From 046a9910c31e6eeb04f54f59574c74773292d3f0 Mon Sep 17 00:00:00 2001 From: Chuanqi Xu Date: Mon, 16 Jan 2023 16:58:13 +0800 Subject: [PATCH] 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. --- clang/docs/ReleaseNotes.rst | 5 +++++ clang/docs/StandardCPlusPlusModules.rst | 22 +++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index 09133f9..3bbab95 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 `_ + 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 c7c0476..1010948 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 ~~~~~~~~~~~~~~~~~~~~~ -- 2.7.4