clang/docs/StandardCPlusPlusModules.rst

   1 ====================
   2 Standard C++ Modules
   3 ====================
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 The term ``module`` is ambiguous, as it is used to mean multiple things in
  12 Clang. For Clang users, a module may refer to an ``Objective-C Module``,
  13 `Clang Module <Modules.html>`_ (also called a ``Clang Header Module``) or a
  14 ``C++20 Module`` (or a ``Standard C++ Module``). The implementation of all
  15 these kinds of modules in Clang shares a lot of code, but from the perspective
  16 of users their semantics and command line interfaces are very different. This
  17 document is an introduction to the use of C++20 modules in Clang. In the
  18 remainder of this document, the term ``module`` will refer to Standard C++20
  19 modules and the term ``Clang module`` will refer to the Clang Modules
  20 extension.
  21
  22 In terms of the C++ Standard, modules consist of two components: "Named
  23 Modules" or "Header Units". This document covers both.
  24
  25 Standard C++ Named modules
  26 ==========================
  27
  28 In order to better understand the compiler's behavior, it is helpful to
  29 understand some terms and definitions for readers who are not familiar with the
  30 C++ feature. This document is not a tutorial on C++; it only introduces
  31 necessary concepts to better understand use of modules in a project.
  32
  33 Background and terminology
  34 --------------------------
  35
  36 Module and module unit
  37 ~~~~~~~~~~~~~~~~~~~~~~
  38
  39 A module consists of one or more module units. A module unit is a special kind
  40 of translation unit. A module unit should almost always start with a module
  41 declaration. The syntax of the module declaration is:
  42
  43 .. code-block:: c++
  44
  45   [export] module module_name[:partition_name];
  46
  47 Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``
  48 follow the rules for a C++ identifier, except that they may contain one or more
  49 period (``.``) characters. Note that a ``.`` in the name has no semantic
  50 meaning and does not imply any hierarchy.
  51
  52 In this document, module units are classified as:
  53
  54 * Primary module interface unit
  55 * Module implementation unit
  56 * Module partition interface unit
  57 * Internal module partition unit
  58
  59 A primary module interface unit is a module unit whose module declaration is
  60 ``export module module_name;`` where ``module_name`` denotes the name of the
  61 module. A module should have one and only one primary module interface unit.
  62
  63 A module implementation unit is a module unit whose module declaration is
  64 ``module module_name;``. Multiple module implementation units can be declared
  65 in the same module.
  66
  67 A module partition interface unit is a module unit whose module declaration is
  68 ``export module module_name:partition_name;``. The ``partition_name`` should be
  69 unique within any given module.
  70
  71 An internal module partition unit is a module unit whose module
  72 declaration is ``module module_name:partition_name;``. The ``partition_name``
  73 should be unique within any given module.
  74
  75 In 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`` or
  81   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
  86 Built Module Interface
  87 ~~~~~~~~~~~~~~~~~~~~~~
  88
  89 A ``Built Module Interface`` (or ``BMI``) is the precompiled result of an
  90 importable module unit.
  91
  92 Global module fragment
  93 ~~~~~~~~~~~~~~~~~~~~~~
  94
  95 The ``global module fragment`` (or ``GMF``) is the code between the ``module;``
  96 and the module declaration within a module unit.
  97
  98
  99 How to build projects using modules
 100 -----------------------------------
 101
 102 Quick Start
 103 ~~~~~~~~~~~
 104
 105 Let's see a "hello world" example that uses modules.
 106
 107 .. code-block:: c++
 108
 109   // Hello.cppm
 110   module;
 111   #include <iostream>
 112   export module Hello;
 113   export void hello() {
 114     std::cout << "Hello World!\n";
 115   }
 116
 117   // use.cpp
 118   import Hello;
 119   int main() {
 120     hello();
 121     return 0;
 122   }
 123
 124 Then, on the command line, invoke Clang like:
 125
 126 .. code-block:: console
 127
 128   $ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
 129   $ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out
 130   $ ./Hello.out
 131   Hello World!
 132
 133 In this example, we make and use a simple module ``Hello`` which contains only a
 134 primary module interface unit named ``Hello.cppm``.
 135
 136 A more complex "hello world" example which uses the 4 kinds of module units is:
 137
 138 .. code-block:: c++
 139
 140   // M.cppm
 141   export module M;
 142   export import :interface_part;
 143   import :impl_part;
 144   export void Hello();
 145
 146   // interface_part.cppm
 147   export module M:interface_part;
 148   export void World();
 149
 150   // impl_part.cppm
 151   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.cpp
 163   module;
 164   #include <iostream>
 165   module M;
 166   void Hello() {
 167     std::cout << "Hello ";
 168   }
 169
 170   // User.cpp
 171   import M;
 172   int main() {
 173     Hello();
 174     World();
 175     return 0;
 176   }
 177
 178 Then, back on the command line, invoke Clang with:
 179
 180 .. code-block:: console
 181
 182   # Precompiling the module
 183   $ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm
 184   $ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
 185   $ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
 186   $ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o
 187
 188   # Compiling the user
 189   $ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o
 190
 191   # Compiling the module and linking it together
 192   $ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o
 193   $ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o
 194   $ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o
 195   $ clang++ User.o M-interface_part.o  M-impl_part.o M.o Impl.o -o a.out
 196
 197 We explain the options in the following sections.
 198
 199 How to enable standard C++ modules
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 Standard C++ modules are enabled automatically when the language standard mode
 203 is ``-std=c++20`` or newer.
 204
 205 How to produce a BMI
 206 ~~~~~~~~~~~~~~~~~~~~
 207
 208 To generate a BMI for an importable module unit, use either the ``--precompile``
 209 or ``-fmodule-output`` command line options.
 210
 211 The ``--precompile`` option generates the BMI as the output of the compilation
 212 with the output path specified using the ``-o`` option.
 213
 214 The ``-fmodule-output`` option generates the BMI as a by-product of the
 215 compilation. If ``-fmodule-output=`` is specified, the BMI will be emitted to
 216 the specified location. If ``-fmodule-output`` and ``-c`` are specified, the
 217 BMI will be emitted in the directory of the output file with the name of the
 218 input file with the extension ``.pcm``. Otherwise, the BMI will be emitted in
 219 the working directory with the name of the input file with the extension
 220 ``.pcm``.
 221
 222 Generating BMIs with ``--precompile`` is referred to as two-phase compilation
 223 because it takes two steps to compile a source file to an object file.
 224 Generating BMIs with ``-fmodule-output`` is called one-phase compilation. The
 225 one-phase compilation model is simpler for build systems to implement while the
 226 two-phase compilation has the potential to compile faster due to higher
 227 parallelism. As an example, if there are two module units ``A`` and ``B``, and
 228 ``B`` depends on ``A``, the one-phase compilation model needs to compile them
 229 serially, whereas the two-phase compilation model is able to be compiled as
 230 soon as ``A.pcm`` is available, and thus can be compiled simultaneously as the
 231 ``A.pcm`` to ``A.o`` compilation step.
 232
 233 File name requirements
 234 ~~~~~~~~~~~~~~~~~~~~~~
 235
 236 By convention, ``importable module unit`` files should use ``.cppm`` (or
 237 ``.ccm``, ``.cxxm``, or ``.c++m``) as a file extension.
 238 ``Module implementation unit`` files should use ``.cpp`` (or ``.cc``, ``.cxx``,
 239 or ``.c++``) as a file extension.
 240
 241 A BMI should use ``.pcm`` as a file extension. The file name of the BMI for a
 242 ``primary module interface unit`` should be ``module_name.pcm``. The file name
 243 of a BMI for a ``module partition unit`` should be
 244 ``module_name-partition_name.pcm``.
 245
 246 Clang may fail to build the module if different extensions are used. For
 247 example, if the filename of an ``importable module unit`` ends with ``.cpp``
 248 instead of ``.cppm``, then Clang cannot generate a BMI for the
 249 ``importable module unit`` with the ``--precompile`` option because the
 250 ``--precompile`` option would only run the preprocessor (``-E``). If using a
 251 different extension than the conventional one for an ``importable module unit``
 252 you can specify ``-x c++-module`` before the file. For example,
 253
 254 .. code-block:: c++
 255
 256   // Hello.cpp
 257   module;
 258   #include <iostream>
 259   export module Hello;
 260   export void hello() {
 261     std::cout << "Hello World!\n";
 262   }
 263
 264   // use.cpp
 265   import Hello;
 266   int main() {
 267     hello();
 268     return 0;
 269   }
 270
 271 In this example, the extension used by the ``module interface`` is ``.cpp``
 272 instead of ``.cppm``, so it cannot be compiled like the previous example, but
 273 it can be compiled with:
 274
 275 .. code-block:: console
 276
 277   $ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
 278   $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
 279   $ ./Hello.out
 280   Hello World!
 281
 282 Module name requirements
 283 ~~~~~~~~~~~~~~~~~~~~~~~~
 284
 285 ..
 286
 287   [module.unit]p1:
 288
 289   All module-names either beginning with an identifier consisting of std followed by zero
 290   or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not
 291   be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
 292   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
 295 Therefore, none of the following names are valid by default:
 296
 297 .. code-block:: text
 298
 299     std
 300     std1
 301     std.foo
 302     __test
 303     // and so on ...
 304
 305 Using a reserved module name is strongly discouraged, but
 306 ``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 307
 308 Specifying dependent BMIs
 309 ~~~~~~~~~~~~~~~~~~~~~~~~~
 310
 311 There are 3 ways to specify a dependent BMI:
 312
 313 1. ``-fprebuilt-module-path=<path/to/directory>``.
 314 2. ``-fmodule-file=<path/to/BMI>`` (Deprecated).
 315 3. ``-fmodule-file=<module-name>=<path/to/BMI>``.
 316
 317 The ``-fprebuilt-module-path`` option specifies the path to search for
 318 dependent BMIs. Multiple paths may be specified, similar to using ``-I`` to
 319 specify a search path for header files. When importing a module ``M``, the
 320 compiler looks for ``M.pcm`` in the directories specified by
 321 ``-fprebuilt-module-path``. Similarly, when importing a partition module unit
 322 ``M:P``, the compiler looks for ``M-P.pcm`` in the directories specified by
 323 ``-fprebuilt-module-path``.
 324
 325 The ``-fmodule-file=<path/to/BMI>`` option causes the compiler to load the
 326 specified BMI directly. The ``-fmodule-file=<module-name>=<path/to/BMI>``
 327 option causes the compiler to load the specified BMI for the module specified
 328 by ``<module-name>`` when necessary. The main difference is that
 329 ``-fmodule-file=<path/to/BMI>`` will load the BMI eagerly, whereas
 330 ``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,
 331 as will ``-fprebuilt-module-path``. The ``-fmodule-file=<path/to/BMI>`` option
 332 for named modules is deprecated and will be removed in a future version of
 333 Clang.
 334
 335 When these options are specified in the same invocation of the compiler, the
 336 ``-fmodule-file=<path/to/BMI>`` option takes precedence over
 337 ``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over
 338 ``-fprebuilt-module-path=<path/to/directory>``.
 339
 340 Note: all dependant BMIs must be specified explicitly, either directly or
 341 indirectly dependent BMIs explicitly. See
 342 https://github.com/llvm/llvm-project/issues/62707 for details.
 343
 344 When compiling a ``module implementation unit``, the BMI of the corresponding
 345 ``primary module interface unit`` must be specified because a module
 346 implementation unit implicitly imports the primary module interface unit.
 347
 348   [module.unit]p8
 349
 350   A module-declaration that contains neither an export-keyword nor a module-partition implicitly
 351   imports the primary module interface unit of the module as if by a module-import-declaration.
 352
 353 The ``-fprebuilt-module-path=<path/to/directory>``, ``-fmodule-file=<path/to/BMI>``,
 354 and ``-fmodule-file=<module-name>=<path/to/BMI>`` options may be specified
 355 multiple times. For example, the command line to compile ``M.cppm`` in
 356 the previous example could be rewritten as:
 357
 358 .. code-block:: console
 359
 360   $ 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
 361
 362 When there are multiple ``-fmodule-file=<module-name>=`` options for the same
 363 ``<module-name>``, the last ``-fmodule-file=<module-name>=`` overrides the
 364 previous ``-fmodule-file=<module-name>=`` option.
 365
 366 Remember that module units still have an object counterpart to the BMI
 367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 368
 369 While module interfaces resemble traditional header files, they still require
 370 compilation. Module units are translation units, and need to be compiled to
 371 object files, which then need to be linked together as the following examples
 372 show.
 373
 374 For example, the traditional compilation processes for headers are like:
 375
 376 .. code-block:: text
 377
 378   src1.cpp -+> clang++ src1.cpp --> src1.o ---,
 379   hdr1.h  --'                                 +-> clang++ src1.o src2.o ->  executable
 380   hdr2.h  --,                                 |
 381   src2.cpp -+> clang++ src2.cpp --> src2.o ---'
 382
 383 And the compilation process for module units are like:
 384
 385 .. code-block:: text
 386
 387                 src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,
 388   (header unit) hdr1.h    -> clang++ hdr1.h ...    -> hdr1.pcm --'                                    +-> clang++ src1.o mod1.o src2.o ->  executable
 389                 mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+
 390                 src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'
 391
 392 As the diagrams show, we need to compile the BMI from module units to object
 393 files and then link the object files. (However, this cannot be done for the BMI
 394 from header units. See the section on :ref:`header units <header-units>` for
 395 more details.
 396
 397 BMIs cannot be shipped in an archive to create a module library. Instead, the
 398 BMIs(``*.pcm``) are compiled into object files(``*.o``) and those object files
 399 are added to the archive instead.
 400
 401 clang-cl
 402 ~~~~~~~~
 403
 404 ``clang-cl`` supports the same options as ``clang++`` for modules as detailed above;
 405 there is no need to prefix these options with ``/clang:``. Note that ``cl.exe``
 406 `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.
 407 The resultant precompiled modules are also not compatible for use with ``cl.exe``.
 408
 409 We recommend that build system authors use the above-mentioned ``clang++`` options  with ``clang-cl`` to build modules.
 410
 411 Consistency Requirements
 412 ~~~~~~~~~~~~~~~~~~~~~~~~
 413
 414 Modules can be viewed as a kind of cache to speed up compilation. Thus, like
 415 other caching techniques, it is important to maintain cache consistency which
 416 is why Clang does very strict checking for consistency.
 417
 418 Options consistency
 419 ^^^^^^^^^^^^^^^^^^^
 420
 421 Compiler options related to the language dialect for a module unit and its
 422 non-module-unit uses need to be consistent. Consider the following example:
 423
 424 .. code-block:: c++
 425
 426   // M.cppm
 427   export module M;
 428
 429   // Use.cpp
 430   import M;
 431
 432 .. code-block:: console
 433
 434   $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
 435   $ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
 436
 437 Clang rejects the example due to the inconsistent language standard modes. Not
 438 all compiler options are language dialect options, though. For example:
 439
 440 .. code-block:: console
 441
 442   $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
 443   # Inconsistent optimization level.
 444   $ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
 445   # Inconsistent debugging level.
 446   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 447
 448 Although the optimization and debugging levels are inconsistent, these
 449 compilations are accepted because the compiler options do not impact the
 450 language dialect.
 451
 452 Note that the compiler **currently** doesn't reject inconsistent macro
 453 definitions (this may change in the future). For example:
 454
 455 .. code-block:: console
 456
 457   $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
 458   # Inconsistent optimization level.
 459   $ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
 460
 461 Currently, Clang accepts the above example, though it may produce surprising
 462 results if the debugging code depends on consistent use of ``NDEBUG`` in other
 463 translation units.
 464
 465 Source Files Consistency
 466 ^^^^^^^^^^^^^^^^^^^^^^^^
 467
 468 Clang may open the input files\ :sup:`1`` of a BMI during the compilation. This implies that
 469 when Clang consumes a BMI, all the input files need to be present in the original path
 470 and with the original contents.
 471
 472 To overcome these requirements and simplify cases like distributed builds and sandboxed
 473 builds, users can use the ``-fmodules-embed-all-files`` flag to embed all input files
 474 into the BMI so that Clang does not need to open the corresponding file on disk.
 475
 476 When the ``-fmodules-embed-all-files`` flag are enabled, Clang explicitly emits the source
 477 code into the BMI file, the contents of the BMI file contain a sufficiently verbose
 478 representation to reproduce the original source file.
 479
 480 :sup:`1`` Input files: The source files which took part in the compilation of the BMI.
 481 For example:
 482
 483 .. code-block:: c++
 484
 485   // M.cppm
 486   module;
 487   #include "foo.h"
 488   export module M;
 489
 490   // foo.h
 491   #pragma once
 492   #include "bar.h"
 493
 494 The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.
 495
 496 Object definition consistency
 497 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 498
 499 The C++ language requires that declarations of the same entity in different
 500 translation units have the same definition, which is known as the One
 501 Definition Rule (ODR). Without modules, the compiler cannot perform strong ODR
 502 violation checking because it only sees one translation unit at a time. With
 503 the use of modules, the compiler can perform checks for ODR violations across
 504 translation units.
 505
 506 However, the current ODR checking mechanisms are not perfect. There are a
 507 significant number of false positive ODR violation diagnostics, where the
 508 compiler incorrectly diagnoses two identical declarations as having different
 509 definitions. Further, true positive ODR violations are not always reported.
 510
 511 To give a better user experience, improve compilation performance, and for
 512 consistency with MSVC, ODR checking of declarations in the global module
 513 fragment is disabled by default. These checks can be enabled by specifying
 514 ``-Xclang -fno-skip-odr-check-in-gmf`` when compiling. If the check is enabled
 515 and you encounter incorrect or missing diagnostics, please report them via the
 516 `community issue tracker <https://github.com/llvm/llvm-project/issues/>`_.
 517
 518 Privacy Issue
 519 -------------
 520
 521 BMIs are not and should not be treated as an information hiding mechanism.
 522 They should always be assumed to contain all the information that was used to
 523 create them, in a recoverable form.
 524
 525 ABI Impacts
 526 -----------
 527
 528 This section describes the new ABI changes brought by modules. Only changes to
 529 the Itanium C++ ABI are covered.
 530
 531 Name Mangling
 532 ~~~~~~~~~~~~~
 533
 534 The declarations in a module unit which are not in the global module fragment
 535 have new linkage names.
 536
 537 For example,
 538
 539 .. code-block:: c++
 540
 541   export module M;
 542   namespace NS {
 543     export int foo();
 544   }
 545
 546 The linkage name of ``NS::foo()`` is ``_ZN2NSW1M3fooEv``. This couldn't be
 547 demangled by previous versions of the debugger or demangler. As of LLVM 15.x,
 548 ``llvm-cxxfilt`` can be used to demangle this:
 549
 550 .. code-block:: console
 551
 552   $ llvm-cxxfilt _ZN2NSW1M3fooEv
 553     NS::foo@M()
 554
 555 The result should be read as ``NS::foo()`` in module ``M``.
 556
 557 The ABI implies that something cannot be declared in a module unit and defined
 558 in a non-module unit (or vice-versa), as this would result in linking errors.
 559
 560 Despite this, it is possible to implement declarations with a compatible ABI in
 561 a module unit by using a language linkage specifier because the declarations in
 562 the language linkage specifier are attached to the global module fragment. For
 563 example:
 564
 565 .. code-block:: c++
 566
 567   export module M;
 568   namespace NS {
 569     export extern "C++" int foo();
 570   }
 571
 572 Now the linkage name of ``NS::foo()`` will be ``_ZN2NS3fooEv``.
 573
 574 Module Initializers
 575 ~~~~~~~~~~~~~~~~~~~
 576
 577 All importable module units are required to emit an initializer function to
 578 handle the dynamic initialization of non-inline variables in the module unit.
 579 The importable module unit has to emit the initializer even if there is no
 580 dynamic initialization; otherwise, the importer may call a nonexistent
 581 function. The initializer function emits calls to imported modules first
 582 followed by calls to all to of the dynamic initializers in the current module
 583 unit.
 584
 585 Translation units that explicitly or implicitly import a named module must call
 586 the initializer functions of the imported named module within the sequence of
 587 the dynamic initializers in the translation unit. Initializations of entities
 588 at namespace scope are appearance-ordered. This (recursively) extends to
 589 imported modules at the point of appearance of the import declaration.
 590
 591 If the imported module is known to be empty, the call to its initializer may be
 592 omitted. Additionally, if the imported module is known to have already been
 593 imported, the call to its initializer may be omitted.
 594
 595 Reduced BMI
 596 -----------
 597
 598 To support the two-phase compilation model, Clang puts everything needed to
 599 produce an object into the BMI. However, other consumers of the BMI generally
 600 don't need that information. This makes the BMI larger and may introduce
 601 unnecessary dependencies for the BMI. To mitigate the problem, Clang has a
 602 compiler option to reduce the information contained in the BMI. These two
 603 formats are known as Full BMI and Reduced BMI, respectively.
 604
 605 Users can use the ``-fexperimental-modules-reduced-bmi`` option to produce a
 606 Reduced BMI.
 607
 608 For the one-phase compilation model (CMake implements this model), with
 609 ``-fexperimental-modules-reduced-bmi``, the generated BMI will be a Reduced
 610 BMI automatically. (The output path of the BMI is specified by
 611 ``-fmodule-output=`` as usual with the one-phase compilation model).
 612
 613 It is also possible to produce a Reduced BMI with the two-phase compilation
 614 model. When ``-fexperimental-modules-reduced-bmi``, ``--precompile``, and
 615 ``-fmodule-output=`` are specified, the generated BMI specified by ``-o`` will
 616 be a full BMI and the BMI specified by ``-fmodule-output=`` will be a Reduced
 617 BMI. The dependency graph in this case would look like:
 618
 619 .. code-block:: none
 620
 621   module-unit.cppm --> module-unit.full.pcm -> module-unit.o
 622                     |
 623                     -> module-unit.reduced.pcm -> consumer1.cpp
 624                                                -> consumer2.cpp
 625                                                -> ...
 626                                                -> consumer_n.cpp
 627
 628 Clang does not emit diagnostics when ``-fexperimental-modules-reduced-bmi`` is
 629 used with a non-module unit. This design permits users of the one-phase
 630 compilation model to try using reduced BMIs without needing to modify the build
 631 system. The two-phase compilation module requires build system support.
 632
 633 In a Reduced BMI, Clang does not emit unreachable entities from the global
 634 module fragment, or definitions of non-inline functions and non-inline
 635 variables. This may not be a transparent change.
 636
 637 Consider the following example:
 638
 639 .. code-block:: c++
 640
 641   // foo.h
 642   namespace N {
 643     struct X {};
 644     int d();
 645     int e();
 646     inline int f(X, int = d()) { return e(); }
 647     int g(X);
 648     int h(X);
 649   }
 650
 651   // M.cppm
 652   module;
 653   #include "foo.h"
 654   export module M;
 655   template<typename T> int use_f() {
 656     N::X x;                       // N::X, N, and :: are decl-reachable from use_f
 657     return f(x, 123);             // N::f is decl-reachable from use_f,
 658                                   // N::e is indirectly decl-reachable from use_f
 659                                   //   because it is decl-reachable from N::f, and
 660                                   // N::d is decl-reachable from use_f
 661                                   //   because it is decl-reachable from N::f
 662                                   //   even though it is not used in this call
 663   }
 664   template<typename T> int use_g() {
 665     N::X x;                       // N::X, N, and :: are decl-reachable from use_g
 666     return g((T(), x));           // N::g is not decl-reachable from use_g
 667   }
 668   template<typename T> int use_h() {
 669     N::X x;                       // N::X, N, and :: are decl-reachable from use_h
 670     return h((T(), x));           // N::h is not decl-reachable from use_h, but
 671                                   // N::h is decl-reachable from use_h<int>
 672   }
 673   int k = use_h<int>();
 674     // use_h<int> is decl-reachable from k, so
 675     // N::h is decl-reachable from k
 676
 677   // M-impl.cpp
 678   module M;
 679   int a = use_f<int>();           // OK
 680   int b = use_g<int>();           // error: no viable function for call to g;
 681                                   // g is not decl-reachable from purview of
 682                                   // module M's interface, so is discarded
 683   int c = use_h<int>();           // OK
 684
 685 In the above example, the function definition of ``N::g`` is elided from the
 686 Reduced BMI of ``M.cppm``. Then the use of ``use_g<int>`` in ``M-impl.cpp``
 687 fails to instantiate. For such issues, users can add references to ``N::g`` in
 688 the `module purview <https://eel.is/c++draft/module.unit#5>`_ of ``M.cppm`` to
 689 ensure it is reachable, e.g. ``using N::g;``.
 690
 691 Support for Reduced BMIs is still experimental, but it may become the default
 692 in the future. The expected roadmap for Reduced BMIs as of Clang 19.x is:
 693
 694 1. ``-fexperimental-modules-reduced-bmi`` is opt-in for 1~2 releases. The period depends
 695    on user feedback and may be extended.
 696 2. Announce that Reduced BMIs are no longer experimental and introduce
 697    ``-fmodules-reduced-bmi`` as a new option, and recommend use of the new
 698    option. This transition is expected to take 1~2 additional releases as well.
 699 3. Finally, ``-fmodules-reduced-bmi`` will be the default. When that time
 700    comes, the term BMI will refer to the Reduced BMI and the Full BMI will only
 701    be meaningful to build systems which elect to support two-phase compilation.
 702
 703 Experimental Non-Cascading Changes
 704 ----------------------------------
 705
 706 This section is primarily for build system vendors. For end compiler users,
 707 if you don't want to read it all, this is helpful to reduce recompilations.
 708 We encourage build system vendors and end users try this out and bring feedback.
 709
 710 Before Clang 19, a change in BMI of any (transitive) dependency would cause the
 711 outputs of the BMI to change. Starting with Clang 19, changes to non-direct
 712 dependencies should not directly affect the output BMI, unless they affect the
 713 results of the compilations. We expect that there are many more opportunities
 714 for this optimization than we currently have realized and would appreaciate
 715 feedback about missed optimization opportunities. For example,
 716
 717 .. code-block:: c++
 718
 719   // m-partA.cppm
 720   export module m:partA;
 721
 722   // m-partB.cppm
 723   export module m:partB;
 724   export int getB() { return 44; }
 725
 726   // m.cppm
 727   export module m;
 728   export import :partA;
 729   export import :partB;
 730
 731   // useBOnly.cppm
 732   export module useBOnly;
 733   import m;
 734   export int B() {
 735     return getB();
 736   }
 737
 738   // Use.cc
 739   import useBOnly;
 740   int get() {
 741     return B();
 742   }
 743
 744 To compile the project (for brevity, some commands are omitted.):
 745
 746 .. code-block:: console
 747
 748   $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
 749   $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
 750   $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
 751   $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
 752   $ md5sum useBOnly.pcm
 753   07656bf4a6908626795729295f9608da  useBOnly.pcm
 754
 755 If the interface of ``m-partA.cppm`` is changed to:
 756
 757 .. code-block:: c++
 758
 759   // m-partA.v1.cppm
 760   export module m:partA;
 761   export int getA() { return 43; }
 762
 763 and the BMI for ``useBOnly`` is recompiled as in:
 764
 765 .. code-block:: console
 766
 767   $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
 768   $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
 769   $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
 770   $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
 771   $ md5sum useBOnly.pcm
 772   07656bf4a6908626795729295f9608da  useBOnly.pcm
 773
 774 then the contents of ``useBOnly.pcm`` remain unchanged.
 775 Consequently, if the build system only bases recompilation decisions on directly imported modules,
 776 it becomes possible to skip the recompilation of ``Use.cc``.
 777 It should be fine because the altered interfaces do not affect ``Use.cc`` in any way;
 778 the changes do not cascade.
 779
 780 When ``Clang`` generates a BMI, it records the hash values of all potentially contributory BMIs
 781 for the BMI being produced. This ensures that build systems are not required to consider
 782 transitively imported modules when deciding whether to recompile.
 783
 784 What is considered to be a potential contributory BMIs is currently unspecified.
 785 However, it is a severe bug for a BMI to remain unchanged following an observable change
 786 that affects its consumers.
 787
 788 Build systems may utilize this optimization by doing an update-if-changed operation to the BMI
 789 that is consumed from the BMI that is output by the compiler.
 790
 791 We encourage build systems to add an experimental mode that
 792 reuses the cached BMI when **direct** dependencies did not change,
 793 even if **transitive** dependencies did change.
 794
 795 Given there are potential compiler bugs, we recommend that build systems
 796 support this feature as a configurable option so that users
 797 can go back to the transitive change mode safely at any time.
 798
 799 Interactions with Reduced BMI
 800 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 801
 802 With reduced BMI, non-cascading changes can be more powerful. For example,
 803
 804 .. code-block:: c++
 805
 806   // A.cppm
 807   export module A;
 808   export int a() { return 44; }
 809
 810   // B.cppm
 811   export module B;
 812   import A;
 813   export int b() { return a(); }
 814
 815 .. code-block:: console
 816
 817   $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm  -fexperimental-modules-reduced-bmi -o A.o
 818   $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm  -fexperimental-modules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
 819   $ md5sum B.pcm
 820   6c2bd452ca32ab418bf35cd141b060b9  B.pcm
 821
 822 And let's change the implementation for ``A.cppm`` into:
 823
 824 .. code-block:: c++
 825
 826   export module A;
 827   int a_impl() { return 99; }
 828   export int a() { return a_impl(); }
 829
 830 and recompile the example:
 831
 832 .. code-block:: console
 833
 834   $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm  -fexperimental-modules-reduced-bmi -o A.o
 835   $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm  -fexperimental-modules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
 836   $ md5sum B.pcm
 837   6c2bd452ca32ab418bf35cd141b060b9  B.pcm
 838
 839 We should find the contents of ``B.pcm`` remains the same. In this case, the build system is
 840 allowed to skip recompilations of TUs which solely and directly depend on module ``B``.
 841
 842 This only happens with a reduced BMI. With reduced BMIs, we won't record the function body
 843 of ``int b()`` in the BMI for ``B`` so that the module ``A`` doesn't contribute to the BMI of ``B``
 844 and we have less dependencies.
 845
 846 Performance Tips
 847 ----------------
 848
 849 Reduce duplications
 850 ~~~~~~~~~~~~~~~~~~~
 851
 852 While it is valid to have duplicated declarations in the global module fragments
 853 of different module units, it is not free for Clang to deal with the duplicated
 854 declarations. A translation unit will compile more slowly if there is a lot of
 855 duplicated declarations between the translation unit and modules it imports.
 856 For example:
 857
 858 .. code-block:: c++
 859
 860   // M-partA.cppm
 861   module;
 862   #include "big.header.h"
 863   export module M:partA;
 864   ...
 865
 866   // M-partB.cppm
 867   module;
 868   #include "big.header.h"
 869   export module M:partB;
 870   ...
 871
 872   // other partitions
 873   ...
 874
 875   // M-partZ.cppm
 876   module;
 877   #include "big.header.h"
 878   export module M:partZ;
 879   ...
 880
 881   // M.cppm
 882   export module M;
 883   export import :partA;
 884   export import :partB;
 885   ...
 886   export import :partZ;
 887
 888   // use.cpp
 889   import M;
 890   ... // use declarations from module M.
 891
 892 When ``big.header.h`` is big enough and there are a lot of partitions, the
 893 compilation of ``use.cpp`` may be significantly slower than the following
 894 approach:
 895
 896 .. code-block:: c++
 897
 898   module;
 899   #include "big.header.h"
 900   export module m:big.header.wrapper;
 901   export ... // export the needed declarations
 902
 903   // M-partA.cppm
 904   export module M:partA;
 905   import :big.header.wrapper;
 906   ...
 907
 908   // M-partB.cppm
 909   export module M:partB;
 910   import :big.header.wrapper;
 911   ...
 912
 913   // other partitions
 914   ...
 915
 916   // M-partZ.cppm
 917   export module M:partZ;
 918   import :big.header.wrapper;
 919   ...
 920
 921   // M.cppm
 922   export module M;
 923   export import :partA;
 924   export import :partB;
 925   ...
 926   export import :partZ;
 927
 928   // use.cpp
 929   import M;
 930   ... // use declarations from module M.
 931
 932 Reducing the duplication from textual includes is what improves compile-time
 933 performance.
 934
 935 To help users to identify such issues, we add a warning ``-Wdecls-in-multiple-modules``.
 936 This warning is disabled by default and it needs to be explicitly enabled or by ``-Weverything``.
 937
 938 Transitioning to modules
 939 ------------------------
 940
 941 It is best for new code and libraries to use modules from the start if
 942 possible. However, it may be a breaking change for existing code or libraries
 943 to switch to modules. As a result, many existing libraries need to provide
 944 both headers and module interfaces for a while to not break existing users.
 945
 946 This section suggests some suggestions on how to ease the transition process
 947 for existing libraries. **Note that this information is only intended as
 948 guidance, rather than as requirements to use modules in Clang.** It presumes
 949 the project is starting with no module-based dependencies.
 950
 951 ABI non-breaking styles
 952 ~~~~~~~~~~~~~~~~~~~~~~~
 953
 954 export-using style
 955 ^^^^^^^^^^^^^^^^^^
 956
 957 .. code-block:: c++
 958
 959   module;
 960   #include "header_1.h"
 961   #include "header_2.h"
 962   ...
 963   #include "header_n.h"
 964   export module your_library;
 965   export namespace your_namespace {
 966     using decl_1;
 967     using decl_2;
 968     ...
 969     using decl_n;
 970   }
 971
 972 This example shows how to include all the headers containing declarations which
 973 need to be exported, and uses `using` declarations in an `export` block to
 974 produce the module interface.
 975
 976 export extern-C++ style
 977 ^^^^^^^^^^^^^^^^^^^^^^^
 978
 979 .. code-block:: c++
 980
 981   module;
 982   #include "third_party/A/headers.h"
 983   #include "third_party/B/headers.h"
 984   ...
 985   #include "third_party/Z/headers.h"
 986   export module your_library;
 987   #define IN_MODULE_INTERFACE
 988   extern "C++" {
 989     #include "header_1.h"
 990     #include "header_2.h"
 991     ...
 992     #include "header_n.h"
 993   }
 994
 995 Headers (from ``header_1.h`` to ``header_n.h``) need to define the macro:
 996
 997 .. code-block:: c++
 998
 999   #ifdef IN_MODULE_INTERFACE
1000   #define EXPORT export
1001   #else
1002   #define EXPORT
1003   #endif
1004
1005 and put ``EXPORT`` on the declarations you want to export.
1006
1007 Also, it is recommended to refactor headers to include third-party headers
1008 conditionally:
1009
1010 .. code-block:: c++
1011
1012   #ifndef IN_MODULE_INTERFACE
1013   #include "third_party/A/headers.h"
1014   #endif
1015
1016   #include "header_x.h"
1017
1018   ...
1019
1020 This can be helpful because it gives better diagnostic messages if the module
1021 interface unit is not properly updated when modifying code.
1022
1023 This approach works because the declarations with language linkage are attached
1024 to the global module. Thus, the ABI of the modular form of the library does not
1025 change.
1026
1027 While this style is more involved than the export-using style, it makes it
1028 easier to further refactor the library to other styles.
1029
1030 ABI breaking style
1031 ~~~~~~~~~~~~~~~~~~
1032
1033 The term ``ABI breaking`` may sound like a bad approach. However, this style
1034 forces consumers of the library use it in a consistent way. e.g., either always
1035 include headers for the library or always import modules. The style prevents
1036 the ability to mix includes and imports for the library.
1037
1038 The pattern for ABI breaking style is similar to the export extern-C++ style.
1039
1040 .. code-block:: c++
1041
1042   module;
1043   #include "third_party/A/headers.h"
1044   #include "third_party/B/headers.h"
1045   ...
1046   #include "third_party/Z/headers.h"
1047   export module your_library;
1048   #define IN_MODULE_INTERFACE
1049   #include "header_1.h"
1050   #include "header_2.h"
1051   ...
1052   #include "header_n.h"
1053
1054   #if the number of .cpp files in your project are small
1055   module :private;
1056   #include "source_1.cpp"
1057   #include "source_2.cpp"
1058   ...
1059   #include "source_n.cpp"
1060   #else // the number of .cpp files in your project are a lot
1061   // Using all the declarations from third-party libraries which are
1062   // used in the .cpp files.
1063   namespace third_party_namespace {
1064     using third_party_decl_used_in_cpp_1;
1065     using third_party_decl_used_in_cpp_2;
1066     ...
1067     using third_party_decl_used_in_cpp_n;
1068   }
1069   #endif
1070
1071 (And add `EXPORT` and conditional include to the headers as suggested in the
1072 export extern-C++ style section.)
1073
1074 The ABI with modules is different and thus we need to compile the source files
1075 into the new ABI. This is done by an additional part of the interface unit:
1076
1077 .. code-block:: c++
1078
1079   #if the number of .cpp files in your project are small
1080   module :private;
1081   #include "source_1.cpp"
1082   #include "source_2.cpp"
1083   ...
1084   #include "source_n.cpp"
1085   #else // the number of .cpp files in your project are a lot
1086   // Using all the declarations from third-party libraries which are
1087   // used in the .cpp files.
1088   namespace third_party_namespace {
1089     using third_party_decl_used_in_cpp_1;
1090     using third_party_decl_used_in_cpp_2;
1091     ...
1092     using third_party_decl_used_in_cpp_n;
1093   }
1094   #endif
1095
1096 If the number of source files is small, everything can be put in the private
1097 module fragment directly (it is recommended to add conditional includes to the
1098 source files as well). However, compile time performance will be bad if there
1099 are a lot of source files to compile.
1100
1101 **Note that the private module fragment can only be in the primary module
1102 interface unit and the primary module interface unit containing the private
1103 module fragment should be the only module unit of the corresponding module.**
1104
1105 In this case, source files (.cpp files) must be converted to module
1106 implementation units:
1107
1108 .. code-block:: c++
1109
1110   #ifndef IN_MODULE_INTERFACE
1111   // List all the includes here.
1112   #include "third_party/A/headers.h"
1113   ...
1114   #include "header.h"
1115   #endif
1116
1117   module your_library;
1118
1119   // Following off should be unchanged.
1120   ...
1121
1122 The module implementation unit will import the primary module implicitly. Do
1123 not include any headers in the module implementation units as it avoids
1124 duplicated declarations between translation units. This is why non-exported
1125 using declarations should be added from third-party libraries in the primary
1126 module interface unit.
1127
1128 If the library is provided as ``libyour_library.so``, a modular library (e.g.,
1129 ``libyour_library_modules.so``) may also need to be provided for ABI
1130 compatibility.
1131
1132 What if there are headers only included by the source files
1133 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1134
1135 The above practice may be problematic if there are headers only included by the
1136 source files. When using a private module fragment, this issue may be solved by
1137 including those headers in the private module fragment. While it is OK to solve
1138 it by including the implementation headers in the module purview when using
1139 implementation module units, it may be suboptimal because the primary module
1140 interface units now contain entities that do not belong to the interface.
1141
1142 This can potentially be improved by introducing a module partition
1143 implementation unit. An internal module partition unit is an importable
1144 module unit which is internal to the module itself.
1145
1146 Providing a header to skip parsing redundant headers
1147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1148
1149 Many redeclarations shared between translation units causes Clang to have
1150 slower compile-time performance. Further, there are known issues with
1151 `include after import <https://github.com/llvm/llvm-project/issues/61465>`_.
1152 Even when that issue is resolved, users may still get slower compilation speed
1153 and larger BMIs. For these reasons, it is recommended to not include headers
1154 after importing the corresponding module. However, it is not always easy if the
1155 library is included by other dependencies, as in:
1156
1157 .. code-block:: c++
1158
1159   #include "third_party/A.h" // #include "your_library/a_header.h"
1160   import your_library;
1161
1162 or
1163
1164 .. code-block:: c++
1165
1166   import your_library;
1167   #include "third_party/A.h" // #include "your_library/a_header.h"
1168
1169 For such cases, it is best if the library providing both module and header
1170 interfaces also provides a header which skips parsing so that the library can
1171 be imported with the following approach that skips redundant redeclarations:
1172
1173 .. code-block:: c++
1174
1175   import your_library;
1176   #include "your_library_imported.h"
1177   #include "third_party/A.h" // #include "your_library/a_header.h" but got skipped
1178
1179 The implementation of ``your_library_imported.h`` can be a set of controlling
1180 macros or an overall controlling macro if using `#pragma once`. Then headers
1181 can be refactored to:
1182
1183 .. code-block:: c++
1184
1185   #pragma once
1186   #ifndef YOUR_LIBRARY_IMPORTED
1187   ...
1188   #endif
1189
1190 If the modules imported by the library provide such headers, remember to add
1191 them to ``your_library_imported.h`` too.
1192
1193 Importing modules
1194 ~~~~~~~~~~~~~~~~~
1195
1196 When there are dependent libraries providing modules, they should be imported
1197 in your module as well. Many existing libraries will fall into this category
1198 once the ``std`` module is more widely available.
1199
1200 All dependent libraries providing modules
1201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1202
1203 Of course, most of the complexity disappears if all the dependent libraries
1204 provide modules.
1205
1206 Headers need to be converted to include third-party headers conditionally. Then,
1207 for the export-using style:
1208
1209 .. code-block:: c++
1210
1211   module;
1212   import modules_from_third_party;
1213   #define IN_MODULE_INTERFACE
1214   #include "header_1.h"
1215   #include "header_2.h"
1216   ...
1217   #include "header_n.h"
1218   export module your_library;
1219   export namespace your_namespace {
1220     using decl_1;
1221     using decl_2;
1222     ...
1223     using decl_n;
1224   }
1225
1226 or, for the export extern-C++ style:
1227
1228 .. code-block:: c++
1229
1230   export module your_library;
1231   import modules_from_third_party;
1232   #define IN_MODULE_INTERFACE
1233   extern "C++" {
1234     #include "header_1.h"
1235     #include "header_2.h"
1236     ...
1237     #include "header_n.h"
1238   }
1239
1240 or, for the ABI-breaking style,
1241
1242 .. code-block:: c++
1243
1244   export module your_library;
1245   import modules_from_third_party;
1246   #define IN_MODULE_INTERFACE
1247   #include "header_1.h"
1248   #include "header_2.h"
1249   ...
1250   #include "header_n.h"
1251
1252   #if the number of .cpp files in your project are small
1253   module :private;
1254   #include "source_1.cpp"
1255   #include "source_2.cpp"
1256   ...
1257   #include "source_n.cpp"
1258   #endif
1259
1260 Non-exported ``using`` declarations are unnecessary if using implementation
1261 module units. Instead, third-party modules can be imported directly in
1262 implementation module units.
1263
1264 Partial dependent libraries providing modules
1265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1266
1267 If the library has to mix the use of ``include`` and ``import`` in its module,
1268 the primary goal is still the removal of duplicated declarations in translation
1269 units as much as possible. If the imported modules provide headers to skip
1270 parsing their headers, those should be included after the import. If the
1271 imported modules don't provide such a header, one can be made manually for
1272 improved compile time performance.
1273
1274 Reachability of internal partition units
1275 ----------------------------------------
1276
1277 The internal partition units are sometimes called implementation partition units in other documentation.
1278 However, the name may be confusing since implementation partition units are not implementation
1279 units.
1280
1281 According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
1282 `[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):
1283
1284   A translation unit U is necessarily reachable from a point P if U is a module
1285   interface unit on which the translation unit containing P has an interface
1286   dependency, or the translation unit containing P imports U, in either case
1287   prior to P.
1288
1289   All translation units that are necessarily reachable are reachable. Additional
1290   translation units on which the point within the program has an interface
1291   dependency may be considered reachable, but it is unspecified which are and
1292   under what circumstances.
1293
1294 For example,
1295
1296 .. code-block:: c++
1297
1298   // a.cpp
1299   import B;
1300   int main()
1301   {
1302       g<void>();
1303   }
1304
1305   // b.cppm
1306   export module B;
1307   import :C;
1308   export template <typename T> inline void g() noexcept
1309   {
1310       return f<T>();
1311   }
1312
1313   // c.cppm
1314   module B:C;
1315   template<typename> inline void f() noexcept {}
1316
1317 The internal partition unit ``c.cppm`` is not necessarily reachable by
1318 ``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``
1319 doesn't import ``c.cppm``. This leaves it up to the compiler to decide if
1320 ``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that
1321 indirectly imported internal partition units are not reachable.
1322
1323 The suggested approach for using an internal partition unit in Clang is
1324 to only import them in the implementation unit.
1325
1326 Known Issues
1327 ------------
1328
1329 The following describes issues in the current implementation of modules. Please
1330 see
1331 `the issues list for modules <https://github.com/llvm/llvm-project/labels/clang%3Amodules>`_
1332 for a list of issues or to file a new issue if you don't find an existing one.
1333 When creating a new issue for standard C++ modules, please start the title with
1334 ``[C++20] [Modules]`` (or ``[C++23] [Modules]``, etc) and add the label
1335 ``clang:modules`` if possible.
1336
1337 A high-level overview of support for standards features, including modules, can
1338 be found on the `C++ Feature Status <https://clang.llvm.org/cxx_status.html>`_
1339 page.
1340
1341 Including headers after import is not well-supported
1342 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1343
1344 The following example is accepted:
1345
1346 .. code-block:: c++
1347
1348   #include <iostream>
1349   import foo; // assume module 'foo' contain the declarations from `<iostream>`
1350
1351   int main(int argc, char *argv[])
1352   {
1353       std::cout << "Test\n";
1354       return 0;
1355   }
1356
1357 but if the order of ``#include <iostream>`` and ``import foo;`` is reversed,
1358 then the code is currently rejected:
1359
1360 .. code-block:: c++
1361
1362   import foo; // assume module 'foo' contain the declarations from `<iostream>`
1363   #include <iostream>
1364
1365   int main(int argc, char *argv[])
1366   {
1367       std::cout << "Test\n";
1368       return 0;
1369   }
1370
1371 Both of the above examples should be accepted.
1372
1373 This is a limitation of the implementation. In the first example, the compiler
1374 will see and parse ``<iostream>`` first then it will see the ``import``. In
1375 this case, ODR checking and declaration merging will happen in the
1376 deserializer. In the second example, the compiler will see the ``import`` first
1377 and the ``#include`` second which results in ODR checking and declarations
1378 merging happening in the semantic analyzer. This is due to a divergence in the
1379 implementation path. This is tracked by
1380 `#61465 <https://github.com/llvm/llvm-project/issues/61465>`_.
1381
1382 Ignored ``preferred_name`` Attribute
1383 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1384
1385 When Clang writes BMIs, it will ignore the ``preferred_name`` attribute on
1386 declarations which use it. Thus, the preferred name will not be displayed in
1387 the debugger as expected. This is tracked by
1388 `#56490 <https://github.com/llvm/llvm-project/issues/56490>`_.
1389
1390 Don't emit macros about module declaration
1391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1392
1393 This is covered by `P1857R3 <https://wg21.link/P1857R3>`_. It is mentioned here
1394 because we want users to be aware that we don't yet implement it.
1395
1396 A direct approach to write code that can be compiled by both modules and
1397 non-module builds may look like:
1398
1399 .. code-block:: c++
1400
1401   MODULE
1402   IMPORT header_name
1403   EXPORT_MODULE MODULE_NAME;
1404   IMPORT header_name
1405   EXPORT ...
1406
1407 The intent of this is that this file can be compiled like a module unit or a
1408 non-module unit depending on the definition of some macros. However, this usage
1409 is forbidden by P1857R3 which is not yet implemented in Clang. This means that
1410 is possible to write invalid modules which will no longer be accepted once
1411 P1857R3 is implemented. This is tracked by
1412 `#54047 <https://github.com/llvm/llvm-project/issues/54047>`_.
1413
1414 Until then, it is recommended not to mix macros with module declarations.
1415
1416
1417 In consistent filename suffix requirement for importable module units
1418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1419
1420 Currently, Clang requires the file name of an ``importable module unit`` to
1421 have ``.cppm`` (or ``.ccm``, ``.cxxm``, ``.c++m``) as the file extension.
1422 However, the behavior is inconsistent with other compilers. This is tracked by
1423 `#57416 <https://github.com/llvm/llvm-project/issues/57416>`_.
1424
1425 Incorrect ODR violation diagnostics
1426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1427
1428 ODR violations are a common issue when using modules. Clang sometimes produces
1429 false-positive diagnostics or fails to produce true-positive diagnostics of the
1430 One Definition Rule. One often-reported example is:
1431
1432 .. code-block:: c++
1433
1434   // part.cc
1435   module;
1436   typedef long T;
1437   namespace ns {
1438   inline void fun() {
1439       (void)(T)0;
1440   }
1441   }
1442   export module repro:part;
1443
1444   // repro.cc
1445   module;
1446   typedef long T;
1447   namespace ns {
1448       using ::T;
1449   }
1450   namespace ns {
1451   inline void fun() {
1452       (void)(T)0;
1453   }
1454   }
1455   export module repro;
1456   export import :part;
1457
1458 Currently the compiler incorrectly diagnoses the inconsistent definition of
1459 ``fun()`` in two module units. Because both definitions of ``fun()`` have the
1460 same spelling and ``T`` refers to the same type entity, there is no ODR
1461 violation. This is tracked by
1462 `#78850 <https://github.com/llvm/llvm-project/issues/78850>`_.
1463
1464 Using TU-local entity in other units
1465 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1466
1467 Module units are translation units, so the entities which should be local to
1468 the module unit itself should never be used by other units.
1469
1470 The C++ standard defines the concept of ``TU-local`` and ``exposure`` in
1471 `basic.link/p14 <https://eel.is/c++draft/basic.link#14>`_,
1472 `basic.link/p15 <https://eel.is/c++draft/basic.link#15>`_,
1473 `basic.link/p16 <https://eel.is/c++draft/basic.link#16>`_,
1474 `basic.link/p17 <https://eel.is/c++draft/basic.link#17>`_, and
1475 `basic.link/p18 <https://eel.is/c++draft/basic.link#18>`_.
1476
1477 However, Clang doesn't formally support these two concepts. This results in
1478 unclear or confusing diagnostic messages. Further, Clang may import
1479 ``TU-local`` entities to other units without any diagnostics. This is tracked
1480 by `#78173 <https://github.com/llvm/llvm-project/issues/78173>`_.
1481
1482 .. _header-units:
1483
1484 Header Units
1485 ============
1486
1487 How to build projects using header units
1488 ----------------------------------------
1489
1490 .. warning::
1491
1492    The support for header units, including related command line options, is
1493    experimental. There are still many unanswered question about how tools
1494    should interact with header units. The details described here may change in
1495    the future.
1496
1497 Quick Start
1498 ~~~~~~~~~~~
1499
1500 The following example:
1501
1502 .. code-block:: c++
1503
1504   import <iostream>;
1505   int main() {
1506     std::cout << "Hello World.\n";
1507   }
1508
1509 could be compiled with:
1510
1511 .. code-block:: console
1512
1513   $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
1514   $ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp
1515
1516 How to produce BMIs
1517 ~~~~~~~~~~~~~~~~~~~
1518
1519 Similar to named modules, ``--precompile`` can be used to produce a BMI.
1520 However, that requires specifying that the input file is a header by using
1521 ``-xc++-system-header`` or ``-xc++-user-header``.
1522
1523 The ``-fmodule-header={user,system}`` option can also be used to produce a BMI
1524 for header units which have a file extension like `.h` or `.hh`. The argument to
1525 ``-fmodule-header`` specifies either the user search path or the system search
1526 path. The default value for ``-fmodule-header`` is ``user``. For example:
1527
1528 .. code-block:: c++
1529
1530   // foo.h
1531   #include <iostream>
1532   void Hello() {
1533     std::cout << "Hello World.\n";
1534   }
1535
1536   // use.cpp
1537   import "foo.h";
1538   int main() {
1539     Hello();
1540   }
1541
1542 could be compiled with:
1543
1544 .. code-block:: console
1545
1546   $ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm
1547   $ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp
1548
1549 For headers which do not have a file extension, ``-xc++-header`` (or
1550 ``-xc++-system-header``, ``-xc++-user-header``) must be used to specify the
1551 file as a header. For example:
1552
1553 .. code-block:: c++
1554
1555   // use.cpp
1556   import "foo.h";
1557   int main() {
1558     Hello();
1559   }
1560
1561 .. code-block:: console
1562
1563   $ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
1564   $ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
1565
1566 How to specify dependent BMIs
1567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1568
1569 ``-fmodule-file`` can be used to specify a dependent BMI (or multiple times for
1570 more than one dependent BMI).
1571
1572 With the existing implementation, ``-fprebuilt-module-path`` cannot be used for
1573 header units (because they are nominally anonymous). For header units, use
1574 ``-fmodule-file`` to include the relevant PCM file for each header unit.
1575
1576 This is expect to be solved in a future version of Clang either by the compiler
1577 finding and specifying ``-fmodule-file`` automatically, or by the use of a
1578 module-mapper that understands how to map the header name to their PCMs.
1579
1580 Compiling a header unit to an object file
1581 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1582
1583 A header unit cannot be compiled to an object file due to the semantics of
1584 header units. For example:
1585
1586 .. code-block:: console
1587
1588   $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
1589   # This is not allowed!
1590   $ clang++ iostream.pcm -c -o iostream.o
1591
1592 Include translation
1593 ~~~~~~~~~~~~~~~~~~~
1594
1595 The C++ standard allows vendors to convert ``#include header-name`` to
1596 ``import header-name;`` when possible. Currently, Clang does this translation
1597 for the ``#include`` in the global module fragment. For example, the following
1598 example:
1599
1600 .. code-block:: c++
1601
1602   module;
1603   import <iostream>;
1604   export module M;
1605   export void Hello() {
1606     std::cout << "Hello.\n";
1607   }
1608
1609 is the same as this example:
1610
1611 .. code-block:: c++
1612
1613   module;
1614   #include <iostream>
1615   export module M;
1616   export void Hello() {
1617       std::cout << "Hello.\n";
1618   }
1619
1620 .. code-block:: console
1621
1622   $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
1623   $ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp
1624
1625 In the latter example, Clang can find the BMI for ``<iostream>`` and so it
1626 tries to replace the ``#include <iostream>`` with ``import <iostream>;``
1627 automatically.
1628
1629
1630 Differences between Clang modules and header units
1631 --------------------------------------------------
1632
1633 Header units have similar semantics to Clang modules. The semantics of both are
1634 like headers. Therefore, header units can be mimicked by Clang modules as in
1635 the following example:
1636
1637 .. code-block:: c++
1638
1639   module "iostream" {
1640     export *
1641     header "/path/to/libstdcxx/iostream"
1642   }
1643
1644 .. code-block:: console
1645
1646   $ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp
1647
1648 This example is simplified when using libc++:
1649
1650 .. code-block:: console
1651
1652   $ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
1653
1654 because libc++ already supplies a
1655 `module map <https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in>`_.
1656
1657 This raises the question: why are header units not implemented through Clang
1658 modules?
1659
1660 This is primarily because Clang modules have more hierarchical semantics when
1661 wrapping multiple headers together as one module, which is not supported by
1662 Standard C++ Header units. We want to avoid the impression that these
1663 additional semantics get interpreted as Standard C++ behavior.
1664
1665 Another reason is that there are proposals to introduce module mappers to the
1666 C++ standard (for example, https://wg21.link/p1184r2). Reusing Clang's
1667 ``modulemap`` may be more difficult if we need to introduce another module
1668 mapper.
1669
1670 Discovering Dependencies
1671 ========================
1672
1673 Without use of modules, all the translation units in a project can be compiled
1674 in parallel. However, the presence of module units requires compiling the
1675 translation units in a topological order.
1676
1677 The ``clang-scan-deps`` tool can extract dependency information and produce a
1678 JSON file conforming to the specification described in
1679 `P1689 <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html>`_.
1680 Only named modules are supported currently.
1681
1682 A compilation database is needed when using ``clang-scan-deps``. See
1683 `JSON Compilation Database Format Specification <JSONCompilationDatabase.html>`_
1684 for more information about compilation databases. Note that the ``output``
1685 JSON attribute is necessary for ``clang-scan-deps`` to scan using the P1689
1686 format. For example:
1687
1688 .. code-block:: c++
1689
1690   //--- M.cppm
1691   export module M;
1692   export import :interface_part;
1693   import :impl_part;
1694   export int Hello();
1695
1696   //--- interface_part.cppm
1697   export module M:interface_part;
1698   export void World();
1699
1700   //--- Impl.cpp
1701   module;
1702   #include <iostream>
1703   module M;
1704   void Hello() {
1705       std::cout << "Hello ";
1706   }
1707
1708   //--- impl_part.cppm
1709   module;
1710   #include <string>
1711   #include <iostream>
1712   module M:impl_part;
1713   import :interface_part;
1714
1715   std::string W = "World.";
1716   void World() {
1717       std::cout << W << std::endl;
1718   }
1719
1720   //--- User.cpp
1721   import M;
1722   import third_party_module;
1723   int main() {
1724     Hello();
1725     World();
1726     return 0;
1727   }
1728
1729 And here is the compilation database:
1730
1731 .. code-block:: text
1732
1733   [
1734   {
1735       "directory": ".",
1736       "command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",
1737       "file": "M.cppm",
1738       "output": "M.o"
1739   },
1740   {
1741       "directory": ".",
1742       "command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",
1743       "file": "Impl.cpp",
1744       "output": "Impl.o"
1745   },
1746   {
1747       "directory": ".",
1748       "command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",
1749       "file": "impl_part.cppm",
1750       "output": "impl_part.o"
1751   },
1752   {
1753       "directory": ".",
1754       "command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",
1755       "file": "interface_part.cppm",
1756       "output": "interface_part.o"
1757   },
1758   {
1759       "directory": ".",
1760       "command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",
1761       "file": "User.cpp",
1762       "output": "User.o"
1763   }
1764   ]
1765
1766 To get the dependency information in P1689 format, use:
1767
1768 .. code-block:: console
1769
1770   $ clang-scan-deps -format=p1689 -compilation-database P1689.json
1771
1772 to get:
1773
1774 .. code-block:: text
1775
1776   {
1777     "revision": 0,
1778     "rules": [
1779       {
1780         "primary-output": "Impl.o",
1781         "requires": [
1782           {
1783             "logical-name": "M",
1784             "source-path": "M.cppm"
1785           }
1786         ]
1787       },
1788       {
1789         "primary-output": "M.o",
1790         "provides": [
1791           {
1792             "is-interface": true,
1793             "logical-name": "M",
1794             "source-path": "M.cppm"
1795           }
1796         ],
1797         "requires": [
1798           {
1799             "logical-name": "M:interface_part",
1800             "source-path": "interface_part.cppm"
1801           },
1802           {
1803             "logical-name": "M:impl_part",
1804             "source-path": "impl_part.cppm"
1805           }
1806         ]
1807       },
1808       {
1809         "primary-output": "User.o",
1810         "requires": [
1811           {
1812             "logical-name": "M",
1813             "source-path": "M.cppm"
1814           },
1815           {
1816             "logical-name": "third_party_module"
1817           }
1818         ]
1819       },
1820       {
1821         "primary-output": "impl_part.o",
1822         "provides": [
1823           {
1824             "is-interface": false,
1825             "logical-name": "M:impl_part",
1826             "source-path": "impl_part.cppm"
1827           }
1828         ],
1829         "requires": [
1830           {
1831             "logical-name": "M:interface_part",
1832             "source-path": "interface_part.cppm"
1833           }
1834         ]
1835       },
1836       {
1837         "primary-output": "interface_part.o",
1838         "provides": [
1839           {
1840             "is-interface": true,
1841             "logical-name": "M:interface_part",
1842             "source-path": "interface_part.cppm"
1843           }
1844         ]
1845       }
1846     ],
1847     "version": 1
1848   }
1849
1850 See the P1689 paper for the meaning of the fields.
1851
1852 Getting dependency information per file with finer-grained control (such as
1853 scanning generated source files) is possible. For example:
1854
1855 .. code-block:: console
1856
1857   $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o
1858
1859 will produce:
1860
1861 .. code-block:: text
1862
1863   {
1864     "revision": 0,
1865     "rules": [
1866       {
1867         "primary-output": "impl_part.o",
1868         "provides": [
1869           {
1870             "is-interface": false,
1871             "logical-name": "M:impl_part",
1872             "source-path": "impl_part.cppm"
1873           }
1874         ],
1875         "requires": [
1876           {
1877             "logical-name": "M:interface_part"
1878           }
1879         ]
1880       }
1881     ],
1882     "version": 1
1883   }
1884
1885 Individual command line options can be specified after ``--``.
1886 ``clang-scan-deps`` will extract the necessary information from the specified
1887 options. Note that the path to the compiler executable needs to be specified
1888 explicitly instead of using ``clang++`` directly.
1889
1890 Users may want the scanner to get the transitional dependency information for
1891 headers. Otherwise, the project has to be scanned twice, once for headers and
1892 once for modules. To address this, ``clang-scan-deps`` will recognize the
1893 specified preprocessor options in the given command line and generate the
1894 corresponding dependency information. For example:
1895
1896 .. code-block:: console
1897
1898   $ 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.dep
1899   $ cat impl_part.dep
1900
1901 will produce:
1902
1903 .. code-block:: text
1904
1905   impl_part.ddi: \
1906     /usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \
1907     /usr/include/bits/types/mbstate_t.h \
1908     /usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \
1909     /usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \
1910     /usr/include/bits/types/__locale_t.h \
1911     ...
1912
1913 When ``clang-scan-deps`` detects the ``-MF`` option, it will try to write the
1914 dependency information for headers to the file specified by ``-MF``.
1915
1916 Possible Issues: Failed to find system headers
1917 ----------------------------------------------
1918
1919 If encountering an error like ``fatal error: 'stddef.h' file not found``,
1920 the specified ``<path-to-compiler-executable>/clang++`` probably refers to a
1921 symlink instead a real binary. There are four potential solutions to the
1922 problem:
1923
1924 1. Point the specified compiler executable to the real binary instead of the
1925    symlink.
1926 2. Invoke ``<path-to-compiler-executable>/clang++ -print-resource-dir`` to get
1927    the corresponding resource directory for your compiler and add that
1928    directory to the include search paths manually in the build scripts.
1929 3. For build systems that use a compilation database as the input for
1930    ``clang-scan-deps``, the build system can add the
1931    ``--resource-dir-recipe invoke-compiler`` option when executing
1932    ``clang-scan-deps`` to calculate the resource directory dynamically.
1933    The calculation happens only once for a unique ``<path-to-compiler-executable>/clang++``.
1934 4. For build systems that invoke ``clang-scan-deps`` per file, repeatedly
1935    calculating the resource directory may be inefficient. In such cases, the
1936    build system can cache the resource directory and specify
1937    ``-resource-dir <resource-dir>`` explicitly, as in:
1938
1939    .. code-block:: console
1940
1941      $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o
1942
1943
1944 Import modules with clang-repl
1945 ==============================
1946
1947 ``clang-repl`` supports importing C++20 named modules. For example:
1948
1949 .. code-block:: c++
1950
1951   // M.cppm
1952   export module M;
1953   export const char* Hello() {
1954       return "Hello Interpreter for Modules!";
1955   }
1956
1957 The named module still needs to be compiled ahead of time.
1958
1959 .. code-block:: console
1960
1961   $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
1962   $ clang++ M.pcm -c -o M.o
1963   $ clang++ -shared M.o -o libM.so
1964
1965 Note that the module unit needs to be compiled as a dynamic library so that
1966 ``clang-repl`` can load the object files of the module units. Then it is
1967 possible to import module ``M`` in clang-repl.
1968
1969 .. code-block:: console
1970
1971   $ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.
1972   # We need to load the dynamic library first before importing the modules.
1973   clang-repl> %lib libM.so
1974   clang-repl> import M;
1975   clang-repl> extern "C" int printf(const char *, ...);
1976   clang-repl> printf("%s\n", Hello());
1977   Hello Interpreter for Modules!
1978   clang-repl> %quit
1979
1980 Possible Questions
1981 ==================
1982
1983 How modules speed up compilation
1984 --------------------------------
1985
1986 A classic theory for the reason why modules speed up the compilation is: if
1987 there are ``n`` headers and ``m`` source files and each header is included by
1988 each source file, then the complexity of the compilation is ``O(n*m)``.
1989 However, if there are ``n`` module interfaces and ``m`` source files, the
1990 complexity of the compilation is ``O(n+m)``. Therefore, using modules would be
1991 a significant improvement at scale. More simply, use of modules causes many of
1992 the redundant compilations to no longer be necessary.
1993
1994 While this is accurate at a high level, this depends greatly on the
1995 optimization level, as illustrated below.
1996
1997 First is ``-O0``. The compilation process is described in the following graph.
1998
1999 .. code-block:: none
2000
2001   ├-------------frontend----------┼-------------middle end----------------┼----backend----┤
2002   │                               │                                       │               │
2003   └---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘
2004
2005   ├---------------------------------------------------------------------------------------┐
2006   |                                                                                       │
2007   |                                     source file                                       │
2008   |                                                                                       │
2009   └---------------------------------------------------------------------------------------┘
2010
2011               ├--------┐
2012               │        │
2013               │imported│
2014               │        │
2015               │  code  │
2016               │        │
2017               └--------┘
2018
2019 In this case, the source file (which could be a non-module unit or a module
2020 unit) would get processed by the entire pipeline. However, the imported code
2021 would only get involved in semantic analysis, which, for the most part, is name
2022 lookup, overload resolution, and template instantiation. All of these processes
2023 are fast relative to the whole compilation process. More importantly, the
2024 imported code only needs to be processed once during frontend code generation,
2025 as well as the whole middle end and backend. So we could get a big win for the
2026 compilation time in ``-O0``.
2027
2028 But with optimizations, things are different (the ``code generation`` part for
2029 each end is omitted due to limited space):
2030
2031 .. code-block:: none
2032
2033   ├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤
2034   │                           │                                               │                   │
2035   └--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘
2036
2037   ├-----------------------------------------------------------------------------------------------┐
2038   │                                                                                               │
2039   │                                         source file                                           │
2040   │                                                                                               │
2041   └-----------------------------------------------------------------------------------------------┘
2042                 ├---------------------------------------┐
2043                 │                                       │
2044                 │                                       │
2045                 │            imported code              │
2046                 │                                       │
2047                 │                                       │
2048                 └---------------------------------------┘
2049
2050 It would be very unfortunate if we end up with worse performance when using
2051 modules. The main concern is that when a source file is compiled, the compiler
2052 needs to see the body of imported module units so that it can perform IPO
2053 (InterProcedural Optimization, primarily inlining in practice) to optimize
2054 functions in the current source file with the help of the information provided
2055 by the imported module units. In other words, the imported code would be
2056 processed again and again in importee units by optimizations (including IPO
2057 itself). The optimizations before IPO and IPO itself are the most time-consuming
2058 part in whole compilation process. So from this perspective, it might not be
2059 possible to get the compile time improvements described, but there could be
2060 time savings for optimizations after IPO and the whole backend.
2061
2062 Overall, at ``-O0`` the implementations of functions defined in a module will
2063 not impact module users, but at higher optimization levels the definitions of
2064 such functions are provided to user compilations for the purposes of
2065 optimization (but definitions of these functions are still not included in the
2066 use's object file). This means the build speedup at higher optimization levels
2067 may be lower than expected given ``-O0`` experience, but does provide more
2068 optimization opportunities.
2069
2070 Interoperability with Clang Modules
2071 -----------------------------------
2072
2073 We **wish** to support Clang modules and standard C++ modules at the same time,
2074 but the mixing them together is not well used/tested yet. Please file new
2075 GitHub issues as you find interoperability problems.