[clang] 046a991 - Add Release Notes and Doc for -fmodule-output

[Chuanqi Xu via cfe-commits]

Author: Chuanqi Xu
Date: 2023-01-16T17:01:41+08:00
New Revision: 046a9910c31e6eeb04f54f59574c74773292d3f0

URL: https://github.com/llvm/llvm-project/commit/046a9910c31e6eeb04f54f59574c74773292d3f0
DIFF: https://github.com/llvm/llvm-project/commit/046a9910c31e6eeb04f54f59574c74773292d3f0.diff

LOG: Add Release Notes and Doc for -fmodule-output

As the summary explained in https://reviews.llvm.org/D137058,
the design of `-fmodule-output` changes relatively frequently
so I skipped the release notes and docs for -fmodule-output in the
the patches. And the patches get accepted and landed. The patch adds
the related release notes and docs.

Added: 
    

Modified: 
    clang/docs/ReleaseNotes.rst
    clang/docs/StandardCPlusPlusModules.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 09133f967f01..3bbab951e8a8 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -537,6 +537,11 @@ New Compiler Flags
       int b[0]; // NOT a flexible array member.
     };
 
+- Added ``-fmodule-output`` to enable the one-phase compilation model for
+  standard C++ modules. See
+  `Standard C++ Modules <https://clang.llvm.org/docs/StandardCPlusPlusModules.html>`_
+  for more information.
+
 Deprecated Compiler Flags
 -------------------------
 - ``-enable-trivial-auto-var-init-zero-knowing-it-will-be-removed-from-clang``

diff  --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index c7c04767c7b8..1010948ae91b 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -223,7 +223,27 @@ 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.
+We can generate a BMI for an importable module unit by either ``--precompile``
+or ``-fmodule-output`` flags.
+
+The ``--precompile`` option generates the BMI as the output of the compilation and the output path
+can be specified using the ``-o`` option. 
+
+The ``-fmodule-output`` option generates the BMI as a by-product of the compilation.
+If ``-fmodule-output=`` is specified, the BMI will be emitted the specified location. Then if
+``-fmodule-output`` and ``-c`` are specified, the BMI will be emitted in the directory of the
+output file with the name of the input file with the new extension ``.pcm``. Otherwise, the BMI
+will be emitted in the working directory with the name of the input file with the new extension
+``.pcm``.
+
+The style to generate BMIs by ``--precompile`` is called two-phase compilation since it takes
+2 steps to compile a source file to an object file. The style to generate BMIs by ``-fmodule-output``
+is called one-phase compilation respectively. The one-phase compilation model is simpler
+for build systems to implement and the two-phase compilation has the potential to compile faster due
+to higher parallelism. As an example, if there are two module units A and B, and B depends on A, the
+one-phase compilation model would need to compile them serially, whereas the two-phase compilation
+model may be able to compile them simultaneously if the compilation from A.pcm to A.o takes a long
+time.
 
 File name requirement
 ~~~~~~~~~~~~~~~~~~~~~