C++20 modules

Contract

Field	Bound contract
Trigger	The user writes or builds export module code, asks how named modules differ from header units, needs the CMake wiring for module interface units, or gets a module-not-found, redefinition, or stale-BMI error.
Authority	Read-only. The skill emits module source shapes, compiler invocations, and CMake snippets to chat; the user applies them. Rollback is not needed. No remote mutation.
Side effect	Chat output. Any scratch build to confirm a flag runs on scratch files.
Done	The module layout, the per-compiler build commands, and the CMake wiring are reported for the user's compiler and CMake version, and every error in the request maps to a cause and fix.

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

Failure class	Behavior
CMake older than 3.28	Report that stable module support starts at 3.28; the experimental 3.25 API is not recommended.
Makefile generator selected	Switch to Ninja; report that Make lacks the dynamic dependency support modules need.
import std; requested	Report it as toolchain-dependent and confirm on the user's standard library before promising it.
Compiler older than the current line	Confirm each flag with a scratch build; module support in earlier lines is uneven.
Precompiled headers as an alternative	PCH and build caching: use build-acceleration.

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.