cmake-cxxmodules(7) — CMake 4.0.2 Documentation (original) (raw)

Added in version 3.28.

C++ 20 introduced the concept of "modules" to the language. The design requires build systems to order compilations among each other to satisfyimport statements reliably. CMake's implementation asks the compiler to scan source files for module dependencies during the build, collates scanning results to infer ordering constraints, and tells the build tool how to dynamically update the build graph.

Compilation Strategy

With C++ modules, compiling a set of C++ sources is no longer embarrassingly parallel. That is, any given source may first require the compilation of another source file first in order to provide a "CMI" (compiled module interface) or "BMI" (binary module interface) that C++ compilers use to satisfy import statements in other sources. With headers, sources could share their declarations so that any consumers could compile independently. With modules, declarations are now generated into these BMI files by the compiler during compilation based on the contents of the source file and itsexport statements.

The order necessary for compilation requires build-time resolution of the ordering because the order is controlled by the contents of the sources. This means that the ordering needs extracted from the source during the build to avoid regenerating the build graph via a configure and generate phase for every source change to get a correct build.

The general strategy is to use a "scanner" to extract the ordering dependency information and update the build graph with new edges between existing edges by taking the per-source scan results (represented by P1689R5 files) and "collating" the dependencies within a target and to modules produced by targets visible to the target. The primary task is to generate "module map" files to pass to each compile rule with the paths to the BMIs needed to satisfy import statements. The collator also has tasks to use the build-time information to fill out information including install rules for the module interface units, their BMIs, and properties for any exported targets with C++ modules.

Note

CMake is focusing on correct builds before looking at performance improvements. There are known tactics within the chosen strategy which may offer build performance improvements. However, they are being deferred until we have a working model against which to compare them. It is also important to note that a tactic useful in one situation (e.g., clean builds) may not be performant in a different situation (e.g., incremental builds). Finding a balance and offering controls to select the tactics is future work.

Scanning Control

Whether or not sources get scanned for C++ module usage is dependent on the following queries. The first query that provides a yes/no answer is used.

Note that any scanned source will be excluded from any unity build (seeUNITY_BUILD) because module-related statements can only happen at one place within a C++ translation unit.

Compiler Support

Compilers which CMake natively supports module dependency scanning include:

import std Support

Support for import std is limited to the following toolchain and standard library combinations:

The CMAKE_CXX_COMPILER_IMPORT_STD variable may be used to detect support for a standard level with the active C++ toolchain.

Note

This support is provided only when experimental support forimport std; has been enabled by theCMAKE_EXPERIMENTAL_CXX_IMPORT_STD gate.

Generator Support

The list of generators which support scanning sources for C++ modules include:

Limitations

There are a number of known limitations of the current C++ module support in CMake. This does not document known limitations or bugs in compilers as these can change over time.

For all generators:

For the Ninja Generators:

For the Visual Studio Generators: