================
@@ -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
----------------
ChuanqiXu9 wrote:
I don't feel bad if we want to remove this.
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
