# Cpp Modules

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

- **Type:** Skill
- **Install:** `agentstack add skill-mohitmishra786-low-level-dev-skills-cpp-modules`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mohitmishra786](https://agentstack.voostack.com/s/mohitmishra786)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mohitmishra786](https://github.com/mohitmishra786)
- **Source:** https://github.com/mohitmishra786/low-level-dev-skills/tree/main/skills/compilers/cpp-modules
- **Website:** https://www.lowleveldevskills.com

## Install

```sh
agentstack add skill-mohitmishra786-low-level-dev-skills-cpp-modules
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```cpp
// 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; }
```

```cpp
// main.cpp — consumer
import math;                 // import the module
#include           // legacy header (still works)

int main() {
    std::cout ;           // header unit (compiler generates BMI)
import ;

// 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            // macros like assert() are available
export 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 .pcm
clang++ -std=c++20 -fmodule-file=math=math.pcm -c math.cpp -o math.o

# Compile consumer
clang++ -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
```

### 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)
```

```bash
# Requires a generator that supports modules (Ninja ≥1.11 or MSBuild)
cmake -S . -B build -G Ninja
cmake --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)
```

### 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 use
export module cjson;

module;                       // Global Module Fragment
#include       // 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](references/modules-cmake-support.md).

## 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 & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mohitmishra786](https://github.com/mohitmishra786)
- **Source:** [mohitmishra786/low-level-dev-skills](https://github.com/mohitmishra786/low-level-dev-skills)
- **License:** MIT
- **Homepage:** https://www.lowleveldevskills.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mohitmishra786-low-level-dev-skills-cpp-modules
- Seller: https://agentstack.voostack.com/s/mohitmishra786
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.