Cpp Modules

mohitmishra786/low-level-dev-skills/skills/compilers/cpp-modules

by mohitmishra786bdc58472fa9fNo license253 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 months ago

C++20 modules skill for modern C++ projects. Use when working with named modules, module partitions, header units, CMake MODULE_SOURCES, Clang -fmodules-ts, BMI caching issues, or migrating from headers to modules. Activates on queries about C++20 modules, import statements, module interface units, header units, or BMI files.

Instructions onlySoftware Development

AI-generated overview

Guides agents through authoring, building, and debugging C++20 modules, including CMake and compiler integration.

What it does: This skill provides instructions for working with C++20 modules: named module interface units, module implementation units, partitions, and header units. It covers minimal code examples, compiler-specific build commands for Clang and GCC, CMake integration from version 3.25 through 3.28 and later, and a table of common module errors with fixes. It also explains interoperability with legacy headers and the Global Module Fragment.
When to use it: Use it when writing or importing C++20 modules, resolving module-related build errors such as missing BMIs or redefinitions, configuring CMake for module sources, or migrating a codebase from headers to modules.
Requirements: Requires a C++20-capable compiler such as Clang or GCC 11 or later, and optionally CMake 3.25 or later with a module-supporting generator like Ninja 1.11 or MSBuild. It ships no scripts; it is instructions only, with one reference document on CMake module support.

C++20 Modules

Purpose

Guide agents through authoring, building, and debugging C++20 modules: named modules vs header units, module partitions, CMake integration, compiler-specific flags, and interoperability with legacy headers.

Triggers

"How do I write a C++20 module?"
"How do I import a module in CMake?"
"What's the difference between a named module and a header unit?"
"My module gives 'cannot find module' errors"
"How do I use C++20 modules with Clang?"
"How do I migrate from headers to modules?"

Workflow

1. Module concepts overview

C++20 module kinds:├── Named module interface unit  (.cppm / .ixx)  — exports declarations├── Module implementation unit   (.cpp)           — defines module members├── Module partition             (.cppm)          — internal module subdivision└── Header unit                  (any header)     — import a legacy header as module

C++20 module kinds:├── Named module interface unit  (.cppm / .ixx)  — exports declarations├── Module implementation unit   (.cpp)           — defines module members├── Module partition             (.cppm)          — internal module subdivision└── Header unit                  (any header)     — import a legacy header as module

Named modules are the primary target. Header units are a bridge for legacy code. Avoid Global Module Fragment unless required for macro access.

2. Named module — minimal example

cpp

// math.cppm — module interface unitexport module math;          // declares the module name
export int add(int a, int b) { return a + b; }export double pi = 3.14159;
// Non-exported (module-private)int internal_helper() { return 42; }

// math.cppm — module interface unitexport module math;          // declares the module name
export int add(int a, int b) { return a + b; }export double pi = 3.14159;
// Non-exported (module-private)int internal_helper() { return 42; }

cpp

// main.cpp — consumerimport math;                 // import the module#include <iostream>          // legacy header (still works)
int main() {    std::cout << add(2, 3) << "\n";  // 5    std::cout << pi << "\n";}

// main.cpp — consumerimport math;                 // import the module#include <iostream>          // legacy header (still works)
int main() {    std::cout << add(2, 3) << "\n";  // 5    std::cout << pi << "\n";}

3. Module partitions

cpp

// math-core.cppm — partitionexport module math:core;     // partition 'core' of module 'math'
export int add(int a, int b) { return a + b; }

// math-core.cppm — partitionexport module math:core;     // partition 'core' of module 'math'
export int add(int a, int b) { return a + b; }

cpp

// math.cppm — primary module interfaceexport module math;export import :core;         // re-export the partition

// math.cppm — primary module interfaceexport module math;export import :core;         // re-export the partition

cpp

// math-impl.cpp — implementation unit (no export)module math;                 // belongs to 'math' module, not a partition// has access to all math declarations, but exports nothing

// math-impl.cpp — implementation unit (no export)module math;                 // belongs to 'math' module, not a partition// has access to all math declarations, but exports nothing

4. Header units — bridging legacy headers

cpp

// Import a standard library header as a module unitimport <iostream>;           // header unit (compiler generates BMI)import <vector>;
// Or import a project header (must be compilable as header unit)import "myheader.h";

// Import a standard library header as a module unitimport <iostream>;           // header unit (compiler generates BMI)import <vector>;
// Or import a project header (must be compilable as header unit)import "myheader.h";

Header units do NOT provide macros to importers. For macro access, use the Global Module Fragment:

cpp

module;                      // Global Module Fragment starts here#include <cassert>           // macros like assert() are availableexport module mymod;// ... rest of module

module;                      // Global Module Fragment starts here#include <cassert>           // macros like assert() are availableexport module mymod;// ... rest of module

5. Building with Clang

bash

# Compile module interface → produces .pcm (precompiled module)clang++ -std=c++20 --precompile math.cppm -o math.pcm
# Compile implementation using the .pcmclang++ -std=c++20 -fmodule-file=math=math.pcm -c math.cpp -o math.o
# Compile consumerclang++ -std=c++20 -fmodule-file=math=math.pcm main.cpp math.o -o prog

# Compile module interface → produces .pcm (precompiled module)clang++ -std=c++20 --precompile math.cppm -o math.pcm
# Compile implementation using the .pcmclang++ -std=c++20 -fmodule-file=math=math.pcm -c math.cpp -o math.o
# Compile consumerclang++ -std=c++20 -fmodule-file=math=math.pcm main.cpp math.o -o prog

6. Building with GCC

bash

# GCC ≥11 supports modules (experimental ≥11, better ≥14)# Compile interface unit → produces .gcm in gcm.cache/g++ -std=c++20 -fmodules-ts math.cppm -c -o math.o
# Compiler auto-discovers .gcm files in gcm.cache/g++ -std=c++20 -fmodules-ts main.cpp math.o -o prog

# GCC ≥11 supports modules (experimental ≥11, better ≥14)# Compile interface unit → produces .gcm in gcm.cache/g++ -std=c++20 -fmodules-ts math.cppm -c -o math.o
# Compiler auto-discovers .gcm files in gcm.cache/g++ -std=c++20 -fmodules-ts main.cpp math.o -o prog

7. CMake integration (CMake ≥3.28)

cmake

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    # module interface units            src/math.cppm            src/math-core.cppm    PRIVATE        src/math-impl.cpp             # implementation unit)
add_executable(myapp main.cpp)target_link_libraries(myapp PRIVATE math)

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    # module interface units            src/math.cppm            src/math-core.cppm    PRIVATE        src/math-impl.cpp             # implementation unit)
add_executable(myapp main.cpp)target_link_libraries(myapp PRIVATE math)

bash

# Requires a generator that supports modules (Ninja ≥1.11 or MSBuild)cmake -S . -B build -G Ninjacmake --build build

# Requires a generator that supports modules (Ninja ≥1.11 or MSBuild)cmake -S . -B build -G Ninjacmake --build build

For CMake 3.25–3.27 (experimental):

cmake

cmake_minimum_required(VERSION 3.25)set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "3c375311-a3c9-4396-a187-3227ef642046")set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP ON)

cmake_minimum_required(VERSION 3.25)set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "3c375311-a3c9-4396-a187-3227ef642046")set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP ON)

8. Common errors

Error	Cause	Fix
`module 'math' not found`	BMI not found in search path	Compile interface unit first; check `-fmodule-file=` flags
`cannot import header in module`	`#include` inside module purview	Move `#include` to Global Module Fragment or use `import <>`
`redefinition of module 'math'`	Two `.cppm` files declare same module	Only one primary interface per module
`macro not available after import`	Macros don't cross module boundaries	Move macro-dependent code to GMF or use `#include`
`ODR violation`	Same name in multiple partitions	Each name exported from exactly one partition
BMI cache stale	`.pcm`/`.gcm` not rebuilt after change	Clean build or ensure dependency tracking is working

9. Interop with legacy headers

cpp

// Wrapping a C library for module useexport module cjson;
module;                       // Global Module Fragment#include <cjson/cJSON.h>      // C header with macros
export module cjson;          // back to module purview
// Re-export key types (optional)export using ::cJSON;export using ::cJSON_Parse;

// Wrapping a C library for module useexport module cjson;
module;                       // Global Module Fragment#include <cjson/cJSON.h>      // C header with macros
export module cjson;          // back to module purview
// Re-export key types (optional)export using ::cJSON;export using ::cJSON_Parse;

For CMake module support details, see references/modules-cmake-support.md [blocked].

Related skills

Use skills/build-systems/build-acceleration for PCH as a modules alternative
Use skills/compilers/gcc or skills/compilers/clang for compiler-specific module flags
Use skills/build-systems/cmake for CMake project configuration

Source and attribution

Source:mohitmishra786/low-level-dev-skillsinskills/compilers/cpp-modulesat commitbdc5847

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Cpp Modules

C++20 Modules

Purpose

Triggers

Workflow

1. Module concepts overview

2. Named module — minimal example

3. Module partitions

4. Header units — bridging legacy headers

5. Building with Clang

6. Building with GCC

7. CMake integration (CMake ≥3.28)

8. Common errors

9. Interop with legacy headers

Related skills

Source and attribution

More from mohitmishra786/low-level-dev-skills

Zig Debugging

Simd Intrinsics

Zig Cross

Rustc Basics

Zig Cinterop

Zig Build System

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices