Cpp Modules

C++20 modules

Contract

Inputs

• Compiler and version: required. Clang 23.1.0 and GCC 16.2 are current stable; both accept the commands below.
• CMake version when CMake is in use: required. Current stable is 4.4.3; the stable CXX_MODULES file set needs 3.28 or later.
• Generator: required with CMake. Ninja 1.11 or later, Ninja Multi-Config, or Visual Studio; Makefile generators do not support modules.
• Module layout the user has or wants: required. Primary interface, partitions, implementation units, and any legacy headers with macros.

Procedure

1. Classify each translation unit. Primary interface unit: export module m; in a .cppm (or .ixx) file. Partition interface: export module m:part;, re-exported from the primary with export import :part;. Implementation unit: module m; with no exports. Header unit: import <vector>; or import "local.h";, a bridge for legacy headers. Prefer named modules; use header units only to bridge. Done when: every file has one classification.

2. Handle macros. Macros do not cross import. Code that needs a header's macros puts #include in the global module fragment: a file that opens with module;, then the includes, then export module m;. Wrap a C library the same way and re-export with export using ::name;. Done when: every macro dependency is in a global module fragment.

3. Build with Clang. Precompile the interface: clang++ -std=c++20 --precompile math.cppm -o math.pcm. Compile users against it: clang++ -std=c++20 -fmodule-file=math=math.pcm -c main.cpp -o main.o. Link the interface's object as well: clang++ -std=c++20 -fmodule-file=math=math.pcm math.pcm main.o -o prog. Done when: the three commands are given in dependency order.

4. Build with GCC. g++ -std=c++20 -fmodules-ts -c math.cppm -o math.o writes math.gcm under gcm.cache/ in the working directory, and g++ -std=c++20 -fmodules-ts main.cpp math.o -o prog finds it there. GCC 16 also accepts -fmodules; both spellings compile on the installed 16 line. Done when: the interface is compiled before its importers and the cache directory is named.

5. Wire CMake 3.28 or later:

   cmake_minimum_required(VERSION 3.28)
   project(myproject LANGUAGES CXX)
   set(CMAKE_CXX_STANDARD 20)
   add_library(math)
   target_sources(math
       PUBLIC FILE_SET CXX_MODULES FILES src/math.cppm src/math-core.cppm
       PRIVATE src/math-impl.cpp)
   add_executable(myapp main.cpp)
   target_link_libraries(myapp PRIVATE math)
   

   Configure with cmake -S . -B build -G Ninja and build with cmake --build build. Install the interfaces with install(TARGETS math FILE_SET CXX_MODULES DESTINATION include/math). Done when: interface units are in the CXX_MODULES file set and the generator supports dynamic dependencies.

6. Map errors from the table; reproduce on scratch files when the message is not listed. Done when: each error has a cause and fix.

   Error	Cause	Fix
   module m not found	BMI absent or not on the lookup path	Compile the interface first; pass -fmodule-file=m=<path> (Clang) or run in the directory holding gcm.cache/ (GCC)
   #include inside the module purview rejected	Include placed after export module	Move it to the global module fragment or import a header unit
   redefinition of module m	Two files declare the same primary interface	One primary interface per module; make the second a partition
   macro undefined after import	Macros do not cross module boundaries	Global module fragment with #include
   ODR violation across partitions	One name exported from two partitions	Export each name from exactly one partition
   stale results after an edit	BMI not rebuilt	Rebuild the interface; with CMake, use a generator that tracks module dependencies

7. Confirm the commands on the installed compiler with a two-file scratch module before reporting. Done when: the scratch build links and runs.

Failure and recovery

Output

A chat report with the classified module layout, the ordered build commands for the user's compiler, the CMake snippet when CMake is in use, and the error table entries that apply.