[clang] [docs] Fix the use of word "dependent" and other typos in the C++ Modules Doc (PR #136719)
Arseniy Zaostrovnykh via cfe-commits
cfe-commits at lists.llvm.org
Wed Apr 23 00:32:21 PDT 2025
https://github.com/necto updated https://github.com/llvm/llvm-project/pull/136719
>From 095e00202104240797e21c941be7f6256850c534 Mon Sep 17 00:00:00 2001
From: Arseniy Zaostrovnykh <necto.ne at gmail.com>
Date: Tue, 22 Apr 2025 15:24:20 +0200
Subject: [PATCH 1/4] [docs] Fix the use of "dependent" and "dependant" in the
C++ Modules Doc
"Dependant BMI" / "Dependent BMI" was used incorrectly in the
documentation:
"Dependent BMI" refers to a BMI that depends on the current TU, but it
was used for the BMI that current TU depends on.
I replaced all the mentions with "BMI dependency".
---
clang/docs/StandardCPlusPlusModules.rst | 37 ++++++++++++-------------
1 file changed, 18 insertions(+), 19 deletions(-)
diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 93edce0cf90b7..8b05984e0d9dd 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -305,17 +305,17 @@ Therefore, none of the following names are valid by default:
Using a reserved module name is strongly discouraged, but
``-Wno-reserved-module-identifier`` can be used to suppress the warning.
-Specifying dependent BMIs
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Specifying BMI dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are 3 ways to specify a dependent BMI:
+There are 3 ways to specify a BMI dependency:
1. ``-fprebuilt-module-path=<path/to/directory>``.
2. ``-fmodule-file=<path/to/BMI>`` (Deprecated).
3. ``-fmodule-file=<module-name>=<path/to/BMI>``.
The ``-fprebuilt-module-path`` option specifies the path to search for
-dependent BMIs. Multiple paths may be specified, similar to using ``-I`` to
+BMI dependencies. Multiple paths may be specified, similar to using ``-I`` to
specify a search path for header files. When importing a module ``M``, the
compiler looks for ``M.pcm`` in the directories specified by
``-fprebuilt-module-path``. Similarly, when importing a partition module unit
@@ -337,9 +337,8 @@ When these options are specified in the same invocation of the compiler, the
``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over
``-fprebuilt-module-path=<path/to/directory>``.
-Note: all dependant BMIs must be specified explicitly, either directly or
-indirectly dependent BMIs explicitly. See
-https://github.com/llvm/llvm-project/issues/62707 for details.
+Note: all BMI dependencies must be specified explicitly, either directly or
+indirectly. See https://github.com/llvm/llvm-project/issues/62707 for details.
When compiling a ``module implementation unit``, the BMI of the corresponding
``primary module interface unit`` must be specified because a module
@@ -1192,14 +1191,14 @@ them to ``your_library_imported.h`` too.
Importing modules
~~~~~~~~~~~~~~~~~
-When there are dependent libraries providing modules, they should be imported
-in your module as well. Many existing libraries will fall into this category
-once the ``std`` module is more widely available.
+When there are library dependencies providing modules, the module dependencies
+should be imported in your module as well. Many existing libraries will fall
+into this category once the ``std`` module is more widely available.
-All dependent libraries providing modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All library dependencies providing modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Of course, most of the complexity disappears if all the dependent libraries
+Of course, most of the complexity disappears if all the library dependencies
provide modules.
Headers need to be converted to include third-party headers conditionally. Then,
@@ -1260,8 +1259,8 @@ Non-exported ``using`` declarations are unnecessary if using implementation
module units. Instead, third-party modules can be imported directly in
implementation module units.
-Partial dependent libraries providing modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Partial library dependencies providing modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the library has to mix the use of ``include`` and ``import`` in its module,
the primary goal is still the removal of duplicated declarations in translation
@@ -1562,11 +1561,11 @@ file as a header. For example:
$ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
$ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
-How to specify dependent BMIs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How to specify BMI dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``-fmodule-file`` can be used to specify a dependent BMI (or multiple times for
-more than one dependent BMI).
+``-fmodule-file`` can be used to specify a BMI dependency (or multiple times for
+more than one BMI dependency).
With the existing implementation, ``-fprebuilt-module-path`` cannot be used for
header units (because they are nominally anonymous). For header units, use
>From 1c7c534bfbda2d1d2f1ceb923970713dc35a2c62 Mon Sep 17 00:00:00 2001
From: Arseniy Zaostrovnykh <necto.ne at gmail.com>
Date: Tue, 22 Apr 2025 15:42:29 +0200
Subject: [PATCH 2/4] minor typos
---
clang/docs/StandardCPlusPlusModules.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 8b05984e0d9dd..1cf6dd7682f35 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -379,7 +379,7 @@ For example, the traditional compilation processes for headers are like:
hdr2.h --, |
src2.cpp -+> clang++ src2.cpp --> src2.o ---'
-And the compilation process for module units are like:
+And the compilation processes for module units are like:
.. code-block:: text
@@ -434,7 +434,7 @@ non-module-unit uses need to be consistent. Consider the following example:
$ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
Clang rejects the example due to the inconsistent language standard modes. Not
-all compiler options are language dialect options, though. For example:
+all compiler options are language-dialect options, though. For example:
.. code-block:: console
@@ -1571,7 +1571,7 @@ With the existing implementation, ``-fprebuilt-module-path`` cannot be used for
header units (because they are nominally anonymous). For header units, use
``-fmodule-file`` to include the relevant PCM file for each header unit.
-This is expect to be solved in a future version of Clang either by the compiler
+This is expected to be solved in a future version of Clang either by the compiler
finding and specifying ``-fmodule-file`` automatically, or by the use of a
module-mapper that understands how to map the header name to their PCMs.
>From 184b4e59bc6ba0a2cf0c70282a5638361a5191f3 Mon Sep 17 00:00:00 2001
From: Arseniy Zaostrovnykh <necto.ne at gmail.com>
Date: Tue, 22 Apr 2025 15:42:50 +0200
Subject: [PATCH 3/4] footnote RST syntax fix
---
clang/docs/StandardCPlusPlusModules.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 1cf6dd7682f35..4e6f0d67ea100 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -464,7 +464,7 @@ translation units.
Source Files Consistency
^^^^^^^^^^^^^^^^^^^^^^^^
-Clang may open the input files\ :sup:`1`` of a BMI during the compilation. This implies that
+Clang may open the input files [1]_ of a BMI during the compilation. This implies that
when Clang consumes a BMI, all the input files need to be present in the original path
and with the original contents.
@@ -476,21 +476,21 @@ When the ``-fmodules-embed-all-files`` flag are enabled, Clang explicitly emits
code into the BMI file, the contents of the BMI file contain a sufficiently verbose
representation to reproduce the original source file.
-:sup:`1`` Input files: The source files which took part in the compilation of the BMI.
-For example:
+.. [1] Input files: The source files which took part in the compilation of the BMI.
+ For example:
-.. code-block:: c++
+ .. code-block:: c++
- // M.cppm
- module;
- #include "foo.h"
- export module M;
+ // M.cppm
+ module;
+ #include "foo.h"
+ export module M;
- // foo.h
- #pragma once
- #include "bar.h"
+ // foo.h
+ #pragma once
+ #include "bar.h"
-The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.
+ The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.
Object definition consistency
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>From d1e80e2f3f526925b5e25aaf7512394c7af026fa Mon Sep 17 00:00:00 2001
From: Arseniy Zaostrovnykh <necto.ne at gmail.com>
Date: Tue, 22 Apr 2025 16:01:30 +0200
Subject: [PATCH 4/4] Clarify what changed and what not
---
clang/docs/StandardCPlusPlusModules.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 4e6f0d67ea100..2ca014f3fd831 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -780,8 +780,8 @@ for the BMI being produced. This ensures that build systems are not required to
transitively imported modules when deciding whether to recompile.
What is considered to be a potential contributory BMIs is currently unspecified.
-However, it is a severe bug for a BMI to remain unchanged following an observable change
-that affects its consumers.
+However, it is a severe bug for a BMI to remain unchanged following an
+observable change in the module source files that affects the module consumers.
Build systems may utilize this optimization by doing an update-if-changed operation to the BMI
that is consumed from the BMI that is output by the compiler.
More information about the cfe-commits
mailing list