================
@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
__test
// and so on ...
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
-How to specify the dependent BMIs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Specifying dependent BMIs
+~~~~~~~~~~~~~~~~~~~~~~~~~
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
-* (1) ``-fprebuilt-module-path=<path/to/directory>``.
-* (2) ``-fmodule-file=<path/to/BMI>`` (Deprecated).
-* (3) ``-fmodule-file=<module-name>=<path/to/BMI>``.
+1. ``-fprebuilt-module-path=<path/to/directory>``.
+2. ``-fmodule-file=<path/to/BMI>`` (Deprecated).
+3. ``-fmodule-file=<module-name>=<path/to/BMI>``.
-The option ``-fprebuilt-module-path`` tells the compiler the path where to
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header
files. The look up rule here is:
+The ``-fprebuilt-module-path`` option specifies the path to search for
+dependent BMIs. 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
+``M:P``, the compiler looks for ``M-P.pcm`` in the directories specified by
+``-fprebuilt-module-path``.
-* (1) When we import module M. The compiler would look up M.pcm in the
directories specified
- by ``-fprebuilt-module-path``.
-* (2) When we import partition module unit M:P. The compiler would look up
M-P.pcm in the
- directories specified by ``-fprebuilt-module-path``.
-
-The option ``-fmodule-file=<path/to/BMI>`` tells the compiler to load the
specified BMI directly.
-The option ``-fmodule-file=<module-name>=<path/to/BMI>`` tells the compiler to
load the specified BMI
-for the module specified by ``<module-name>`` when necessary. The main
difference is that
+The ``-fmodule-file=<path/to/BMI>`` option causes the compiler to load the
+specified BMI directly. The ``-fmodule-file=<module-name>=<path/to/BMI>``
+option causes the compiler to load the specified BMI for the module specified
+by ``<module-name>`` when necessary. The main difference is that
``-fmodule-file=<path/to/BMI>`` will load the BMI eagerly, whereas
-``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,
which is similar
-with ``-fprebuilt-module-path``. The option ``-fmodule-file=<path/to/BMI>``
for named modules is deprecated
-and is planning to be removed in future versions.
+``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,
+which is similar to ``-fprebuilt-module-path``. The
+``-fmodule-file=<path/to/BMI>`` option for named modules is deprecated and will
+be removed in a future version of Clang.
-In case all ``-fprebuilt-module-path=<path/to/directory>``,
``-fmodule-file=<path/to/BMI>`` and
-``-fmodule-file=<module-name>=<path/to/BMI>`` exist, the
``-fmodule-file=<path/to/BMI>`` option
-takes highest precedence and ``-fmodule-file=<module-name>=<path/to/BMI>``
will take the second
-highest precedence.
+When these options are specified in the same invocation of the compiler, the
+``-fmodule-file=<path/to/BMI>`` option takes precedence over
+``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over
+``-fprebuilt-module-path=<path/to/directory>``.
-We need to specify all the dependent (directly and indirectly) BMIs.
-See https://github.com/llvm/llvm-project/issues/62707 for detail.
+Note: you must specify all the (directly or indirectly) dependent BMIs
+explicitly. See https://github.com/llvm/llvm-project/issues/62707 for details.
-When we compile a ``module implementation unit``, we must specify the BMI of
the corresponding
-``primary module interface unit``.
-Since the language specification says a module implementation unit implicitly
imports
-the primary module interface unit.
+When compiling a ``module implementation unit``, the BMI of the corresponding
+``primary module interface unit`` must be specified. This is because a module
+implementation unit implicitly imports the primary module interface unit.
[module.unit]p8
A module-declaration that contains neither an export-keyword nor a
module-partition implicitly
imports the primary module interface unit of the module as if by a
module-import-declaration.
-All of the 3 options ``-fprebuilt-module-path=<path/to/directory>``,
``-fmodule-file=<path/to/BMI>``
-and ``-fmodule-file=<module-name>=<path/to/BMI>`` may occur multiple times.
-For example, the command line to compile ``M.cppm`` in
-the above example could be rewritten into:
+The ``-fprebuilt-module-path=<path/to/directory>``,
``-fmodule-file=<path/to/BMI>``,
+and ``-fmodule-file=<module-name>=<path/to/BMI>`` options may be specified
+multiple times. For example, the command line to compile ``M.cppm`` in
+the previous example could be rewritten as:
.. code-block:: console
$ clang++ -std=c++20 M.cppm --precompile
-fmodule-file=M:interface_part=M-interface_part.pcm
-fmodule-file=M:impl_part=M-impl_part.pcm -o M.pcm
When there are multiple ``-fmodule-file=<module-name>=`` options for the same
-``<module-name>``, the last ``-fmodule-file=<module-name>=`` will override the
previous
-``-fmodule-file=<module-name>=`` options.
+``<module-name>``, the last ``-fmodule-file=<module-name>=`` overrides the
+previous ``-fmodule-file=<module-name>=`` option.
-``-fprebuilt-module-path`` is more convenient and ``-fmodule-file`` is faster
since
-it saves time for file lookup.
+``-fprebuilt-module-path`` is more convenient while ``-fmodule-file`` is faster
+because it saves time for file lookup.
Remember that module units still have an object counterpart to the BMI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is easy to forget to compile BMIs at first since we may envision module
interfaces like headers.
-However, this is not true.
-Module units are translation units. We need to compile them to object files
-and link the object files like the example shows.
+It is easy to forget to compile BMIs at first because module interfaces seem
----------------
erichkeane wrote:
While module interfaces resemble traditional header files, they still require
compilation. Module units are translation units, and need to be compiled to
object files, which need to be linked together as the following examples show.
https://github.com/llvm/llvm-project/pull/90237
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
