2070 lines · plain
1====================2Standard C++ Modules3====================4 5.. contents::6 :local:7 8Introduction9============10 11The term ``module`` is ambiguous, as it is used to mean multiple things in12Clang. For Clang users, a module may refer to an ``Objective-C Module``,13`Clang Module <Modules.html>`_ (also called a ``Clang Header Module``) or a14``C++20 Module`` (or a ``Standard C++ Module``). The implementation of all15these kinds of modules in Clang shares a lot of code, but from the perspective16of users their semantics and command line interfaces are very different. This17document is an introduction to the use of C++20 modules in Clang. In the18remainder of this document, the term ``module`` will refer to Standard C++2019modules and the term ``Clang module`` will refer to the Clang Modules20extension.21 22In terms of the C++ Standard, modules consist of two components: "Named23Modules" or "Header Units". This document covers both.24 25Standard C++ Named modules26==========================27 28In order to better understand the compiler's behavior, it is helpful to29understand some terms and definitions for readers who are not familiar with the30C++ feature. This document is not a tutorial on C++; it only introduces31necessary concepts to better understand use of modules in a project.32 33Background and terminology34--------------------------35 36Module and module unit37~~~~~~~~~~~~~~~~~~~~~~38 39A module consists of one or more module units. A module unit is a special kind40of translation unit. A module unit should almost always start with a module41declaration. The syntax of the module declaration is:42 43.. code-block:: c++44 45 [export] module module_name[:partition_name];46 47Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``48follow the rules for a C++ identifier, except that they may contain one or more49period (``.``) characters. Note that a ``.`` in the name has no semantic50meaning and does not imply any hierarchy.51 52In this document, module units are classified as:53 54* Primary module interface unit55* Module implementation unit56* Module partition interface unit57* Internal module partition unit58 59A primary module interface unit is a module unit whose module declaration is60``export module module_name;`` where ``module_name`` denotes the name of the61module. A module should have one and only one primary module interface unit.62 63A module implementation unit is a module unit whose module declaration is64``module module_name;``. Multiple module implementation units can be declared65in the same module.66 67A module partition interface unit is a module unit whose module declaration is68``export module module_name:partition_name;``. The ``partition_name`` should be69unique within any given module.70 71An internal module partition unit is a module unit whose module72declaration is ``module module_name:partition_name;``. The ``partition_name``73should be unique within any given module.74 75In this document, we use the following terms:76 77* A ``module interface unit`` refers to either a ``primary module interface unit``78 or a ``module partition interface unit``.79 80* An ``importable module unit`` refers to either a ``module interface unit`` or81 an ``internal module partition unit``.82 83* A ``module partition unit`` refers to either a ``module partition interface unit``84 or an ``internal module partition unit``.85 86Built Module Interface87~~~~~~~~~~~~~~~~~~~~~~88 89A ``Built Module Interface`` (or ``BMI``) is the precompiled result of an90importable module unit.91 92Global module fragment93~~~~~~~~~~~~~~~~~~~~~~94 95The ``global module fragment`` (or ``GMF``) is the code between the ``module;``96and the module declaration within a module unit.97 98 99How to build projects using modules100-----------------------------------101 102Quick Start103~~~~~~~~~~~104 105Let's see a "hello world" example that uses modules.106 107.. code-block:: c++108 109 // Hello.cppm110 module;111 #include <iostream>112 export module Hello;113 export void hello() {114 std::cout << "Hello World!\n";115 }116 117 // use.cpp118 import Hello;119 int main() {120 hello();121 return 0;122 }123 124Then, on the command line, invoke Clang like:125 126.. code-block:: console127 128 $ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm129 $ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out130 $ ./Hello.out131 Hello World!132 133In this example, we make and use a simple module ``Hello`` which contains only a134primary module interface unit named ``Hello.cppm``.135 136A more complex "hello world" example which uses the 4 kinds of module units is:137 138.. code-block:: c++139 140 // M.cppm141 export module M;142 export import :interface_part;143 import :impl_part;144 export void Hello();145 146 // interface_part.cppm147 export module M:interface_part;148 export void World();149 150 // impl_part.cppm151 module;152 #include <iostream>153 #include <string>154 module M:impl_part;155 import :interface_part;156 157 std::string W = "World.";158 void World() {159 std::cout << W << std::endl;160 }161 162 // Impl.cpp163 module;164 #include <iostream>165 module M;166 void Hello() {167 std::cout << "Hello ";168 }169 170 // User.cpp171 import M;172 int main() {173 Hello();174 World();175 return 0;176 }177 178Then, back on the command line, invoke Clang with:179 180.. code-block:: console181 182 # Precompiling the module183 $ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm184 $ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm185 $ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm186 $ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o187 188 # Compiling the user189 $ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o190 191 # Compiling the module and linking it together192 $ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o193 $ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o194 $ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o195 $ clang++ User.o M-interface_part.o M-impl_part.o M.o Impl.o -o a.out196 197We explain the options in the following sections.198 199How to enable standard C++ modules200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~201 202Standard C++ modules are enabled automatically when the language standard mode203is ``-std=c++20`` or newer.204 205How to produce a BMI206~~~~~~~~~~~~~~~~~~~~207 208To generate a BMI for an importable module unit, use either the ``--precompile``209or ``-fmodule-output`` command line options.210 211The ``--precompile`` option generates the BMI as the output of the compilation212with the output path specified using the ``-o`` option.213 214The ``-fmodule-output`` option generates the BMI as a by-product of the215compilation. If ``-fmodule-output=`` is specified, the BMI will be emitted to216the specified location. If ``-fmodule-output`` and ``-c`` are specified, the217BMI will be emitted in the directory of the output file with the name of the218input file with the extension ``.pcm``. Otherwise, the BMI will be emitted in219the working directory with the name of the input file with the extension220``.pcm``.221 222Generating BMIs with ``--precompile`` is referred to as two-phase compilation223because it takes two steps to compile a source file to an object file.224Generating BMIs with ``-fmodule-output`` is called one-phase compilation. The225one-phase compilation model is simpler for build systems to implement while the226two-phase compilation has the potential to compile faster due to higher227parallelism. As an example, if there are two module units ``A`` and ``B``, and228``B`` depends on ``A``, the one-phase compilation model needs to compile them229serially, whereas the two-phase compilation model can be compiled as230soon as ``A.pcm`` is available, and thus can be compiled simultaneously with the231``A.pcm`` to ``A.o`` compilation step.232 233File name requirements234~~~~~~~~~~~~~~~~~~~~~~235 236By convention, ``importable module unit`` files should use ``.cppm`` (or237``.ccm``, ``.cxxm``, or ``.c++m``) as a file extension.238``Module implementation unit`` files should use ``.cpp`` (or ``.cc``, ``.cxx``,239or ``.c++``) as a file extension.240 241A BMI should use ``.pcm`` as a file extension. The file name of the BMI for a242``primary module interface unit`` should be ``module_name.pcm``. The file name243of a BMI for a ``module partition unit`` should be244``module_name-partition_name.pcm``.245 246Clang may fail to build the module if different extensions are used. For247example, if the filename of an ``importable module unit`` ends with ``.cpp``248instead of ``.cppm``, then Clang cannot generate a BMI for the249``importable module unit`` with the ``--precompile`` option because the250``--precompile`` option would only run the preprocessor (``-E``). If using a251different extension than the conventional one for an ``importable module unit``252you can specify ``-x c++-module`` before the file. For example,253 254.. code-block:: c++255 256 // Hello.cpp257 module;258 #include <iostream>259 export module Hello;260 export void hello() {261 std::cout << "Hello World!\n";262 }263 264 // use.cpp265 import Hello;266 int main() {267 hello();268 return 0;269 }270 271In this example, the extension used by the ``module interface`` is ``.cpp``272instead of ``.cppm``, so it cannot be compiled like the previous example, but273it can be compiled with:274 275.. code-block:: console276 277 $ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm278 $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out279 $ ./Hello.out280 Hello World!281 282Module name requirements283~~~~~~~~~~~~~~~~~~~~~~~~284 285..286 287 [module.unit]p1:288 289 All module-names either beginning with an identifier consisting of std followed by zero290 or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not291 be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved292 module-name is a reserved identifier, the module name is reserved for use by C++ implementations;293 otherwise it is reserved for future standardization.294 295Therefore, none of the following names are valid by default:296 297.. code-block:: text298 299 std300 std1301 std.foo302 __test303 // and so on ...304 305Using a reserved module name is strongly discouraged, but306``-Wno-reserved-module-identifier`` can be used to suppress the warning.307 308Specifying BMI dependencies309~~~~~~~~~~~~~~~~~~~~~~~~~~~310 311There are 3 ways to specify a BMI dependency:312 3131. ``-fprebuilt-module-path=<path/to/directory>``.3142. ``-fmodule-file=<path/to/BMI>`` (Deprecated).3153. ``-fmodule-file=<module-name>=<path/to/BMI>``.316 317The ``-fprebuilt-module-path`` option specifies the path to search for318BMI dependencies. Multiple paths may be specified, similar to using ``-I`` to319specify a search path for header files. When importing a module ``M``, the320compiler looks for ``M.pcm`` in the directories specified by321``-fprebuilt-module-path``. Similarly, when importing a partition module unit322``M:P``, the compiler looks for ``M-P.pcm`` in the directories specified by323``-fprebuilt-module-path``.324 325The ``-fmodule-file=<path/to/BMI>`` option causes the compiler to load the326specified BMI directly. The ``-fmodule-file=<module-name>=<path/to/BMI>``327option causes the compiler to load the specified BMI for the module specified328by ``<module-name>`` when necessary. The main difference is that329``-fmodule-file=<path/to/BMI>`` will load the BMI eagerly, whereas330``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,331as will ``-fprebuilt-module-path``. The ``-fmodule-file=<path/to/BMI>`` option332for named modules is deprecated and will be removed in a future version of333Clang.334 335When these options are specified in the same invocation of the compiler, the336``-fmodule-file=<path/to/BMI>`` option takes precedence over337``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over338``-fprebuilt-module-path=<path/to/directory>``.339 340Note: all BMI dependencies must be specified explicitly, either directly or341indirectly. See https://github.com/llvm/llvm-project/issues/62707 for details.342 343When compiling a ``module implementation unit``, the BMI of the corresponding344``primary module interface unit`` must be specified because a module345implementation unit implicitly imports the primary module interface unit.346 347 [module.unit]p8348 349 A module-declaration that contains neither an export-keyword nor a module-partition implicitly350 imports the primary module interface unit of the module as if by a module-import-declaration.351 352The ``-fprebuilt-module-path=<path/to/directory>``, ``-fmodule-file=<path/to/BMI>``,353and ``-fmodule-file=<module-name>=<path/to/BMI>`` options may be specified354multiple times. For example, the command line to compile ``M.cppm`` in355the previous example could be rewritten as:356 357.. code-block:: console358 359 $ 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.pcm360 361When there are multiple ``-fmodule-file=<module-name>=`` options for the same362``<module-name>``, the last ``-fmodule-file=<module-name>=`` overrides the363previous ``-fmodule-file=<module-name>=`` option.364 365Remember that module units still have an object counterpart to the BMI366~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~367 368While module interfaces resemble traditional header files, they still require369compilation. Module units are translation units, and need to be compiled to370object files, which then need to be linked together as the following examples371show.372 373For example, the traditional compilation processes for headers are like:374 375.. code-block:: text376 377 src1.cpp -+> clang++ src1.cpp --> src1.o ---,378 hdr1.h --' +-> clang++ src1.o src2.o -> executable379 hdr2.h --, |380 src2.cpp -+> clang++ src2.cpp --> src2.o ---'381 382And the compilation processes for module units are like:383 384.. code-block:: text385 386 src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,387 (header unit) hdr1.h -> clang++ hdr1.h ... -> hdr1.pcm --' +-> clang++ src1.o mod1.o src2.o -> executable388 mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+389 src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'390 391As the diagrams show, we need to compile the BMI from module units to object392files and then link the object files. (However, this cannot be done for the BMI393from header units. See the section on :ref:`header units <header-units>` for394more details.)395 396BMIs cannot be shipped in an archive to create a module library. Instead, the397BMIs(``*.pcm``) are compiled into object files(``*.o``) and those object files398are added to the archive instead.399 400clang-cl401~~~~~~~~402 403``clang-cl`` supports the same options as ``clang++`` for modules as detailed above;404there is no need to prefix these options with ``/clang:``. Note that ``cl.exe``405`options to emit/consume IFC files <https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/>` are *not* supported.406The resulting precompiled modules are also not compatible for use with ``cl.exe``.407 408We recommend that build system authors use the above-mentioned ``clang++`` options with ``clang-cl`` to build modules.409 410Consistency Requirements411~~~~~~~~~~~~~~~~~~~~~~~~412 413Modules can be viewed as a kind of cache to speed up compilation. Thus, like414other caching techniques, it is important to maintain cache consistency, which415is why Clang does very strict checking for consistency.416 417Options consistency418^^^^^^^^^^^^^^^^^^^419 420Compiler options related to the language dialect for a module unit and its421non-module-unit uses need to be consistent. Consider the following example:422 423.. code-block:: c++424 425 // M.cppm426 export module M;427 428 // Use.cpp429 import M;430 431.. code-block:: console432 433 $ clang++ -std=c++20 M.cppm --precompile -o M.pcm434 $ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.435 436Clang rejects the example due to the inconsistent language standard modes. Not437all compiler options are language-dialect options, though. For example:438 439.. code-block:: console440 441 $ clang++ -std=c++20 M.cppm --precompile -o M.pcm442 # Inconsistent optimization level.443 $ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.444 # Inconsistent debugging level.445 $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.446 447Although the optimization and debugging levels are inconsistent, these448compilations are accepted because the compiler options do not impact the449language dialect.450 451Note that the compiler **currently** doesn't reject inconsistent macro452definitions (this may change in the future). For example:453 454.. code-block:: console455 456 $ clang++ -std=c++20 M.cppm --precompile -o M.pcm457 # Inconsistent optimization level.458 $ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.459 460Currently, Clang accepts the above example, though it may produce surprising461results if the debugging code depends on consistent use of ``NDEBUG`` in other462translation units.463 464Source Files Consistency465^^^^^^^^^^^^^^^^^^^^^^^^466 467Clang may open the input files [1]_ of a BMI during the compilation. This implies that468when Clang consumes a BMI, all the input files need to be present in the original path469and with the original contents.470 471To overcome these requirements and simplify cases like distributed builds and sandboxed472builds, users can use the ``-fmodules-embed-all-files`` flag to embed all input files473into the BMI so that Clang does not need to open the corresponding file on disk.474 475When the ``-fmodules-embed-all-files`` flag is enabled, Clang explicitly emits the source476code into the BMI file; the BMI file contains a sufficiently verbose477representation to reproduce the original source file.478 479.. [1] Input files: The source files which took part in the compilation of the BMI.480 For example:481 482 .. code-block:: c++483 484 // M.cppm485 module;486 #include "foo.h"487 export module M;488 489 // foo.h490 #pragma once491 #include "bar.h"492 493 The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.494 495Object definition consistency496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^497 498The C++ language requires that declarations of the same entity in different499translation units have the same definition, which is known as the One500Definition Rule (ODR). Without modules, the compiler cannot perform strong ODR501violation checking because it only sees one translation unit at a time. With502the use of modules, the compiler can perform checks for ODR violations across503translation units.504 505However, the current ODR checking mechanisms are not perfect. There are a506significant number of false positive ODR violation diagnostics, where the507compiler incorrectly diagnoses two identical declarations as having different508definitions. Further, true positive ODR violations are not always reported.509 510To give a better user experience, improve compilation performance, and for511consistency with MSVC, ODR checking of declarations in the global module512fragment is disabled by default. These checks can be enabled by specifying513``-Xclang -fno-skip-odr-check-in-gmf`` when compiling. If the check is enabled514and you encounter incorrect or missing diagnostics, please report them via the515`community issue tracker <https://github.com/llvm/llvm-project/issues/>`_.516 517Privacy Issue518-------------519 520BMIs are not and should not be treated as an information hiding mechanism.521They should always be assumed to contain all the information that was used to522create them, in a recoverable form.523 524ABI Impacts525-----------526 527This section describes the new ABI changes brought by modules. Only changes to528the Itanium C++ ABI are covered.529 530Name Mangling531~~~~~~~~~~~~~532 533The declarations in a module unit which are not in the global module fragment534have new linkage names.535 536For example,537 538.. code-block:: c++539 540 export module M;541 namespace NS {542 export int foo();543 }544 545The linkage name of ``NS::foo()`` is ``_ZN2NSW1M3fooEv``. This couldn't be546demangled by previous versions of the debugger or demangler. As of LLVM 15.x,547``llvm-cxxfilt`` can be used to demangle this:548 549.. code-block:: console550 551 $ llvm-cxxfilt _ZN2NSW1M3fooEv552 NS::foo@M()553 554The result should be read as ``NS::foo()`` in module ``M``.555 556The ABI implies that something cannot be declared in a module unit and defined557in a non-module unit (or vice-versa), as this would result in linking errors.558 559Despite this, it is possible to implement declarations with a compatible ABI in560a module unit by using a language linkage specifier because the declarations in561the language linkage specifier are attached to the global module fragment. For562example:563 564.. code-block:: c++565 566 export module M;567 namespace NS {568 export extern "C++" int foo();569 }570 571Now the linkage name of ``NS::foo()`` will be ``_ZN2NS3fooEv``.572 573Module Initializers574~~~~~~~~~~~~~~~~~~~575 576All importable module units are required to emit an initializer function to577handle the dynamic initialization of non-inline variables in the module unit.578The importable module unit has to emit the initializer even if there is no579dynamic initialization; otherwise, the importer may call a nonexistent580function. The initializer function emits calls to imported modules first581followed by calls to all of the dynamic initializers in the current module582unit.583 584Translation units that explicitly or implicitly import a named module must call585the initializer functions of the imported named module within the sequence of586the dynamic initializers in the translation unit. Initializations of entities587at namespace scope are appearance-ordered. This (recursively) extends to588imported modules at the point of appearance of the import declaration.589 590If the imported module is known to be empty, the call to its initializer may be591omitted. Additionally, if the imported module is known to have already been592imported, the call to its initializer may be omitted.593 594Reduced BMI595-----------596 597To support the two-phase compilation model, Clang puts everything needed to598produce an object into the BMI. However, other consumers of the BMI generally599don't need that information. This makes the BMI larger and may introduce600unnecessary dependencies for the BMI. To mitigate the problem, Clang has a601compiler option to reduce the information contained in the BMI. These two602formats are known as Full BMI and Reduced BMI, respectively.603 604Users can use the ``-fmodules-reduced-bmi`` option to produce a605Reduced BMI.606 607For the one-phase compilation model (CMake implements this model), with608``-fmodules-reduced-bmi``, the generated BMI will be a Reduced609BMI automatically. (The output path of the BMI is specified by610``-fmodule-output=`` as usual with the one-phase compilation model).611 612It is also possible to produce a Reduced BMI with the two-phase compilation613model. When ``-fmodules-reduced-bmi``, ``--precompile``, and614``-fmodule-output=`` are specified, the generated BMI specified by ``-o`` will615be a full BMI and the BMI specified by ``-fmodule-output=`` will be a Reduced616BMI. The dependency graph in this case would look like:617 618.. code-block:: none619 620 module-unit.cppm --> module-unit.full.pcm -> module-unit.o621 |622 -> module-unit.reduced.pcm -> consumer1.cpp623 -> consumer2.cpp624 -> ...625 -> consumer_n.cpp626 627Clang does not emit diagnostics when ``-fmodules-reduced-bmi`` is628used with a non-module unit. This design permits users of the one-phase629compilation model to try using reduced BMIs without needing to modify the build630system. The two-phase compilation module requires build system support.631 632In a Reduced BMI, Clang does not emit unreachable entities from the global633module fragment, or definitions of non-inline functions and non-inline634variables. This may not be a transparent change.635 636Consider the following example:637 638.. code-block:: c++639 640 // foo.h641 namespace N {642 struct X {};643 int d();644 int e();645 inline int f(X, int = d()) { return e(); }646 int g(X);647 int h(X);648 }649 650 // M.cppm651 module;652 #include "foo.h"653 export module M;654 template<typename T> int use_f() {655 N::X x; // N::X, N, and :: are decl-reachable from use_f656 return f(x, 123); // N::f is decl-reachable from use_f,657 // N::e is indirectly decl-reachable from use_f658 // because it is decl-reachable from N::f, and659 // N::d is decl-reachable from use_f660 // because it is decl-reachable from N::f661 // even though it is not used in this call662 }663 template<typename T> int use_g() {664 N::X x; // N::X, N, and :: are decl-reachable from use_g665 return g((T(), x)); // N::g is not decl-reachable from use_g666 }667 template<typename T> int use_h() {668 N::X x; // N::X, N, and :: are decl-reachable from use_h669 return h((T(), x)); // N::h is not decl-reachable from use_h, but670 // N::h is decl-reachable from use_h<int>671 }672 int k = use_h<int>();673 // use_h<int> is decl-reachable from k, so674 // N::h is decl-reachable from k675 676 // M-impl.cpp677 module M;678 int a = use_f<int>(); // OK679 int b = use_g<int>(); // error: no viable function for call to g;680 // g is not decl-reachable from purview of681 // module M's interface, so is discarded682 int c = use_h<int>(); // OK683 684In the above example, the function definition of ``N::g`` is elided from the685Reduced BMI of ``M.cppm``. Then the use of ``use_g<int>`` in ``M-impl.cpp``686fails to instantiate. For such issues, users can add references to ``N::g`` in687the `module purview <https://eel.is/c++draft/module.unit#5>`_ of ``M.cppm`` to688ensure it is reachable, e.g. ``using N::g;``.689 690As of Clang 22.x, the Reduced BMI is enabled by default. You may still want to691use Full BMI with ``-fno-modules-reduced-bmi`` in the following case:6921. Your build system uses two-phase compilation, but it hasn't adjusted the693implementation for reduced BMI.6942. You encounter a regression with Reduced BMI that you cannot work around. Please695report an issue for this case.696 697Experimental Non-Cascading Changes698----------------------------------699 700This section is primarily for build system vendors. For end compiler users,701if you don't want to read it all, this is helpful to reduce recompilations.702We encourage build system vendors and end users to try this out and bring feedback.703 704Before Clang 19, a change in BMI of any (transitive) dependency would cause the705outputs of the BMI to change. Starting with Clang 19, changes to non-direct706dependencies should not directly affect the output BMI, unless they affect the707results of the compilations. We expect that there are many more opportunities708for this optimization than we currently have realized and would appreciate709feedback about missed optimization opportunities. For example,710 711.. code-block:: c++712 713 // m-partA.cppm714 export module m:partA;715 716 // m-partB.cppm717 export module m:partB;718 export int getB() { return 44; }719 720 // m.cppm721 export module m;722 export import :partA;723 export import :partB;724 725 // useBOnly.cppm726 export module useBOnly;727 import m;728 export int B() {729 return getB();730 }731 732 // Use.cc733 import useBOnly;734 int get() {735 return B();736 }737 738To compile the project (for brevity, some commands are omitted.):739 740.. code-block:: console741 742 $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm743 $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm744 $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.745 $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.746 $ md5sum useBOnly.pcm747 07656bf4a6908626795729295f9608da useBOnly.pcm748 749If the interface of ``m-partA.cppm`` is changed to:750 751.. code-block:: c++752 753 // m-partA.v1.cppm754 export module m:partA;755 export int getA() { return 43; }756 757and the BMI for ``useBOnly`` is recompiled as in:758 759.. code-block:: console760 761 $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm762 $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm763 $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.764 $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.765 $ md5sum useBOnly.pcm766 07656bf4a6908626795729295f9608da useBOnly.pcm767 768then the contents of ``useBOnly.pcm`` remain unchanged.769Consequently, if the build system only bases recompilation decisions on directly imported modules,770it becomes possible to skip the recompilation of ``Use.cc``.771It should be fine because the altered interfaces do not affect ``Use.cc`` in any way;772the changes do not cascade.773 774When ``Clang`` generates a BMI, it records the hash values of all potentially contributory BMIs775for the BMI being produced. This ensures that build systems are not required to consider776transitively imported modules when deciding whether to recompile.777 778What is considered to be a potential contributory BMIs is currently unspecified.779However, it is a severe bug for a BMI to remain unchanged following an780observable change in the module source files that affects the module consumers.781 782Build systems may utilize this optimization by doing an update-if-changed operation to the BMI783that is consumed from the BMI that is output by the compiler.784 785We encourage build systems to add an experimental mode that786reuses the cached BMI when **direct** dependencies did not change,787even if **transitive** dependencies did change.788 789Given that there are potential compiler bugs, we recommend that build systems790support this feature as a configurable option so that users791can go back to the transitive change mode safely at any time.792 793Interactions with Reduced BMI794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~795 796With reduced BMI, non-cascading changes can be more powerful. For example,797 798.. code-block:: c++799 800 // A.cppm801 export module A;802 export int a() { return 44; }803 804 // B.cppm805 export module B;806 import A;807 export int b() { return a(); }808 809.. code-block:: console810 811 $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o812 $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm813 $ md5sum B.pcm814 6c2bd452ca32ab418bf35cd141b060b9 B.pcm815 816And let's change the implementation for ``A.cppm`` to:817 818.. code-block:: c++819 820 export module A;821 int a_impl() { return 99; }822 export int a() { return a_impl(); }823 824and recompile the example:825 826.. code-block:: console827 828 $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o829 $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm830 $ md5sum B.pcm831 6c2bd452ca32ab418bf35cd141b060b9 B.pcm832 833We should find the contents of ``B.pcm`` remain the same. In this case, the build system is834allowed to skip recompilations of TUs which solely and directly depend on module ``B``.835 836This only happens with a reduced BMI. With reduced BMIs, we won't record the function body837of ``int b()`` in the BMI for ``B`` so that the module ``A`` doesn't contribute to the BMI of ``B``838and we have less dependencies.839 840Performance Tips841----------------842 843Reduce duplications844~~~~~~~~~~~~~~~~~~~845 846While it is valid to have duplicated declarations in the global module fragments847of different module units, it is not free for Clang to deal with the duplicated848declarations. A translation unit will compile more slowly if there are a lot of849duplicated declarations between the translation unit and modules it imports.850For example:851 852.. code-block:: c++853 854 // M-partA.cppm855 module;856 #include "big.header.h"857 export module M:partA;858 ...859 860 // M-partB.cppm861 module;862 #include "big.header.h"863 export module M:partB;864 ...865 866 // other partitions867 ...868 869 // M-partZ.cppm870 module;871 #include "big.header.h"872 export module M:partZ;873 ...874 875 // M.cppm876 export module M;877 export import :partA;878 export import :partB;879 ...880 export import :partZ;881 882 // use.cpp883 import M;884 ... // use declarations from module M.885 886When ``big.header.h`` is big enough and there are a lot of partitions, the887compilation of ``use.cpp`` may be significantly slower than the following888approach:889 890.. code-block:: c++891 892 module;893 #include "big.header.h"894 export module m:big.header.wrapper;895 export ... // export the needed declarations896 897 // M-partA.cppm898 export module M:partA;899 import :big.header.wrapper;900 ...901 902 // M-partB.cppm903 export module M:partB;904 import :big.header.wrapper;905 ...906 907 // other partitions908 ...909 910 // M-partZ.cppm911 export module M:partZ;912 import :big.header.wrapper;913 ...914 915 // M.cppm916 export module M;917 export import :partA;918 export import :partB;919 ...920 export import :partZ;921 922 // use.cpp923 import M;924 ... // use declarations from module M.925 926Reducing the duplication from textual includes is what improves compile-time927performance.928 929To help users to identify such issues, we add a warning ``-Wdecls-in-multiple-modules``.930This warning is disabled by default and it needs to be explicitly enabled or by ``-Weverything``.931 932Transitioning to modules933------------------------934 935It is best for new code and libraries to use modules from the start if936possible. However, it may be a breaking change for existing code or libraries937to switch to modules. As a result, many existing libraries need to provide938both headers and module interfaces for a while to not break existing users.939 940This section provides some suggestions on how to ease the transition process941for existing libraries. **Note that this information is only intended as942guidance, rather than as requirements to use modules in Clang.** It presumes943the project is starting with no module-based dependencies.944 945ABI non-breaking styles946~~~~~~~~~~~~~~~~~~~~~~~947 948export-using style949^^^^^^^^^^^^^^^^^^950 951.. code-block:: c++952 953 module;954 #include "header_1.h"955 #include "header_2.h"956 ...957 #include "header_n.h"958 export module your_library;959 export namespace your_namespace {960 using decl_1;961 using decl_2;962 ...963 using decl_n;964 }965 966This example shows how to include all the headers containing declarations which967need to be exported, and uses `using` declarations in an `export` block to968produce the module interface.969 970export extern-C++ style971^^^^^^^^^^^^^^^^^^^^^^^972 973.. code-block:: c++974 975 module;976 #include "third_party/A/headers.h"977 #include "third_party/B/headers.h"978 ...979 #include "third_party/Z/headers.h"980 export module your_library;981 #define IN_MODULE_INTERFACE982 extern "C++" {983 #include "header_1.h"984 #include "header_2.h"985 ...986 #include "header_n.h"987 }988 989Headers (from ``header_1.h`` to ``header_n.h``) need to define the macro:990 991.. code-block:: c++992 993 #ifdef IN_MODULE_INTERFACE994 #define EXPORT export995 #else996 #define EXPORT997 #endif998 999and put ``EXPORT`` on the declarations you want to export.1000 1001Also, it is recommended to refactor headers to include third-party headers1002conditionally:1003 1004.. code-block:: c++1005 1006 #ifndef IN_MODULE_INTERFACE1007 #include "third_party/A/headers.h"1008 #endif1009 1010 #include "header_x.h"1011 1012 ...1013 1014This can be helpful because it gives better diagnostic messages if the module1015interface unit is not properly updated when modifying code.1016 1017This approach works because the declarations with language linkage are attached1018to the global module. Thus, the ABI of the modular form of the library does not1019change.1020 1021While this style is more involved than the export-using style, it makes it1022easier to further refactor the library to other styles.1023 1024ABI breaking style1025~~~~~~~~~~~~~~~~~~1026 1027The term ``ABI breaking`` may sound like a bad approach. However, this style1028forces consumers of the library use it in a consistent way. e.g., either always1029include headers for the library or always import modules. The style prevents1030the ability to mix includes and imports for the library.1031 1032The pattern for ABI breaking style is similar to the export extern-C++ style.1033 1034.. code-block:: c++1035 1036 module;1037 #include "third_party/A/headers.h"1038 #include "third_party/B/headers.h"1039 ...1040 #include "third_party/Z/headers.h"1041 export module your_library;1042 #define IN_MODULE_INTERFACE1043 #include "header_1.h"1044 #include "header_2.h"1045 ...1046 #include "header_n.h"1047 1048 #if the number of .cpp files in your project are small1049 module :private;1050 #include "source_1.cpp"1051 #include "source_2.cpp"1052 ...1053 #include "source_n.cpp"1054 #else // the number of .cpp files in your project are a lot1055 // Using all the declarations from third-party libraries which are1056 // used in the .cpp files.1057 namespace third_party_namespace {1058 using third_party_decl_used_in_cpp_1;1059 using third_party_decl_used_in_cpp_2;1060 ...1061 using third_party_decl_used_in_cpp_n;1062 }1063 #endif1064 1065(And add `EXPORT` and conditional include to the headers as suggested in the1066export extern-C++ style section.)1067 1068The ABI with modules is different and thus we need to compile the source files1069into the new ABI. This is done by an additional part of the interface unit:1070 1071.. code-block:: c++1072 1073 #if the number of .cpp files in your project are small1074 module :private;1075 #include "source_1.cpp"1076 #include "source_2.cpp"1077 ...1078 #include "source_n.cpp"1079 #else // the number of .cpp files in your project are a lot1080 // Using all the declarations from third-party libraries which are1081 // used in the .cpp files.1082 namespace third_party_namespace {1083 using third_party_decl_used_in_cpp_1;1084 using third_party_decl_used_in_cpp_2;1085 ...1086 using third_party_decl_used_in_cpp_n;1087 }1088 #endif1089 1090If the number of source files is small, everything can be put in the private1091module fragment directly (it is recommended to add conditional includes to the1092source files as well). However, compile time performance will be bad if there1093are a lot of source files to compile.1094 1095**Note that the private module fragment can only be in the primary module1096interface unit and the primary module interface unit containing the private1097module fragment should be the only module unit of the corresponding module.**1098 1099In this case, source files (.cpp files) must be converted to module1100implementation units:1101 1102.. code-block:: c++1103 1104 #ifndef IN_MODULE_INTERFACE1105 // List all the includes here.1106 #include "third_party/A/headers.h"1107 ...1108 #include "header.h"1109 #endif1110 1111 module your_library;1112 1113 // Following off should be unchanged.1114 ...1115 1116The module implementation unit will import the primary module implicitly. Do1117not include any headers in the module implementation units as it avoids1118duplicated declarations between translation units. This is why non-exported1119using declarations should be added from third-party libraries in the primary1120module interface unit.1121 1122If the library is provided as ``libyour_library.so``, a modular library (e.g.,1123``libyour_library_modules.so``) may also need to be provided for ABI1124compatibility.1125 1126What if there are headers only included by the source files1127^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1128 1129The above practice may be problematic if there are headers only included by the1130source files. When using a private module fragment, this issue may be solved by1131including those headers in the private module fragment. While it is OK to solve1132it by including the implementation headers in the module purview when using1133implementation module units, it may be suboptimal because the primary module1134interface units now contain entities that do not belong to the interface.1135 1136This can potentially be improved by introducing a module partition1137implementation unit. An internal module partition unit is an importable1138module unit which is internal to the module itself.1139 1140Providing a header to skip parsing redundant headers1141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1142 1143Many redeclarations shared between translation units cause Clang to have1144slower compile-time performance. Further, there are known issues with1145`include after import <https://github.com/llvm/llvm-project/issues/61465>`_.1146Even when that issue is resolved, users may still get slower compilation speed1147and larger BMIs. For these reasons, it is recommended to not include headers1148after importing the corresponding module. However, it is not always easy if the1149library is included by other dependencies, as in:1150 1151.. code-block:: c++1152 1153 #include "third_party/A.h" // #include "your_library/a_header.h"1154 import your_library;1155 1156or1157 1158.. code-block:: c++1159 1160 import your_library;1161 #include "third_party/A.h" // #include "your_library/a_header.h"1162 1163For such cases, it is best if the library providing both module and header1164interfaces also provides a header which skips parsing so that the library can1165be imported with the following approach that skips redundant redeclarations:1166 1167.. code-block:: c++1168 1169 import your_library;1170 #include "your_library_imported.h"1171 #include "third_party/A.h" // #include "your_library/a_header.h" but got skipped1172 1173The implementation of ``your_library_imported.h`` can be a set of controlling1174macros or an overall controlling macro if using `#pragma once`. Then headers1175can be refactored to:1176 1177.. code-block:: c++1178 1179 #pragma once1180 #ifndef YOUR_LIBRARY_IMPORTED1181 ...1182 #endif1183 1184If the modules imported by the library provide such headers, remember to add1185them to ``your_library_imported.h`` too.1186 1187Importing modules1188~~~~~~~~~~~~~~~~~1189 1190When there are library dependencies providing modules, the module dependencies1191should be imported in your module as well. Many existing libraries will fall1192into this category once the ``std`` module is more widely available.1193 1194All library dependencies providing modules1195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1196 1197Of course, most of the complexity disappears if all the library dependencies1198provide modules.1199 1200Headers need to be converted to include third-party headers conditionally. Then,1201for the export-using style:1202 1203.. code-block:: c++1204 1205 module;1206 import modules_from_third_party;1207 #define IN_MODULE_INTERFACE1208 #include "header_1.h"1209 #include "header_2.h"1210 ...1211 #include "header_n.h"1212 export module your_library;1213 export namespace your_namespace {1214 using decl_1;1215 using decl_2;1216 ...1217 using decl_n;1218 }1219 1220or, for the export extern-C++ style:1221 1222.. code-block:: c++1223 1224 export module your_library;1225 import modules_from_third_party;1226 #define IN_MODULE_INTERFACE1227 extern "C++" {1228 #include "header_1.h"1229 #include "header_2.h"1230 ...1231 #include "header_n.h"1232 }1233 1234or, for the ABI-breaking style,1235 1236.. code-block:: c++1237 1238 export module your_library;1239 import modules_from_third_party;1240 #define IN_MODULE_INTERFACE1241 #include "header_1.h"1242 #include "header_2.h"1243 ...1244 #include "header_n.h"1245 1246 #if the number of .cpp files in your project are small1247 module :private;1248 #include "source_1.cpp"1249 #include "source_2.cpp"1250 ...1251 #include "source_n.cpp"1252 #endif1253 1254Non-exported ``using`` declarations are unnecessary if using implementation1255module units. Instead, third-party modules can be imported directly in1256implementation module units.1257 1258Partial library dependencies providing modules1259^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1260 1261If the library has to mix the use of ``include`` and ``import`` in its module,1262the primary goal is still the removal of duplicated declarations in translation1263units as much as possible. If the imported modules provide headers to skip1264parsing their headers, those should be included after the import. If the1265imported modules don't provide such a header, one can be made manually for1266improved compile time performance.1267 1268Reachability of internal partition units1269----------------------------------------1270 1271The internal partition units are sometimes called implementation partition units in other documentation.1272However, the name may be confusing since implementation partition units are not implementation1273units.1274 1275According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and1276`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):1277 1278 A translation unit U is necessarily reachable from a point P if U is a module1279 interface unit on which the translation unit containing P has an interface1280 dependency, or the translation unit containing P imports U, in either case1281 prior to P.1282 1283 All translation units that are necessarily reachable are reachable. Additional1284 translation units on which the point within the program has an interface1285 dependency may be considered reachable, but it is unspecified which are and1286 under what circumstances.1287 1288For example,1289 1290.. code-block:: c++1291 1292 // a.cpp1293 import B;1294 int main()1295 {1296 g<void>();1297 }1298 1299 // b.cppm1300 export module B;1301 import :C;1302 export template <typename T> inline void g() noexcept1303 {1304 return f<T>();1305 }1306 1307 // c.cppm1308 module B:C;1309 template<typename> inline void f() noexcept {}1310 1311The internal partition unit ``c.cppm`` is not necessarily reachable by1312``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``1313doesn't import ``c.cppm``. This leaves it up to the compiler to decide if1314``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that1315indirectly imported internal partition units are not reachable.1316 1317The suggested approach for using an internal partition unit in Clang is1318to only import them in the implementation unit.1319 1320Known Issues1321------------1322 1323The following describes issues in the current implementation of modules. Please1324see1325`the issues list for modules <https://github.com/llvm/llvm-project/labels/clang%3Amodules>`_1326for a list of issues or to file a new issue if you don't find an existing one.1327When creating a new issue for standard C++ modules, please start the title with1328``[C++20] [Modules]`` (or ``[C++23] [Modules]``, etc) and add the label1329``clang:modules`` if possible.1330 1331A high-level overview of support for standards features, including modules, can1332be found on the `C++ Feature Status <https://clang.llvm.org/cxx_status.html>`_1333page.1334 1335Including headers after import is not well-supported1336~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1337 1338The following example is accepted:1339 1340.. code-block:: c++1341 1342 #include <iostream>1343 import foo; // assume module 'foo' contain the declarations from `<iostream>`1344 1345 int main(int argc, char *argv[])1346 {1347 std::cout << "Test\n";1348 return 0;1349 }1350 1351but if the order of ``#include <iostream>`` and ``import foo;`` is reversed,1352then the code is currently rejected:1353 1354.. code-block:: c++1355 1356 import foo; // assume module 'foo' contain the declarations from `<iostream>`1357 #include <iostream>1358 1359 int main(int argc, char *argv[])1360 {1361 std::cout << "Test\n";1362 return 0;1363 }1364 1365Both of the above examples should be accepted.1366 1367This is a limitation of the implementation. In the first example, the compiler1368will see and parse ``<iostream>`` first then it will see the ``import``. In1369this case, ODR checking and declaration merging will happen in the1370deserializer. In the second example, the compiler will see the ``import`` first1371and the ``#include`` second which results in ODR checking and declarations1372merging happening in the semantic analyzer. This is due to a divergence in the1373implementation path. This is tracked by1374`#61465 <https://github.com/llvm/llvm-project/issues/61465>`_.1375 1376Ignored ``preferred_name`` Attribute1377~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1378 1379When Clang writes BMIs, it will ignore the ``preferred_name`` attribute on1380declarations which use it. Thus, the preferred name will not be displayed in1381the debugger as expected. This is tracked by1382`#56490 <https://github.com/llvm/llvm-project/issues/56490>`_.1383 1384Don't emit macros about module declaration1385~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1386 1387This is covered by `P1857R3 <https://wg21.link/P1857R3>`_. It is mentioned here1388because we want users to be aware that we don't yet implement it.1389 1390A direct approach to write code that can be compiled by both modules and1391non-module builds may look like:1392 1393.. code-block:: c++1394 1395 MODULE1396 IMPORT header_name1397 EXPORT_MODULE MODULE_NAME;1398 IMPORT header_name1399 EXPORT ...1400 1401The intent of this is that this file can be compiled like a module unit or a1402non-module unit depending on the definition of some macros. However, this usage1403is forbidden by P1857R3 which is not yet implemented in Clang. This means that1404is possible to write invalid modules which will no longer be accepted once1405P1857R3 is implemented. This is tracked by1406`#54047 <https://github.com/llvm/llvm-project/issues/54047>`_.1407 1408Until then, it is recommended not to mix macros with module declarations.1409 1410 1411Inconsistent filename suffix requirement for importable module units1412~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1413 1414Currently, Clang requires the file name of an ``importable module unit`` to1415have ``.cppm`` (or ``.ccm``, ``.cxxm``, ``.c++m``) as the file extension.1416However, the behavior is inconsistent with other compilers. This is tracked by1417`#57416 <https://github.com/llvm/llvm-project/issues/57416>`_.1418 1419Incorrect ODR violation diagnostics1420~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1421 1422ODR violations are a common issue when using modules. Clang sometimes produces1423false-positive diagnostics or fails to produce true-positive diagnostics of the1424One Definition Rule. One often-reported example is:1425 1426.. code-block:: c++1427 1428 // part.cc1429 module;1430 typedef long T;1431 namespace ns {1432 inline void fun() {1433 (void)(T)0;1434 }1435 }1436 export module repro:part;1437 1438 // repro.cc1439 module;1440 typedef long T;1441 namespace ns {1442 using ::T;1443 }1444 namespace ns {1445 inline void fun() {1446 (void)(T)0;1447 }1448 }1449 export module repro;1450 export import :part;1451 1452Currently the compiler incorrectly diagnoses the inconsistent definition of1453``fun()`` in two module units. Because both definitions of ``fun()`` have the1454same spelling and ``T`` refers to the same type entity, there is no ODR1455violation. This is tracked by1456`#78850 <https://github.com/llvm/llvm-project/issues/78850>`_.1457 1458Using TU-local entity in other units1459~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1460 1461Module units are translation units, so the entities which should be local to1462the module unit itself should never be used by other units.1463 1464The C++ standard defines the concept of ``TU-local`` and ``exposure`` in1465`basic.link/p14 <https://eel.is/c++draft/basic.link#14>`_,1466`basic.link/p15 <https://eel.is/c++draft/basic.link#15>`_,1467`basic.link/p16 <https://eel.is/c++draft/basic.link#16>`_,1468`basic.link/p17 <https://eel.is/c++draft/basic.link#17>`_, and1469`basic.link/p18 <https://eel.is/c++draft/basic.link#18>`_.1470 1471However, Clang doesn't formally support these two concepts. This results in1472unclear or confusing diagnostic messages. Further, Clang may import1473``TU-local`` entities to other units without any diagnostics. This is tracked1474by `#78173 <https://github.com/llvm/llvm-project/issues/78173>`_.1475 1476.. _header-units:1477 1478Header Units1479============1480 1481How to build projects using header units1482----------------------------------------1483 1484.. warning::1485 1486 The support for header units, including related command line options, is1487 experimental. There are still many unanswered questions about how tools1488 should interact with header units. The details described here may change in1489 the future.1490 1491Quick Start1492~~~~~~~~~~~1493 1494The following example:1495 1496.. code-block:: c++1497 1498 import <iostream>;1499 int main() {1500 std::cout << "Hello World.\n";1501 }1502 1503could be compiled with:1504 1505.. code-block:: console1506 1507 $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm1508 $ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp1509 1510How to produce BMIs1511~~~~~~~~~~~~~~~~~~~1512 1513Similar to named modules, ``--precompile`` can be used to produce a BMI.1514However, that requires specifying that the input file is a header by using1515``-xc++-system-header`` or ``-xc++-user-header``.1516 1517The ``-fmodule-header={user,system}`` option can also be used to produce a BMI1518for header units which have a file extension like `.h` or `.hh`. The argument to1519``-fmodule-header`` specifies either the user search path or the system search1520path. The default value for ``-fmodule-header`` is ``user``. For example:1521 1522.. code-block:: c++1523 1524 // foo.h1525 #include <iostream>1526 void Hello() {1527 std::cout << "Hello World.\n";1528 }1529 1530 // use.cpp1531 import "foo.h";1532 int main() {1533 Hello();1534 }1535 1536could be compiled with:1537 1538.. code-block:: console1539 1540 $ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm1541 $ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp1542 1543For headers which do not have a file extension, ``-xc++-header`` (or1544``-xc++-system-header``, ``-xc++-user-header``) must be used to specify the1545file as a header. For example:1546 1547.. code-block:: c++1548 1549 // use.cpp1550 import "foo.h";1551 int main() {1552 Hello();1553 }1554 1555.. code-block:: console1556 1557 $ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm1558 $ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp1559 1560How to specify BMI dependencies1561~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1562 1563``-fmodule-file`` can be used to specify a BMI dependency (or multiple times for1564more than one BMI dependency).1565 1566With the existing implementation, ``-fprebuilt-module-path`` cannot be used for1567header units (because they are nominally anonymous). For header units, use1568``-fmodule-file`` to include the relevant PCM file for each header unit.1569 1570This is expected to be solved in a future version of Clang either by the compiler1571finding and specifying ``-fmodule-file`` automatically, or by the use of a1572module-mapper that understands how to map the header name to their PCMs.1573 1574Compiling a header unit to an object file1575~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1576 1577A header unit cannot be compiled to an object file due to the semantics of1578header units. For example:1579 1580.. code-block:: console1581 1582 $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm1583 # This is not allowed!1584 $ clang++ iostream.pcm -c -o iostream.o1585 1586Include translation1587~~~~~~~~~~~~~~~~~~~1588 1589The C++ standard allows vendors to convert ``#include header-name`` to1590``import header-name;`` when possible. Currently, Clang does this translation1591for the ``#include`` in the global module fragment. For example, the following1592example:1593 1594.. code-block:: c++1595 1596 module;1597 import <iostream>;1598 export module M;1599 export void Hello() {1600 std::cout << "Hello.\n";1601 }1602 1603is the same as this example:1604 1605.. code-block:: c++1606 1607 module;1608 #include <iostream>1609 export module M;1610 export void Hello() {1611 std::cout << "Hello.\n";1612 }1613 1614.. code-block:: console1615 1616 $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm1617 $ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp1618 1619In the latter example, Clang can find the BMI for ``<iostream>`` and so it1620tries to replace the ``#include <iostream>`` with ``import <iostream>;``1621automatically.1622 1623 1624Differences between Clang modules and header units1625--------------------------------------------------1626 1627Header units have similar semantics to Clang modules. The semantics of both are1628like headers. Therefore, header units can be mimicked by Clang modules as in1629the following example:1630 1631.. code-block:: c++1632 1633 module "iostream" {1634 export *1635 header "/path/to/libstdcxx/iostream"1636 }1637 1638.. code-block:: console1639 1640 $ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp1641 1642This example is simplified when using libc++:1643 1644.. code-block:: console1645 1646 $ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps1647 1648because libc++ already supplies a1649`module map <https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in>`_.1650 1651This raises the question: why are header units not implemented through Clang1652modules?1653 1654This is primarily because Clang modules have more hierarchical semantics when1655wrapping multiple headers together as one module, which is not supported by1656Standard C++ Header units. We want to avoid the impression that these1657additional semantics get interpreted as Standard C++ behavior.1658 1659Another reason is that there are proposals to introduce module mappers to the1660C++ standard (for example, https://wg21.link/p1184r2). Reusing Clang's1661``modulemap`` may be more difficult if we need to introduce another module1662mapper.1663 1664Discovering Dependencies1665========================1666 1667Without use of modules, all the translation units in a project can be compiled1668in parallel. However, the presence of module units requires compiling the1669translation units in a topological order.1670 1671The ``clang-scan-deps`` tool can extract dependency information and produce a1672JSON file conforming to the specification described in1673`P1689 <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html>`_.1674Only named modules are supported currently.1675 1676A compilation database is needed when using ``clang-scan-deps``. See1677`JSON Compilation Database Format Specification <JSONCompilationDatabase.html>`_1678for more information about compilation databases. Note that the ``output``1679JSON attribute is necessary for ``clang-scan-deps`` to scan using the P16891680format. For example:1681 1682.. code-block:: c++1683 1684 //--- M.cppm1685 export module M;1686 export import :interface_part;1687 import :impl_part;1688 export int Hello();1689 1690 //--- interface_part.cppm1691 export module M:interface_part;1692 export void World();1693 1694 //--- Impl.cpp1695 module;1696 #include <iostream>1697 module M;1698 void Hello() {1699 std::cout << "Hello ";1700 }1701 1702 //--- impl_part.cppm1703 module;1704 #include <string>1705 #include <iostream>1706 module M:impl_part;1707 import :interface_part;1708 1709 std::string W = "World.";1710 void World() {1711 std::cout << W << std::endl;1712 }1713 1714 //--- User.cpp1715 import M;1716 import third_party_module;1717 int main() {1718 Hello();1719 World();1720 return 0;1721 }1722 1723And here is the compilation database:1724 1725.. code-block:: text1726 1727 [1728 {1729 "directory": ".",1730 "command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",1731 "file": "M.cppm",1732 "output": "M.o"1733 },1734 {1735 "directory": ".",1736 "command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",1737 "file": "Impl.cpp",1738 "output": "Impl.o"1739 },1740 {1741 "directory": ".",1742 "command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",1743 "file": "impl_part.cppm",1744 "output": "impl_part.o"1745 },1746 {1747 "directory": ".",1748 "command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",1749 "file": "interface_part.cppm",1750 "output": "interface_part.o"1751 },1752 {1753 "directory": ".",1754 "command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",1755 "file": "User.cpp",1756 "output": "User.o"1757 }1758 ]1759 1760To get the dependency information in P1689 format, use:1761 1762.. code-block:: console1763 1764 $ clang-scan-deps -format=p1689 -compilation-database P1689.json1765 1766to get:1767 1768.. code-block:: text1769 1770 {1771 "revision": 0,1772 "rules": [1773 {1774 "primary-output": "Impl.o",1775 "requires": [1776 {1777 "logical-name": "M",1778 "source-path": "M.cppm"1779 }1780 ]1781 },1782 {1783 "primary-output": "M.o",1784 "provides": [1785 {1786 "is-interface": true,1787 "logical-name": "M",1788 "source-path": "M.cppm"1789 }1790 ],1791 "requires": [1792 {1793 "logical-name": "M:interface_part",1794 "source-path": "interface_part.cppm"1795 },1796 {1797 "logical-name": "M:impl_part",1798 "source-path": "impl_part.cppm"1799 }1800 ]1801 },1802 {1803 "primary-output": "User.o",1804 "requires": [1805 {1806 "logical-name": "M",1807 "source-path": "M.cppm"1808 },1809 {1810 "logical-name": "third_party_module"1811 }1812 ]1813 },1814 {1815 "primary-output": "impl_part.o",1816 "provides": [1817 {1818 "is-interface": false,1819 "logical-name": "M:impl_part",1820 "source-path": "impl_part.cppm"1821 }1822 ],1823 "requires": [1824 {1825 "logical-name": "M:interface_part",1826 "source-path": "interface_part.cppm"1827 }1828 ]1829 },1830 {1831 "primary-output": "interface_part.o",1832 "provides": [1833 {1834 "is-interface": true,1835 "logical-name": "M:interface_part",1836 "source-path": "interface_part.cppm"1837 }1838 ]1839 }1840 ],1841 "version": 11842 }1843 1844See the P1689 paper for the meaning of the fields.1845 1846Getting dependency information per file with finer-grained control (such as1847scanning generated source files) is possible. For example:1848 1849.. code-block:: console1850 1851 $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o1852 1853will produce:1854 1855.. code-block:: text1856 1857 {1858 "revision": 0,1859 "rules": [1860 {1861 "primary-output": "impl_part.o",1862 "provides": [1863 {1864 "is-interface": false,1865 "logical-name": "M:impl_part",1866 "source-path": "impl_part.cppm"1867 }1868 ],1869 "requires": [1870 {1871 "logical-name": "M:interface_part"1872 }1873 ]1874 }1875 ],1876 "version": 11877 }1878 1879Individual command line options can be specified after ``--``.1880``clang-scan-deps`` will extract the necessary information from the specified1881options. Note that the path to the compiler executable needs to be specified1882explicitly instead of using ``clang++`` directly.1883 1884Users may want the scanner to get the transitive dependency information for1885headers. Otherwise, the project has to be scanned twice, once for headers and1886once for modules. To address this, ``clang-scan-deps`` will recognize the1887specified preprocessor options in the given command line and generate the1888corresponding dependency information. For example:1889 1890.. code-block:: console1891 1892 $ clang-scan-deps -format=p1689 -- ../bin/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o -MD -MT impl_part.ddi -MF impl_part.dep1893 $ cat impl_part.dep1894 1895will produce:1896 1897.. code-block:: text1898 1899 impl_part.ddi: \1900 /usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \1901 /usr/include/bits/types/mbstate_t.h \1902 /usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \1903 /usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \1904 /usr/include/bits/types/__locale_t.h \1905 ...1906 1907When ``clang-scan-deps`` detects the ``-MF`` option, it will try to write the1908dependency information for headers to the file specified by ``-MF``.1909 1910Possible Issues: Failed to find system headers1911----------------------------------------------1912 1913If encountering an error like ``fatal error: 'stddef.h' file not found``,1914the specified ``<path-to-compiler-executable>/clang++`` probably refers to a1915symlink instead of a real binary. There are four potential solutions to the1916problem:1917 19181. Point the specified compiler executable to the real binary instead of the1919 symlink.19202. Invoke ``<path-to-compiler-executable>/clang++ -print-resource-dir`` to get1921 the corresponding resource directory for your compiler and add that1922 directory to the include search paths manually in the build scripts.19233. For build systems that use a compilation database as the input for1924 ``clang-scan-deps``, the build system can add the1925 ``--resource-dir-recipe invoke-compiler`` option when executing1926 ``clang-scan-deps`` to calculate the resource directory dynamically.1927 The calculation happens only once for a unique ``<path-to-compiler-executable>/clang++``.19284. For build systems that invoke ``clang-scan-deps`` per file, repeatedly1929 calculating the resource directory may be inefficient. In such cases, the1930 build system can cache the resource directory and specify1931 ``-resource-dir <resource-dir>`` explicitly, as in:1932 1933 .. code-block:: console1934 1935 $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o1936 1937 1938Import modules with clang-repl1939==============================1940 1941``clang-repl`` supports importing C++20 named modules. For example:1942 1943.. code-block:: c++1944 1945 // M.cppm1946 export module M;1947 export const char* Hello() {1948 return "Hello Interpreter for Modules!";1949 }1950 1951The named module still needs to be compiled ahead of time.1952 1953.. code-block:: console1954 1955 $ clang++ -std=c++20 M.cppm --precompile -o M.pcm1956 $ clang++ M.pcm -c -o M.o1957 $ clang++ -shared M.o -o libM.so1958 1959Note that the module unit needs to be compiled as a dynamic library so that1960``clang-repl`` can load the object files of the module units. Then it is1961possible to import module ``M`` in clang-repl.1962 1963.. code-block:: console1964 1965 $ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.1966 # We need to load the dynamic library first before importing the modules.1967 clang-repl> %lib libM.so1968 clang-repl> import M;1969 clang-repl> extern "C" int printf(const char *, ...);1970 clang-repl> printf("%s\n", Hello());1971 Hello Interpreter for Modules!1972 clang-repl> %quit1973 1974Possible Questions1975==================1976 1977How modules speed up compilation1978--------------------------------1979 1980A classic theory for the reason why modules speed up the compilation is: if1981there are ``n`` headers and ``m`` source files and each header is included by1982each source file, then the complexity of the compilation is ``O(n*m)``.1983However, if there are ``n`` module interfaces and ``m`` source files, the1984complexity of the compilation is ``O(n+m)``. Therefore, using modules would be1985a significant improvement at scale. More simply, use of modules causes many of1986the redundant compilations to no longer be necessary.1987 1988While this is accurate at a high level, this depends greatly on the1989optimization level, as illustrated below.1990 1991First is ``-O0``. The compilation process is described in the following graph.1992 1993.. code-block:: none1994 1995 ├-------------frontend----------┼-------------middle end----------------┼----backend----┤1996 │ │ │ │1997 └---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘1998 1999 ├---------------------------------------------------------------------------------------┐2000 | │2001 | source file │2002 | │2003 └---------------------------------------------------------------------------------------┘2004 2005 ├--------┐2006 │ │2007 │imported│2008 │ │2009 │ code │2010 │ │2011 └--------┘2012 2013In this case, the source file (which could be a non-module unit or a module2014unit) would get processed by the entire pipeline. However, the imported code2015would only get involved in semantic analysis, which, for the most part, is name2016lookup, overload resolution, and template instantiation. All of these processes2017are fast relative to the whole compilation process. More importantly, the2018imported code only needs to be processed once during frontend code generation,2019as well as the whole middle end and backend. So we could get a big win for the2020compilation time in ``-O0``.2021 2022But with optimizations, things are different (the ``code generation`` part for2023each end is omitted due to limited space):2024 2025.. code-block:: none2026 2027 ├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤2028 │ │ │ │2029 └--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘2030 2031 ├-----------------------------------------------------------------------------------------------┐2032 │ │2033 │ source file │2034 │ │2035 └-----------------------------------------------------------------------------------------------┘2036 ├---------------------------------------┐2037 │ │2038 │ │2039 │ imported code │2040 │ │2041 │ │2042 └---------------------------------------┘2043 2044It would be very unfortunate if we end up with worse performance when using2045modules. The main concern is that when a source file is compiled, the compiler2046needs to see the body of imported module units so that it can perform IPO2047(InterProcedural Optimization, primarily inlining in practice) to optimize2048functions in the current source file with the help of the information provided2049by the imported module units. In other words, the imported code would be2050processed again and again in importee units by optimizations (including IPO2051itself). The optimizations before IPO and IPO itself are the most time-consuming2052part in whole compilation process. So from this perspective, it might not be2053possible to get the compile time improvements described, but there could be2054time savings for optimizations after IPO and the whole backend.2055 2056Overall, at ``-O0`` the implementations of functions defined in a module will2057not impact module users, but at higher optimization levels the definitions of2058such functions are provided to user compilations for the purposes of2059optimization (but definitions of these functions are still not included in the2060use's object file). This means the build speedup at higher optimization levels2061may be lower than expected given ``-O0`` experience, but does provide more2062optimization opportunities.2063 2064Interoperability with Clang Modules2065-----------------------------------2066 2067We **wish** to support Clang modules and standard C++ modules at the same time,2068but the mixing them together is not well used/tested yet. Please file new2069GitHub issues as you find interoperability problems.2070