cpp-modules

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

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

// math.cppm — module interface unit
export 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; }

// main.cpp — consumer
import 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

// math-core.cppm — partition
export module math:core;     // partition 'core' of module 'math'

export int add(int a, int b) { return a + b; }

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

// 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