C++20 modules: export, import and partitions

A header is pasted text. Every .cpp file that includes it makes the compiler read and parse it again, so in a project of 300 files a common header is parsed 300 times, and a macro defined before the #include can change what it means. A C++20 modulenamed module: A part of a program declared with export module name; and brought into other files with import name;. It is compiled once into a module file, and importers get only the declarations it exports: never its other names and never its macros. is compiled once: the file that starts with export module geometry; is its interface, what it marks export is all that import geometry; gives another file, the rest stays private to the module, macros included, and the compiler saves the interface in a module filemodule file (BMI): The compiled form of a module interface that importers read instead of source text, such as geometry.pcm from Clang or gcm.cache/geometry.gcm from GCC. Clang's documentation calls it a built module interface, or BMI. It must exist before any importer is compiled. that importers read instead of text.

A large module can be split into partitions, such as geometry:shapes, that only the module’s own files import. You will build one module with a partition and an implementation unit on Apple clang 21 and GCC 16, read what the compilers say about the five mistakes that stop most first builds, and let CMake 4.4 work out the build order.

A header is pasted text; a module is compiled once

Every one of those 300 files also receives everything the header needed for itself: its helpers, the headers it includes and its macros. That is how two libraries end up fighting over a macro called min or a function called log. And when two files see a header’s definitions differently, because one of them defines a macro the other does not, the program breaks the one-definition ruleone-definition rule: The rule that a program holds exactly one definition of each ordinary function it uses. An inline function may be defined in every translation unit that uses it, as long as all the definitions are identical. More in “How C++ compiles: preprocess, compile and link” without any error. A module changes each of these:

The last row is the cost. Because an importer reads a module file, the module must be compiled first, and the build system has to know who imports whom. Most of this lesson is about meeting that rule.

export decides what an importer can use

The geometry module has four files. Look at all of them before reading the explanation below:

// The shapes partition: the types of the geometry module.
export module geometry:shapes;

export namespace geometry {

struct Rect {
    double width = 0;   // metres
    double height = 0;
};

struct Circle {
    double radius = 0;
};

}  // namespace geometry

// The primary interface of the geometry module: what an importer can use.
export module geometry;

export import :shapes;   // the partition's types, passed on to every importer

#define GEOMETRY_VERSION 2   // a macro: visible in this file only, never exported

export namespace geometry {
double area(const Rect& r);
double area(const Circle& c);
double perimeter(const Rect& r);
}  // namespace geometry

namespace geometry {
// Not exported: units of the geometry module may use these, importers may not.
inline constexpr double pi = 3.14159265358979;
double square(double x) { return x * x; }
}  // namespace geometry

// An implementation unit of geometry: the function bodies. It sees everything the interface declares.
module geometry;

namespace geometry {
double area(const Rect& r) { return r.width * r.height; }
double area(const Circle& c) { return pi * square(c.radius); }
double perimeter(const Rect& r) { return 2 * (r.width + r.height); }
}  // namespace geometry

#include <print>
import geometry;

int main() {
    geometry::Rect plot{12.5, 8.0};
    geometry::Circle well{1.2};
    std::println("plot: {:.2f} sq m, fence {:.2f} m", geometry::area(plot), geometry::perimeter(plot));
    std::println("well: {:.2f} sq m", geometry::area(well));
}

geometry.cppm is the primary module interface unitmodule interface unit: A file that starts with export module, as in export module geometry; or export module geometry:shapes;. The primary interface, the one without a partition name, exists once per module and decides what importers can use.: its first declaration, export module geometry;, names the module and says this file is its interface. A module has exactly one. Inside it, export namespace geometry { … } exports every declaration in that block, so importers can call area and perimeter. The constant pi and the function square sit in a namespace block without export: they belong to the module and have module linkagemodule linkage: What a name declared in a named module without export has: every file of that module may use it, and no file outside the module can., so every file of the module may use them and no importer can. The macro GEOMETRY_VERSION lives only in that one file.

geometry.cpp starts with module geometry;, without export. That makes it a module implementation unitmodule implementation unit: A file of a module that starts with module name; without export. It holds definitions, implicitly imports the primary interface and cannot be imported, so changing it does not change what importers read., the module’s equivalent of a .cpp file next to a header. The standard says such a unit implicitly imports the primary interface, so it sees Rect, pi and square without importing anything. The function bodies live here, and when one of them changes, only this file is compiled again: the module file, and so every importer, stays as it was.

main.cpp is an ordinary file. It includes <print>, imports geometry and uses the exported names with their namespace, as with any library; an #include and an import can sit in the same file. Step through which of the four files can use which name:

The exports travel along every import, and everything else stops at the edge of the module. That edge is what module linkage means, and the mistakes section below shows the error a file outside the module gets when it crosses it.

Partitions split one module into files that importers never see

geometry-shapes.cppm begins with export module geometry:shapes;. The part after the colon names a partitionmodule partition: A file of a module with a name after a colon, such as geometry:shapes. Only files of the same module can import it, with import :shapes;, and the primary interface must export every partition that is an interface unit.: a file that belongs to geometry but holds only a piece of it, here the two types. Three rules come with partitions:

1. Only the module’s own files can import a partition, with the short form import :shapes;. To the rest of the program the division into partitions is invisible: it imports geometry and nothing else.
2. Every interface partition must be exported by the primary interface, directly or through another partition. That is what export import :shapes; does: Rect and Circle reach every importer of geometry. The standard requires no diagnostic when you forget it, so the mistake can show up as a confusing error far away.
3. A partition without export, such as module geometry:detail;, is an internal partition: code that the module’s files share and that never becomes part of the interface.

Partitions are how a large module stays a set of reasonably sized files without exposing that split to its users. The build order follows the imports:

A module is compiled before every file that imports it

Here is the whole build with both compilers, file by file, in the order of the diagram:

from session import run

# Apple clang 21 builds standard modules only with -fcxx-modules. Each interface unit also writes its module file.
run("""
clang++ -std=c++23 -fcxx-modules -c geometry/geometry-shapes.cppm -fmodule-output=geometry-shapes.pcm -o geometry-shapes.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cppm -fmodule-output=geometry.pcm -o geometry.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cpp -o geometry-impl.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/main.cpp -o main.o
clang++ geometry-shapes.o geometry.o geometry-impl.o main.o -o plot
./plot
ls -1 *.pcm
# GCC 16 needs -fmodules, and writes its module files (.gcm) into gcm.cache/.
g++-16 -std=c++23 -fmodules -c geometry/geometry-shapes.cppm -o geometry-shapes.o
g++-16 -std=c++23 -fmodules -c geometry/geometry.cppm -o geometry.o
g++-16 -std=c++23 -fmodules -c geometry/geometry.cpp -o geometry-impl.o
g++-16 -std=c++23 -fmodules -c geometry/main.cpp -o main.o
g++-16 geometry-shapes.o geometry.o geometry-impl.o main.o -o plot
./plot
ls -1 gcm.cache
""")

$ clang++ -std=c++23 -fcxx-modules -c geometry/geometry-shapes.cppm -fmodule-output=geometry-shapes.pcm -o geometry-shapes.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cppm -fmodule-output=geometry.pcm -o geometry.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cpp -o geometry-impl.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/main.cpp -o main.o
$ clang++ geometry-shapes.o geometry.o geometry-impl.o main.o -o plot
$ ./plot
plot: 100.00 sq m, fence 41.00 m
well: 4.52 sq m
$ ls -1 *.pcm
geometry-shapes.pcm
geometry.pcm
# GCC 16 needs -fmodules, and writes its module files (.gcm) into gcm.cache/.
$ g++-16 -std=c++23 -fmodules -c geometry/geometry-shapes.cppm -o geometry-shapes.o
$ g++-16 -std=c++23 -fmodules -c geometry/geometry.cppm -o geometry.o
$ g++-16 -std=c++23 -fmodules -c geometry/geometry.cpp -o geometry-impl.o
$ g++-16 -std=c++23 -fmodules -c geometry/main.cpp -o main.o
$ g++-16 geometry-shapes.o geometry.o geometry-impl.o main.o -o plot
$ ./plot
plot: 100.00 sq m, fence 41.00 m
well: 4.52 sq m
$ ls -1 gcm.cache
geometry-shapes.gcm
geometry.gcm

Step through the Clang half of that session, one stage per command, with what each command wrote:

What each flag does:

• -fcxx-modules (Apple clang). Apple’s compiler reads export module as an error unless this flag is given, even with -std=c++23. Upstream Clang, for example the LLVM 23 that Homebrew installs, needs no flag.
• -fmodule-output=geometry.pcm (Clang). Compiling an interface unit writes the object file and, as a by-product, the module file. Clang’s documentation calls this one-phase compilation and says it is the model CMake uses.
• -fprebuilt-module-path=. (Clang). Where to look for module files. Clang expects geometry.pcm for the module and geometry-shapes.pcm for the partition geometry:shapes, the colon written as a hyphen.
• -fmodules (GCC). GCC 16’s release notes still call modules experimental and require this flag. GCC writes the module files into a folder called gcm.cache and finds them there again.

File names follow the compilers. Clang’s documentation asks for .cppm on interface units and partitions and .cpp on implementation units. GCC accepts any C++ suffix, .cppm and .ixx included. Microsoft’s compiler uses .ixx for interface units by default and the /interface option for other suffixes.

// What the compiler says about modules through the feature-test macros of C++20 and C++23.
#include <cstdio>
#include <version>

int main() {
#ifdef __cpp_modules
    std::printf("__cpp_modules     = %ld (the language feature)\n", static_cast<long>(__cpp_modules));
#else
    std::puts("__cpp_modules     is not defined");
#endif
#ifdef __cpp_lib_modules
    std::printf("__cpp_lib_modules = %ld (import std)\n", static_cast<long>(__cpp_lib_modules));
#else
    std::puts("__cpp_lib_modules is not defined");
#endif
}

from session import run

# Both builds below compile modules; only one compiler says so through __cpp_modules.
run("""
clang++ -std=c++23 -fcxx-modules features.cpp -o features && ./features
g++-16 -std=c++23 -fmodules features.cpp -o features && ./features
""")

$ clang++ -std=c++23 -fcxx-modules features.cpp -o features && ./features
__cpp_modules     is not defined
__cpp_lib_modules = 202207 (import std)
$ g++-16 -std=c++23 -fmodules features.cpp -o features && ./features
__cpp_modules     = 201810 (the language feature)
__cpp_lib_modules = 202207 (import std)

Read the two runs side by side: a test of __cpp_modules would call Apple clang unable to build modules, which it has just done, and a test of __cpp_lib_modules would send it to an import std; that fails, as the next lesson shows. To decide whether modules work, compile a small module in the build system’s configure step instead.

Five mistakes stop most first builds

Each command below makes one of the classic mistakes:

from session import run

run("""
# 1. Without the modules flag, both compilers read export module as ordinary code.
clang++ -std=c++23 -c geometry/geometry-shapes.cppm -o geometry-shapes.o
g++-16 -std=c++23 -c geometry/geometry-shapes.cppm -o geometry-shapes.o
# 2. An importer compiled before the module it imports.
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/main.cpp -o main.o
g++-16 -std=c++23 -fmodules -c geometry/main.cpp -o main.o
# The module built properly, then misuse.cpp: 3. a name that is not exported, 4. a macro of the interface.
clang++ -std=c++23 -fcxx-modules -c geometry/geometry-shapes.cppm -fmodule-output=geometry-shapes.pcm -o geometry-shapes.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cppm -fmodule-output=geometry.pcm -o geometry.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/misuse.cpp -o misuse.o
g++-16 -std=c++23 -fmodules -c geometry/geometry-shapes.cppm -o geometry-shapes.o
g++-16 -std=c++23 -fmodules -c geometry/geometry.cppm -o geometry.o
g++-16 -std=c++23 -fmodules -c geometry/misuse.cpp -o misuse.o
# 5. A partition imported from outside its module.
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/partition_outside.cpp -o outside.o
g++-16 -std=c++23 -fmodules -c geometry/partition_outside.cpp -o outside.o
""")

# 1. Without the modules flag, both compilers read export module as ordinary code.
$ clang++ -std=c++23 -c geometry/geometry-shapes.cppm -o geometry-shapes.o
geometry/geometry-shapes.cppm:2:8: error: expected template
    2 | export module geometry:shapes;
      |        ^
geometry/geometry-shapes.cppm:2:8: error: unknown type name 'module'
geometry/geometry-shapes.cppm:2:23: error: expected ';' after top level declarator
    2 | export module geometry:shapes;
      |                       ^
      |                       ;
geometry/geometry-shapes.cppm:2:24: error: a type specifier is required for all declarations
    2 | export module geometry:shapes;
      |                        ^
geometry/geometry-shapes.cppm:4:8: error: expected template
    4 | export namespace geometry {
      |        ^
geometry/geometry-shapes.cppm:4:18: error: redefinition of 'geometry' as different kind of symbol
    4 | export namespace geometry {
      |                  ^
geometry/geometry-shapes.cppm:2:15: note: previous definition is here
    2 | export module geometry:shapes;
      |               ^
geometry/geometry-shapes.cppm:1:1: error: missing 'export module' declaration in module interface unit
    1 | // The shapes partition: the types of the geometry module.
      | ^
7 errors generated.
[exit status 1]
$ g++-16 -std=c++23 -c geometry/geometry-shapes.cppm -o geometry-shapes.o
geometry/geometry-shapes.cppm:2:1: warning: keyword 'export' is enabled with '-fmodules'
    2 | export module geometry:shapes;
      | ^~~~~~
geometry/geometry-shapes.cppm:2:8: error: 'module' does not name a type
    2 | export module geometry:shapes;
      |        ^~~~~~
geometry/geometry-shapes.cppm:2:8: note: C++20 'module' only available with '-fmodules', which is not yet enabled with '-std=c++20'
geometry/geometry-shapes.cppm:4:1: warning: keyword 'export' is enabled with '-fmodules'
    4 | export namespace geometry {
      | ^~~~~~
[exit status 1]
# 2. An importer compiled before the module it imports.
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/main.cpp -o main.o
geometry/main.cpp:2:8: fatal error: module 'geometry' not found
    2 | import geometry;
      | ~~~~~~~^~~~~~~~
1 error generated.
[exit status 1]
$ g++-16 -std=c++23 -fmodules -c geometry/main.cpp -o main.o
In module imported at geometry/main.cpp:2:1:
geometry: error: failed to read compiled module: No such file or directory
geometry: note: compiled module file is 'gcm.cache/geometry.gcm'
geometry: note: imports must be built before being imported
geometry: fatal error: returning to the gate for a mechanical issue
compilation terminated.
[exit status 1]
# The module built properly, then misuse.cpp: 3. a name that is not exported, 4. a macro of the interface.
$ clang++ -std=c++23 -fcxx-modules -c geometry/geometry-shapes.cppm -fmodule-output=geometry-shapes.pcm -o geometry-shapes.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/geometry.cppm -fmodule-output=geometry.pcm -o geometry.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c geometry/misuse.cpp -o misuse.o
geometry/misuse.cpp:5:29: error: declaration of 'square' must be imported from module 'geometry' before it is required
    5 |     double side = geometry::square(3.0);   // declared in the module, but not exported
      |                             ^
geometry/geometry.cppm:17:8: note: declaration here is not visible
   17 | double square(double x) { return x * x; }
      |        ^
geometry/misuse.cpp:6:12: error: use of undeclared identifier 'GEOMETRY_VERSION'
    6 |     return GEOMETRY_VERSION;               // a macro of the interface file
      |            ^~~~~~~~~~~~~~~~
2 errors generated.
[exit status 1]
$ g++-16 -std=c++23 -fmodules -c geometry/geometry-shapes.cppm -o geometry-shapes.o
$ g++-16 -std=c++23 -fmodules -c geometry/geometry.cppm -o geometry.o
$ g++-16 -std=c++23 -fmodules -c geometry/misuse.cpp -o misuse.o

Reading the messages:

1. The modules flag is missing. Apple clang reports unknown type name 'module', because without -fcxx-modules the word is an ordinary name. GCC is kinder: its note says that C++20 module is only available with -fmodules.
2. The importer was compiled first. Clang says module 'geometry' not found; GCC names the file it looked for, gcm.cache/geometry.gcm, and adds that imports must be built before being imported. Compile in the order of the import graph, or let a build system work it out.
3. A name that is not exported. Clang’s message is the precise one: the declaration of square exists, but it is not visible outside the module. GCC simply reports that square is not a member of geometry.
4. A macro of the interface. Both compilers report an undeclared identifier: macros never cross an import. A value that importers need should be an exported constexpr variable instead.
5. A partition imported from outside. import geometry:shapes; is not valid syntax outside the module, so both compilers stop with a parse error at the colon. Import the module, which passes the partition on.

A module’s headers go in its global module fragment

Real modules need the standard library and other headers. They go into a global module fragmentglobal module fragment: The start of a module unit between module; and the module declaration. Only preprocessor directives such as #include may appear in it, and what they declare belongs to the global module, the module of every ordinary file. at the very top of the file, between module; and the module declaration:

// The headers a module needs go into its global module fragment, before the module declaration.
module;
#include <string>

export module greeting;

export std::string greet(const std::string& name) { return "Namaste, " + name + "!"; }

#include <print>
#include <string>
import greeting;

int main() { std::println("{}", greet("Kavya")); }

// The same module with the #include moved below the module declaration: a mistake.
export module greeting;

#include <string>

export std::string greet(const std::string& name) { return "Namaste, " + name + "!"; }

Only preprocessor directives may appear in that fragment. Declarations that come from it belong to the global module, the same one that ordinary files use, so the std::string that greet returns is the very type that hello.cpp gets from <string>. In greeting_wrong.cppm the #include comes after export module, so everything the header declares would be attached to the module greeting, as a second, private copy of the standard library:

from session import run

run("""
clang++ -std=c++23 -fcxx-modules -c gmf/greeting.cppm -fmodule-output=greeting.pcm -o greeting.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. gmf/hello.cpp greeting.o -o hello && ./hello
g++-16 -std=c++23 -fmodules gmf/greeting.cppm gmf/hello.cpp -o hello && ./hello
# The #include moved after export module:
clang++ -std=c++23 -fcxx-modules -c gmf/greeting_wrong.cppm -fmodule-output=greeting.pcm -o greeting.o
g++-16 -std=c++23 -fmodules -c gmf/greeting_wrong.cppm -o greeting.o
""", max_lines=14)

$ clang++ -std=c++23 -fcxx-modules -c gmf/greeting.cppm -fmodule-output=greeting.pcm -o greeting.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. gmf/hello.cpp greeting.o -o hello && ./hello
Namaste, Kavya!
$ g++-16 -std=c++23 -fmodules gmf/greeting.cppm gmf/hello.cpp -o hello && ./hello
Namaste, Kavya!
# The #include moved after export module:
$ clang++ -std=c++23 -fcxx-modules -c gmf/greeting_wrong.cppm -fmodule-output=greeting.pcm -o greeting.o
gmf/greeting_wrong.cppm:4:10: warning: '#include <filename>' attaches the declarations to the named module 'greeting', which is not usually intended; consider moving that directive before the module declaration [-Winclude-angled-in-module-purview]
    4 | #include <string>
      |          ^
In file included from gmf/greeting_wrong.cppm:4:
In file included from …/c++/v1/string:596:
In file included from …/c++/v1/__algorithm/remove.h:12:
In file included from …/c++/v1/__algorithm/find.h:35:
In file included from …/c++/v1/cwchar:118:
In file included from …/c++/v1/wchar.h:116:
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/wchar.h:67:
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/_wchar.h:92:
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/time.h:63:
/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/_time.h:111:39: error: declaration of 'tm' in the global module follows declaration in module greeting
  111 | char *_LIBC_CSTR        asctime(const struct tm *);
[94 more lines]
[exit status 1]
$ g++-16 -std=c++23 -fmodules -c gmf/greeting_wrong.cppm -o greeting.o
In file included from …/c++/16/bits/stl_algobase.h:63,
                 from …/c++/16/string:55,
                 from gmf/greeting_wrong.cppm:4:
…/c++/16/bits/stl_pair.h:102:12: error: conflicting declaration of 'struct std::_Index_tuple<_Indexes>' in module 'greeting'
  102 |     struct _Index_tuple;
      |            ^~~~~~~~~~~~
In file included from …/c++/16/bits/char_traits.h:52,
                 from …/c++/16/string:45:
…/c++/16/type_traits:4372:39: note: previously declared in global module
 4372 |   template<size_t... _Indexes> struct _Index_tuple { };
      |                                       ^~~~~~~~~~~~
In file included from …/c++/16/string:83:
…/c++/16/bits/memory_resource.h: In constructor 'std::pmr::polymorphic_allocator<_Tp>::polymorphic_allocator()':
…/c++/16/bits/memory_resource.h:138:33: error: block-scope extern declaration 'std::pmr::memory_resource* std::pmr::get_default_resource()' must not be attached to a named module [-Wtemplate-body]
[2 more lines]
[exit status 1]

Step through which module each declaration of the two files belongs to:

Clang names the mistake in its first warning and then fails on the clash between the module’s copy of the C library declarations and the global one; GCC reports the same clash as a conflicting declaration in module greeting.

CMake scans every file for imports before it compiles

CMake learns which files are module interfaces from a file set of type CXX_MODULES. Implementation units such as geometry.cpp are ordinary sources:

cmake_minimum_required(VERSION 3.28)
project(geometry_demo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

add_library(geometry)
target_sources(geometry
  PUBLIC
    FILE_SET CXX_MODULES FILES   # interface units, partitions included
      geometry.cppm
      geometry-shapes.cppm
  PRIVATE
    geometry.cpp                 # the implementation unit is an ordinary source
)

add_executable(plot main.cpp)
target_link_libraries(plot PRIVATE geometry)

CMake’s documentation lists what its module support needs:

• Generators: Ninja 1.11 or newer, Ninja Multi-Config, and Visual Studio 2022 or newer. The Makefile generators do not support modules.
• Compilers: Clang 16 or newer, GCC 14 or newer, and MSVC 14.34 or newer (Visual Studio 17.4).

Here is the project configured four ways on a Mac, with CMake 4.4.4 and Ninja 1.13.2, and built twice:

from cmake_tools import run

# CMake 4.4.4 and Ninja 1.13.2 with GCC 16: the build scans every file for imports, then compiles in their order.
run("""
cd geometry
cmake -S . -B build-gcc -G Ninja -DCMAKE_CXX_COMPILER=g++-16
""", keep=r"^-- (The CXX compiler identification|Build files)")
run("""
cmake --build build-gcc
./build-gcc/plot
# Homebrew's LLVM 23 scans with its own clang-scan-deps:
cmake -S . -B build-llvm -G Ninja -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
""", keep=r"^(\[|plot|well|-- (The CXX compiler identification|Build files))")
run("""
cmake --build build-llvm
./build-llvm/plot
""", keep=r"^(\[12/|plot|well)")
run("""
# Apple clang 21, and the Unix Makefiles generator, stop at the generate step:
cmake -S . -B build-clt -G Ninja -DCMAKE_CXX_COMPILER=clang++
""", keep=r"^(-- The CXX compiler identification|CMake Error|CMake Generate|  +\S)")
run("""
# The scanner CMake runs for upstream Clang is not part of the Command Line Tools:
xcrun --find clang-scan-deps
""")
run("""
cmake -S . -B build-make -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=g++-16
""", keep=r"^(-- The CXX compiler identification|CMake Error|CMake Generate|  +\S)")

$ cd geometry
$ cmake -S . -B build-gcc -G Ninja -DCMAKE_CXX_COMPILER=g++-16
-- The CXX compiler identification is GNU 16.2.0
-- Build files have been written to: build-gcc
[11 lines not shown]
$ cmake --build build-gcc
[1/12] Scanning geometry.cpp for CXX dependencies
[2/12] Scanning geometry.cppm for CXX dependencies
[3/12] Scanning geometry-shapes.cppm for CXX dependencies
[4/12] Generating CXX dyndep file CMakeFiles/geometry.dir/CXX.dd
[5/12] Scanning main.cpp for CXX dependencies
[6/12] Building CXX object CMakeFiles/geometry.dir/geometry-shapes.cppm.o
[7/12] Building CXX object CMakeFiles/geometry.dir/geometry.cppm.o
[8/12] Building CXX object CMakeFiles/geometry.dir/geometry.cpp.o
[9/12] Generating CXX dyndep file CMakeFiles/plot.dir/CXX.dd
[10/12] Linking CXX static library libgeometry.a
[11/12] Building CXX object CMakeFiles/plot.dir/main.cpp.o
[12/12] Linking CXX executable plot
$ ./build-gcc/plot
plot: 100.00 sq m, fence 41.00 m
well: 4.52 sq m
# Homebrew's LLVM 23 scans with its own clang-scan-deps:
$ cmake -S . -B build-llvm -G Ninja -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
-- The CXX compiler identification is Clang 23.1.2
-- Build files have been written to: build-llvm
[7 lines not shown]
$ cmake --build build-llvm
[12/12] Linking CXX executable plot
[11 lines not shown]
$ ./build-llvm/plot
plot: 100.00 sq m, fence 41.00 m
well: 4.52 sq m
# Apple clang 21, and the Unix Makefiles generator, stop at the generate step:
$ cmake -S . -B build-clt -G Ninja -DCMAKE_CXX_COMPILER=clang++
-- The CXX compiler identification is AppleClang 21.0.0.21000334
CMake Error in CMakeLists.txt:
  The target named "geometry" has C++ sources that may use modules, but the
  compiler does not provide a way to discover the import graph dependencies.
  See the cmake-cxxmodules(7) manual for details.  Use the
  CMAKE_CXX_SCAN_FOR_MODULES variable to enable or disable scanning.
CMake Generate step failed.  Build files cannot be regenerated correctly.
[9 lines not shown]
[exit status 1]
# The scanner CMake runs for upstream Clang is not part of the Command Line Tools:
$ xcrun --find clang-scan-deps
xcrun: error: unable to find utility "clang-scan-deps", not a developer tool or in PATH
[exit status 72]
$ cmake -S . -B build-make -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=g++-16
-- The CXX compiler identification is GNU 16.2.0
CMake Error in CMakeLists.txt:
  The target named "geometry" has C++ sources that may use modules, but
  modules are not supported by this generator:
    Unix Makefiles
  Modules are supported only by Ninja, Ninja Multi-Config, and Visual Studio
  generators for VS 17.4 and newer.  See the cmake-cxxmodules(7) manual for
  details.  Use the CMAKE_CXX_SCAN_FOR_MODULES variable to enable or disable
  scanning.
CMake Generate step failed.  Build files cannot be regenerated correctly.
[15 lines not shown]
[exit status 1]

Step through the GCC build one stage of Ninja’s log at a time, then the two configures that stopped:

Before compiling anything, the build ran a dependency scandependency scan: A build step in which the compiler reads a source file only to report which modules it provides and imports. CMake runs one for every source of a C++20 target, then orders the compiles so that each module is built before its importers. of every source, and the scans alone decided the order: the partition was compiled first, although CMakeLists.txt names it second. Apple clang is not on the documentation’s list. CMake asks upstream Clang for a file’s imports through a separate tool, clang-scan-deps, which the Command Line Tools do not include (xcrun --find in the session finds none), and it has no scanning rules for Apple’s compiler, so it stopped at the generate step with the message in the session. The Makefile generator was refused in the same way. Header units, import <vector>;, are not supported by CMake at all.

Practise: turn a header library into a module

This small library stores amounts in paise and prints rupees with Indian digit grouping, the last three digits first and then pairs, so ten million rupees prints as 1,00,00,000:

// A small header library: amounts in paise, printed with Indian digit grouping.
#pragma once
#include <string>

namespace money {

struct Amount {
    long long paise = 0;
};

Amount from_rupees(long long rupees, int paise = 0);
std::string to_text(Amount a);               // "₹12,34,567.50"
std::string group_indian(long long rupees);  // "12,34,567": the last three digits, then pairs

}  // namespace money

#include "money.h"

namespace money {

Amount from_rupees(long long rupees, int paise) { return Amount{rupees * 100 + paise}; }

std::string group_indian(long long rupees) {
    std::string digits = std::to_string(rupees);
    if (digits.size() <= 3) return digits;
    std::string out = digits.substr(digits.size() - 3);
    for (std::size_t end = digits.size() - 3; end > 0;) {
        std::size_t start = end >= 2 ? end - 2 : 0;
        out = digits.substr(start, end - start) + "," + out;
        end = start;
    }
    return out;
}

std::string to_text(Amount a) {
    std::string paise = std::to_string(a.paise % 100);
    if (paise.size() == 1) paise = "0" + paise;
    return "₹" + group_indian(a.paise / 100) + "." + paise;
}

}  // namespace money

#include <print>
#include "money.h"

int main() {
    money::Amount fees = money::from_rupees(1234567, 50);
    std::println("fees: {}", money::to_text(fees));
    std::println("grouped: {} and {}", money::group_indian(999), money::group_indian(10000000));
}

Turn it into a module called money with one partition, money:format, that holds group_indian. Keep the program’s output exactly the same. Check four things: main.cpp imports money and includes no header of the library; the partition is exported by the primary interface; the module’s own files include <string> only in their global module fragments; and the build works with both compilers, the partition compiled first. Here is one solution, and its build:

// The format partition: Indian digit grouping.
module;
#include <string>

export module money:format;

export namespace money {

std::string group_indian(long long rupees) {
    std::string digits = std::to_string(rupees);
    if (digits.size() <= 3) return digits;
    std::string out = digits.substr(digits.size() - 3);
    for (std::size_t end = digits.size() - 3; end > 0;) {
        std::size_t start = end >= 2 ? end - 2 : 0;
        out = digits.substr(start, end - start) + "," + out;
        end = start;
    }
    return out;
}

}  // namespace money

// The primary interface of money: amounts, and the format partition passed on to importers.
module;
#include <string>

export module money;
export import :format;

export namespace money {

struct Amount {
    long long paise = 0;
};

Amount from_rupees(long long rupees, int paise = 0) { return Amount{rupees * 100 + paise}; }

std::string to_text(Amount a) {
    std::string paise = std::to_string(a.paise % 100);
    if (paise.size() == 1) paise = "0" + paise;
    return "₹" + group_indian(a.paise / 100) + "." + paise;
}

}  // namespace money

#include <print>
#include <string>
import money;

int main() {
    money::Amount fees = money::from_rupees(1234567, 50);
    std::println("fees: {}", money::to_text(fees));
    std::println("grouped: {} and {}", money::group_indian(999), money::group_indian(10000000));
}

cmake_minimum_required(VERSION 3.28)
project(fees LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

add_library(money)
target_sources(money PUBLIC FILE_SET CXX_MODULES FILES money.cppm money-format.cppm)

add_executable(fees main.cpp)
target_link_libraries(fees PRIVATE money)

from session import run

run("""
# The header library, as given.
clang++ -std=c++23 money_header/money.cpp money_header/main.cpp -o fees-header
./fees-header
# The module: the partition first, then the primary interface, then the importer.
clang++ -std=c++23 -fcxx-modules -c money_module/money-format.cppm -fmodule-output=money-format.pcm -o money-format.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c money_module/money.cppm -fmodule-output=money.pcm -o money.o
clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. money_module/main.cpp money-format.o money.o -o fees
./fees
g++-16 -std=c++23 -fmodules money_module/money-format.cppm money_module/money.cppm money_module/main.cpp -o fees-gcc
./fees-gcc
""")

# The header library, as given.
$ clang++ -std=c++23 money_header/money.cpp money_header/main.cpp -o fees-header
$ ./fees-header
fees: ₹12,34,567.50
grouped: 999 and 1,00,00,000
# The module: the partition first, then the primary interface, then the importer.
$ clang++ -std=c++23 -fcxx-modules -c money_module/money-format.cppm -fmodule-output=money-format.pcm -o money-format.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. -c money_module/money.cppm -fmodule-output=money.pcm -o money.o
$ clang++ -std=c++23 -fcxx-modules -fprebuilt-module-path=. money_module/main.cpp money-format.o money.o -o fees
$ ./fees
fees: ₹12,34,567.50
grouped: 999 and 1,00,00,000
$ g++-16 -std=c++23 -fmodules money_module/money-format.cppm money_module/money.cppm money_module/main.cpp -o fees-gcc
$ ./fees-gcc
fees: ₹12,34,567.50
grouped: 999 and 1,00,00,000

GCC compiles all three files in one command because it handles them in the order they are given: list the partition first. With Clang, each interface writes its module file before the next file can read it.

Then test the seven ideas of this lesson against the geometry and greeting files: every choice you make is explained on the spot, and the ideas you have shown least come up first.

Interview questions

Fresher · What does export do in a C++ module, and what does an importer not get?

In a module interface unit, export marks the declarations that importers can see: a function, a type, a whole namespace block or a re-exported import such as export import :shapes;. Everything else declared in the module has module linkage: the module’s own files may use it, and an importer that names it gets an error. An importer never gets the module’s macros, because a named module carries no preprocessor state, and the module never sees the importer’s macros either. An importer also cannot import the module’s partitions; it imports the module, and the primary interface decides what is passed on. Finally, import only makes the module’s exported declarations available: it does not compile the module, so the module file must already exist.

Key takeaways

• An #include pastes a header’s text into every file that includes it, while a module is compiled once into a module file that importers read, so the module has to be built before them.
• export module name; starts the primary interface, export marks what importers can use, everything else has module linkage, and implementation units (module name;) hold bodies that can change without rebuilding importers.
• Partitions (export module name:part;) split a module into files that only the module can import, and the primary interface must export every interface partition.
• A module is compiled before its importers: Apple clang 21 needs -fcxx-modules, GCC 16 needs -fmodules, and neither compiler’s feature-test macro is a reliable sign that modules work.
• A module’s #include lines belong in its global module fragment, between module; and the module declaration, so that what the headers declare stays in the global module that every other file uses.
• CMake builds modules from a CXX_MODULES file set by scanning every file for imports first, with Ninja or Visual Studio, and stops at the generate step with Apple clang or a Makefile generator.