[docs] Document the one-phase style compilation to c++ standard modules

[ChuanqiXu]

Summary

This is the followup of D134267. The patch documents the new behavior with D134267.

[avogelsgesang]

clang/docs/StandardCPlusPlusModules.rst

917

937

[ChuanqiXu]

Address comments.

[ChuanqiXu]

Refine the behavior about partitions.

[tschuett]

Thanks for doing this! The traditional Clang Header modules call this implicit and explicit modules.

Feel free to ignore, but I found this awesome article about implicit and explicit modules in Swift. They have same nomenclature and issues.

https://forums.swift.org/t/explicit-module-builds-the-new-swift-driver-and-swiftpm/36990

[ChuanqiXu]

In D134269#3813568, @tschuett wrote:

Thanks for doing this! The traditional Clang Header modules call this implicit and explicit modules.

Feel free to ignore, but I found this awesome article about implicit and explicit modules in Swift. They have same nomenclature and issues.

https://forums.swift.org/t/explicit-module-builds-the-new-swift-driver-and-swiftpm/36990

Thanks! If you have other opinions about the interface, you can discuss it in https://reviews.llvm.org/D134267.

[ChuanqiXu]

Update to reflect the change in D134267

[tahonermann]

clang/docs/StandardCPlusPlusModules.rst

228–229

When an importable module unit is compiled to an object file,
a corresponding BMI is implicitly generated.

233–234

• (1) If a file name is specified with the -fmodule-bmi-output={BMI-destination-path} option, then the BMI will be written to {BMI-destination-path}.

235–237

What happens if the source file name does not have an extension? E.g., for clang -c -std=c++20 -xc++-module file?

235–239

• (2) Otherwise, the BMI will be written to a file within the module cache with a name constructed from the source file name with a .pcm extension. For example, if the source file is M.cppm, then the BMI will be implicitly written to a file named M.pcm in the module cache. See :ref:Module Cache Path<Module Cache Path> for the rules about the module cache.

[ChuanqiXu]

Suspended due to the dependent patches suspended.

clang/docs/StandardCPlusPlusModules.rst

int main() {
     hello();
     return 0;
   }
 
 Then we type:
 
 .. code-block:: console
 
-  $ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
-  $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
+  $ clang++ -std=c++20 Hello.cppm use.cpp -o Hello.out
   $ ./Hello.out
   Hello World!
 
 In this example, we make and use a simple module ``Hello`` which contains only a
 primary module interface unit ``Hello.cppm``.
 
 Then let's see a little bit more complex "hello world" example which uses the 4 kinds of module units.
 

 
 Currently, standard C++ modules are enabled automatically
 if the language standard is ``-std=c++20`` or newer.
 The ``-fmodules-ts`` option is deprecated and is planned to be removed.
 
 How to produce a BMI
 ~~~~~~~~~~~~~~~~~~~~
 
-It is possible to generate a BMI for an importable module unit by specifying the ``--precompile`` option.
+It is possible to generate a BMI explicitly for an importable
+module unit by specifying the ``--precompile`` option.
+
+Also if when we compile an importable module unit to an object file,
+the compiler will generate the corresponding BMI implicitly in the module cache path.
+See :ref:`Module Cache Path<Module Cache Path>`.
+
+The file name for the implicitly generated BMI will be:
+
+* (1) If the module name is specified by `-fmodule-name={module-name}` option,
+  the file name of the BMI will be `{module-name}.pcm` or `{primary-module-name}-{partition-name}.pcm`
+  if the `module-name` specifies a partition name.
+* (2) If `-fmodule-name` is not specified, the file name of the BMI will be
+  the same with the name with source file except with the different suffix `.pcm`.
+  For example, if the source file is `M.cppm`, then the name of the implicitly
+  generated BMI in this manner will be `M.pcm`.
 
 File name requirement
 ~~~~~~~~~~~~~~~~~~~~~
 
 The file name of an ``importable module unit`` should end with ``.cppm``
 (or ``.ccm``, ``.cxxm``, ``.c++m``). The file name of a ``module implementation unit``
 should end with ``.cpp`` (or ``.cc``, ``.cxx``, ``.c++``).
 

 
 .. code-block:: console
 
   $ clang++ -std=c++20 M.cppm --precompile -fmodule-file=M-interface_part.pcm -fmodule-file=M-impl_part.pcm -o M.pcm
 
 ``-fprebuilt-module-path`` is more convenient and ``-fmodule-file`` is faster since
 it saves time for file lookup.
 
+Module Cache Path
+~~~~~~~~~~~~~~~~~
+
+When we compile an importable module unit to an object file directly, the BMI
+will be generated in the module cache path.
+Users can specifiy the module cache path by ``-fmodules-cache-path=/path/`` option.
+If the module cache path is not specified explicitly, the compiler will choose
+the default module cache path.
+
+If we set the environment variable ``CLANG_MODULE_CACHE_PATH``, its value will
+be the default module cache path.
+Otherwise, the default module path is system specified. In Unix systems, its value
+will be ``~/.cache/clang/ModuleCache/``.
+
+If the directory specified by module cache path doesn't exist,
+the compiler will try to create the directory.
+The compiler will emit an error if it fails to create the directory.
+
+The module cache path will be passed to ``-fprebuilt-module-path`` so that
+the translation unit are able to lookup these implicitly generated BMI implicitly.
+
 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.
 

 But we could still save the time for optimizations after IPO and the whole backend.
 
 Overall, at ``O0`` the implementations of functions defined in a module will not impact module users,
 but at higher optimization levels the definitions of such functions are provided to user compilations for the
 purposes of optimization (but definitions of these functions are still not included in the use's object file)-
 this means the build speedup at higher optimization levels may be lower than expected given ``O0`` experience, 
 but does provide by more optimization opportunities.
 
+Why two-phase compilation?
+--------------------------
+
+The readers may notice that the document generates the BMI explicitly.
+We call this manner as two-phase compilation
+(sources to BMIs and BMIs to object files) to disambiguate the traditional
+compilation process (sources to object files directly),
+which we call one-phase compilation.
+
+The two-phase compilation will have higher parallelism than the one-phase compilation.
+Image the following example:
+
+.. code-block:: c++
+
+  // A.cppm
+  export module A;
+  // ...
+
+  // B.cppm
+  export module B;
+  import A;
+
+  // C.cpp
+  import B;
+
+In this example, `C.cpp` depends on Module B and `B.cppm` depends on Module A.
+So the compilation process in one-phase style will be:
+
+.. code-block:: text
+
+  A.cppm --- A.pcm ---> A.o ->
+                               B.cppm --- B.pcm ---> B.o ->
+                                                            C.cppm --- C.pcm ---> C.o
+
+But if it is compiled by the two-phase compilation, the process will be:
+
+.. code-block:: text
+
+  A.cppm --- A.pcm ---> A.o
+                   B.cppm --- B.pcm ---> B.o
+                                    C.cppm --- C.pcm ---> C.o
+
+From the example, we can find the two-phase compilation can bring more parallelism and
+the higher compilation speed.
+Especially, the middle end and the backend usually take much much more time than the frontend.
+So the gap will be larger in larger projects.
+
+So we highly recommend to use two-phase compilation in real workloads
+while the one-phase compilation model are more suitable for quick POC and demo examples.