Help/cmake-cxxmodules: describe the compilation strategy

1 files changed, 43 insertions, 0 deletions

diff --git a/Help/manual/cmake-cxxmodules.7.rst b/Help/manual/cmake-cxxmodules.7.rst
index 3ee6645..8f62b5a 100644
--- a/Help/manual/cmake-cxxmodules.7.rst
+++ b/Help/manual/cmake-cxxmodules.7.rst
@@ -12,6 +12,49 @@ 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 its
+``export`` 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.
+
+.. _`P1689R5`: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
+
+.. 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
 ================