8.7 C++20 Modules and Translation Unit Isolation

For four decades, C++ relied on a compilation model inherited directly from C: the preprocessor based header system. When you write #include <iostream>, the preprocessor textually includes declarations into a translation unit. C++20 Modules offer a compiled interface model that can improve dependency isolation and build times, but they coexist with headers in real codebases rather than making headers disappear overnight.

Let's look at translation unit isolation, compile bloat, and how to build modules.

When using standard headers, code compilation suffers from two main problems:

* Compilation Slowness: Every single file (called a translation unit) compiles in isolation. If multiple files include the same headers, the compiler must parse, check, and generate code for those headers repeatedly. This leads to hours of compile time for massive systems.

* Macro Pollution and Name Clashes: Because headers are simple copy paste operations, macro definitions and internal namespace details leak into your files, causing name clashes and silent compiler overrides.

A module is declared using the export module statement. Instead of raw text copy pasting, the compiler parses a module file (like Math.cppm) exactly once. It creates an Abstract Syntax Tree (AST) representation of the code, and serializes this into a binary module interface file (.pcm on Clang, .gcm on GCC, or .ifc on MSVC).

When another file writes import Math;, the compiler consumes the module interface produced by its toolchain instead of textually re-parsing a header. The exact artifact format and performance characteristics are implementation details, but imported macros do not leak through the named-module interface.

Let's see how to write a simple module interface and import it:

export module Math;

// Only functions prefixed with export are visible outside!
export int add(int a, int b) {
    return a + b;
}

// This function is internal and cannot be imported!
int helperCalculate(int x) {
    return x * 2;
}

#include <iostream>
import Math; // Import the compiled Math module

int main() {
    // Call the exported add function
    std::cout << "Result: " << add(5, 10) << '\n';
    return 0;
}

Unlike standard headers, compiling C++ modules is toolchain dependent. While the C++ ISO standard does not force a specific file extension, compiler vendors have established conventions:

- GCC and Clang commonly look for .cppm (C++ Module) or standard .cpp extensions.

- Microsoft Visual C++ (MSVC) expects .ixx for module interfaces.

Because the compiler must generate a module interface before importers can build, a build tool must understand dependency order. Current CMake, build2, and compiler-specific build flows can do this; the exact commands remain toolchain-dependent.

What if you need legacy preprocessor headers in a module file? Headers and named modules can coexist, but a textual include after the module declaration may attach declarations to that module and create surprising build or linkage behavior. The Global Module Fragment is the explicit place for includes that must remain outside the named module:

module; // Starts the global module fragment
#include <iostream> // Header includes are clean here

export module Math;

export void printSum(int a, int b) {
    std::cout << "Sum: " << (a + b) << std::endl;
}

C++23 specifies named standard-library modules such as std, but implementation support is still uneven. Treat import std; as a toolchain feature: verify support in your compiler, standard library, and build configuration before adopting it.

import std; // C++23: Precompiled standard library module

int main() {
    std::println("Hello from modern C++23 standard library modules!");
    return 0;
}

Modules allow you to separate the exported interface (what users see) from the actual code implementation (how it works) in a single file or across separate files, without using headers. Only symbols marked with the export keyword are visible to importers. All other classes, structures, and helper functions remain completely hidden, enforcing strong encapsulation at the module boundary.

* The Library Index Metaphor: Preprocessor header inclusion is like photocopying an entire dictionary page into every letter you write just to use one word. C++20 modules are like placing a small reference index sticker. You look up the word directly in the precompiled dictionary without copying any pages.