# C++20 Modules

> Replace fragile textual header graphs with semantic module interfaces, controlled exports, module linkage, and clean boundaries around legacy headers.

- **Source:** C++ Atlas (https://cppatlas.com/topics/modules)
- **Track:** Program structure
- **Estimated reading time:** 9 minutes
- **ISO C++ clauses:** [module.unit] (https://eel.is/c++draft/module.unit), [module.interface] (https://eel.is/c++draft/module.interface), [module.import] (https://eel.is/c++draft/module.import), [module.global.frag] (https://eel.is/c++draft/module.global.frag), [module.private.frag] (https://eel.is/c++draft/module.private.frag), [module.reach] (https://eel.is/c++draft/module.reach), [basic.link] (https://eel.is/c++draft/basic.link)
- **cppreference links:** [Modules](https://en.cppreference.com/w/cpp/language/modules), [identifier with special meaning: module](https://en.cppreference.com/w/cpp/identifier_with_special_meaning/module), [identifier with special meaning: import](https://en.cppreference.com/w/cpp/identifier_with_special_meaning/import), [keyword: export](https://en.cppreference.com/w/cpp/keyword/export), [Translation-unit-local entities](https://en.cppreference.com/w/cpp/language/tu_local)
- **Prerequisites:** translation-units-and-linkage, name-lookup-and-adl

Traditional C++ headers rely on phase 4 textual splicing: every `#include` pastes raw tokens into every consumer translation unit, causing macro leakage in both directions, order-dependent compiles, and quadratic build times. **C++20 modules** replace textual inclusion with semantic translation units compiled once into binary module interfaces (BMIs) and consumed via `import`.

## How modules replace textual inclusion

When a module interface unit is compiled, the compiler emits an interface representation describing only its exported API and reachable entities. Importers read that binary summary directly without re-parsing implementation bodies or legacy headers.

Three isolation guarantees follow immediately from compiling modules semantically rather than textually:

- **Macros never cross `import`.** Preprocessor `#define` directives inside a module interface unit stay strictly inside that unit; importers never inherit them, and macros defined by the importer never alter an already-compiled module.
- **Order independence.** Unlike `#include "a.hpp"` followed by `#include "b.hpp"`, importing named modules in any order produces identical symbol lookup.
- **Private helpers stay hidden.** Non-exported helper functions, constants, and `using namespace` directives inside a module never pollute an importer's namespace.

> **Mental model.** A `#include` copies source code before parsing; a module `import` loads an already-parsed semantic interface. Preprocessor state stops at the module boundary.

## Anatomy of a module unit

A **module unit** (`[module.unit]`) is any translation unit containing a `module-declaration`. Its source layout follows a strict three-zone sequence:

1. **Global module fragment (`module;`):** An optional preamble before the module declaration. Under `[module.global.frag]`, this region may contain *only* preprocessor directives (`#include`, `#define`, `#if`). Legacy headers included here belong to the global module rather than the named module, keeping their C/C++ linkage untouched.
2. **Module purview (`export module name;` or `module name;`):** Everything between the module declaration and an optional private fragment is attached to the named module. Names introduced here carry module ownership and cannot be redeclared identically in another module.
3. **Private module fragment (`module :private;`):** An optional tail inside a *primary module interface unit* (`[module.private.frag]`) when no separate implementation units exist. Declarations after `module :private;` remain invisible and unreachable to importers—useful for single-file libraries, though compiler support varies (`clang++` implements it today, whereas GCC 16 still rejects `module :private;`, making separate `module name;` implementation units more portable).

| Module unit kind | Opening declaration | Emits BMI? | Purpose |
| --- | --- | --- | --- |
| Primary module interface | `export module M;` | Yes | Defines the public exported surface of module `M` |
| Module implementation unit | `module M;` | No | Defines declarations promised by `M` without adding exports |
| Module partition interface | `export module M:part;` | Yes | Splits large interface `M`; must be `export import :part;` |
| Internal partition | `module M:impl;` | Yes | Shares internal helpers across `M` without re-exporting |
| Header unit | `import <vector>;` | Yes | Wraps a legacy header as a precompiled semantic unit with macros |

## Visibility versus reachability

One of the deepest design insights of C++20 modules is the separation between **visibility** (`[module.interface]`) and **reachability** (`[module.reach]`). Adding `export` to a declaration makes its *name* visible to ordinary lookup in importing translation units. However, an entity that is **not** exported can still be **reachable** if an exported declaration refers to it in its return type, parameter type, or template argument.

When a type is reachable but not visible, importers cannot spell the type's name directly, yet they can still receive objects via `auto`, inspect member functions, invoke operators, and use `decltype` on expressions of that type.

```cpp
// File: math_core.cppm (module partition interface)
export module math:core;

export int square(int n) {
    return n * n;
}
```

```cpp
// File: math.cppm (primary module interface)
module;
#include <string> // Global module fragment: keeps <string> out of module purview

export module math;
export import :core; // Re-exports math:core so importers see square()

struct SecretHandle { // Not exported: invisible by name, yet reachable via make_handle()
    int value = 7;
    int read() const { return value; }
};

export SecretHandle make_handle() {
    return {};
}

export std::string greet(const std::string& who);
```

```cpp
// File: math_impl.cpp (module implementation unit)
module;
#include <string>

module math; // Implicitly imports primary module interface math

std::string greet(const std::string& who) {
    return "hi, " + who;
}
```

```cpp
// File: main.cpp (consumer)
import math;

int main() {
    auto handle = make_handle(); // Legal: SecretHandle is reachable via auto
    // SecretHandle raw;         // Error: SecretHandle is not visible to lookup
    return square(3) + handle.read() - 16;
}
```

Notice that `module math;` inside an implementation unit implicitly imports the primary module interface `math`, so `math_impl.cpp` can implement `greet` while seeing `SecretHandle` and all non-exported module-purview helpers.

> **Standardese.** Under `[module.reach]`, a declaration is reachable from an importer whenever an exported declaration exposes its type, base class, or template specialization—even if the declaration itself omits `export`. Lookup visibility requires `export`, whereas semantic completeness (member access, overload checks, destruction) requires only reachability.

## Module linkage and TU-local exposure

Because a named module can span multiple implementation units and internal partitions, C++20 introduced **module linkage** (`[basic.link]`). A non-exported namespace-scope function, class, or variable declared inside a module purview (outside unnamed namespaces and without `static`) has module linkage: every translation unit belonging to module `M` shares that single entity, while all external modules and non-module code cannot link against it.

By contrast, declaring a helper `static` or placing it inside `namespace { ... }` gives it **internal linkage**, making it a **translation-unit-local (TU-local)** entity (`[basic.link]`). Exposing a TU-local entity inside an exported `inline` function, exported template, or exported variable initializer makes the module **ill-formed** (no diagnostic required in corner cases, though modern compilers actively warn or reject it).

> **Pitfall.** Never `#include` a legacy header *after* `export module M;`. Putting `#include <vector>` inside the module purview attaches every declaration inside `<vector>` to module `M`, breaking linkage when another translation unit includes `<vector>` in the global module. Always place legacy `#include` directives between `module;` and `export module M;`.

> **Pitfall.** Calling a `static` helper or referencing an unnamed-namespace constant from an `export inline` function inside a module interface triggers a TU-local exposure error. Either drop `static` (giving the helper module linkage across your module) or mark it `inline` without internal linkage.

## Partitions, header units, and contextual keywords

Large modules split cleanly using **partitions**: `export module M:core;` defines an interface partition that `M` re-exports via `export import :core;`, while `module M:impl;` defines an internal partition that `M` imports via `import :impl;` without exposing it to callers. Note that external consumers can never write `import M:core;` directly—only units of module `M` can import partitions of `M`.

For incremental migration, C++20 provides **header units** (`import <vector>;` or `import "legacy.hpp";`). Unlike named modules, header units *do* export preprocessor macros defined inside the header, allowing gradual replacement of `#include` lines without breaking macro-heavy libraries. Finally, `module` and `import` are **identifiers with special meaning** (`[lex.name]`), not reserved keywords—existing variables or parameters named `module` or `import` remain valid outside module-declaration and import-declaration positions.

## What to remember

- Place legacy `#include` directives strictly inside the **global module fragment** (`module;`) before `export module M;`.
- Macros and unexported declarations stay inside the module; `export import :part;` re-exports module partitions to importers.
- `export` grants **lookup visibility**, whereas returning or referencing an unexported type makes it **reachable** for `auto`, member calls, and destruction.
- Non-exported module-purview entities have **module linkage** (shared across `M`'s units only); never expose `static` or unnamed-namespace **TU-local** entities from exported inline functions or templates.
- Named modules never export macros, whereas C++20 **header units** (`import <header>;`) preserve exported macros to ease migration.

## Concept Map Outline

- **C++20 Modules:** Replaces textual header inclusion with semantic binary interfaces, explicit exports, and module linkage.
  - **Module Isolation:** Compiles an interface once semantically without leaking preprocessor state or parsing order.
    - **Macro Encapsulation:** Macros defined inside a named module never escape export boundaries to importers.
    - **Order Independence:** Importing named modules in any sequence produces identical lookup and compilation.
  - **Unit Structure:** A module unit transitions from global fragment through module purview to optional private fragment.
    - **Global Module Fragment:** Region between module; and export module M; reserved solely for legacy #include directives.
    - **Module Purview:** All declarations after the module declaration attach to that named module.
    - **Private Module Fragment:** Optional module :private; tail hiding single-TU implementation details from importers.
  - **Visibility vs. Reachability:** Exporting controls name lookup visibility while referenced unexported types stay reachable.
    - **Visible Declarations:** Exported names can be spelled directly by importing translation units.
    - **Reachable Unexported Types:** Return or parameter types omitted from export still work via auto and member access.
  - **Linkage & TU-Local:** Separates module-wide internal sharing from translation-unit-private symbols.
    - **Module Linkage:** Non-exported purview entities share one definition across units of the same module.
    - **TU-Local Exposure:** Exported inline functions and templates must not expose static or unnamed-namespace entities.
  - **Partitions & Header Units:** Supports modular sub-units internally and macro-preserving header imports for migration.
    - **Module Partitions:** Interface and internal partitions split module M and are importable only within M.
    - **Header Units:** Syntactic import <header>; builds a precompiled semantic unit while exporting macros.

## Standardese Quiz Questions

### Question 1 [warmup] ([module.global.frag])

Where must legacy `#include <vector>` directives appear inside a module interface file?

A. Between `module;` and `export module M;` inside the global module fragment.
B. Immediately after `export module M;` inside the module purview.
C. Inside `export { #include <vector> }` so callers receive `std::vector`.
D. Inside `module :private;` at the end of the file.

**Answer (A):** Between `module;` and `export module M;` inside the global module fragment.

**Why:** Including a header after `export module M;` attaches all of its declarations to module M, conflicting with other units that include `<vector>` in the global module. Placing `#include` in the global module fragment (`module;`) keeps those declarations in the global module.

### Question 2 [warmup] ([module.import], [cpp.import])

What happens to a `#define DEBUG_TAG 1` macro written inside a named module interface unit `export module app;`?

A. It leaks to importers if placed after `export module app;`.
B. It is exported only if written as `export #define DEBUG_TAG 1`.
C. It never leaks to importers of `app`, because named modules do not export preprocessor macros.
D. It causes a compile error because `#define` is forbidden inside any module unit.

**Answer (C):** It never leaks to importers of `app`, because named modules do not export preprocessor macros.

**Why:** Named modules expose semantic declarations, never preprocessor state. Unlike `#include` or header units (`import <h>;`), macros defined in a named module never affect importing translation units.

### Question 3 [tricky] ([module.interface], [module.reach])

Given module `demo` below, which statement in `main.cpp` compiles cleanly?

```cpp
// demo.cppm
export module demo;
struct Box { int x = 9; };
export Box make_box() { return {}; }

// main.cpp
import demo;
```

A. Box b = make_box();
B. auto b = make_box(); int y = b.x;
C. export Box b = make_box();
D. Neither `Box` nor `b.x` can be used because `Box` is not exported.

**Answer (B):** auto b = make_box(); int y = b.x;

**Why:** Although `Box` is not exported—making its name invisible to unqualified lookup (`Box b` fails)—`Box` is reachable because exported `make_box()` returns it ([module.reach]). Therefore `auto b = make_box();` and accessing `b.x` are well-formed.

### Question 4 [tricky] ([module.import], [module.unit])

Why does writing `import math:core;` directly inside `main.cpp` (a non-module consumer file) fail to compile?

A. Because module partitions must be named with `::` instead of `:`.
B. Because module partitions can only be imported by translation units belonging to the same module `math`.
C. Because partitions cannot contain exported functions.
D. Because `main.cpp` must declare `module math;` before importing any module.

**Answer (B):** Because module partitions can only be imported by translation units belonging to the same module `math`.

**Why:** Under [module.import], a module-partition import (`import :core;`) has no module name prefix and is valid only inside translation units of the owning module. External consumers import the primary module (`import math;`), which uses `export import :core;` to expose interface partitions.

### Question 5 [standardese] ([basic.link], [module.interface])

Why is an `export inline` function inside module `M` ill-formed if it calls a `static` helper function declared in `M`'s purview?

```cpp
export module M;
static int secret() { return 1; }
export inline int api() { return secret(); }
```

A. Because `static` gives `secret` internal linkage (making it TU-local), and an exported inline entity cannot expose TU-local entities.
B. Because `inline` functions are forbidden inside C++20 module interfaces.
C. Because `static` functions in a module purview automatically receive external linkage and clash across units.
D. Because `api()` must be declared `constexpr` to call non-exported helpers.

**Answer (A):** Because `static` gives `secret` internal linkage (making it TU-local), and an exported inline entity cannot expose TU-local entities.

**Why:** In [basic.link], entities with internal linkage (such as namespace-scope `static` functions or unnamed-namespace declarations) are translation-unit-local. Exposing a TU-local entity from a non-TU-local inline function or template is ill-formed; dropping `static` gives `secret()` module linkage instead.

### Question 6 [standardese] ([lex.name], [module.unit])

In `int module = 3; int import = module + 1;` inside a regular function body, how does the lexer classify `module` and `import`?

A. Syntax error, because `module` and `import` became hard keywords in C++20.
B. Valid only when compiled without `-std=c++20`.
C. Valid only if placed inside `module :private;`.
D. Valid identifiers, because `module` and `import` are identifiers with special meaning only in module/import directive positions.

**Answer (D):** Valid identifiers, because `module` and `import` are identifiers with special meaning only in module/import directive positions.

**Why:** To preserve backward compatibility with existing C++ codebases using `module` or `import` as variable, parameter, or field names, C++20 made them identifiers with special meaning ([lex.name]) recognized only at the start of module-declarations and import-declarations.
