modules

Модуль объявляется через export module name;, экспортируемые сущности (функции, классы, переменные) помечаются ключевым словом export. Использующий код пишет import name; вместо #include "name.h". Ключевое отличие от заголовков не в синтаксисе, а в модели компиляции: модуль компилируется один раз в бинарное представление (обычно файл с расширением .pcm у Clang или .ifc у MSVC — конкретное расширение и формат зависят от компилятора), которое затем переиспользуется при каждом импорте — компилятору не нужно заново парсить текст модуля в каждой единице трансляции, которая его импортирует.A module is declared with export module name;, and exported entities (functions, classes, variables) are marked with the export keyword. Code that uses it writes import name; instead of #include "name.h". The key difference from headers isn't the syntax — it's the compilation model: a module compiles once into a binary representation (typically a file with a .pcm extension for Clang, or .ifc for MSVC — the exact extension and format is compiler-specific), which is then reused on every import — the compiler doesn't need to re-parse the module's text in every translation unit that imports it.

// math_utils.h// math_utils.h
#define PI 3.14159   // просачивается всюду, где есть #include// leaks everywhere this gets #included
int square(int x);

// main.cpp — заголовок парсится заново// main.cpp — the header is re-parsed
#include "math_utils.h"   // в каждой единице трансляции,// in every translation unit
                          // которая его включает// that includes it

// math_utils.cppm// math_utils.cppm
export module math_utils;
export int square(int x) { return x * x; }
                          // внутренний #define PI не виден снаружи// an internal #define PI isn't visible outside

// main.cpp — компилятор переиспользует// main.cpp — the compiler reuses
import math_utils;   // уже скомпилированное бинарное представление// the already-compiled binary representation

Модель #include, унаследованная от C, накопила за десятилетия три постоянные проблемы:The #include model, inherited from C, accumulated three persistent problems over the decades:

Компилятор, встретив export module name;, компилирует модуль в самостоятельный артефакт (Binary Module Interface, BMI) — не текстовый файл, а уже разобранное, семантически проверенное представление экспортируемого интерфейса модуля. При import name; компилятор подгружает этот готовый артефакт напрямую, минуя лексический анализ и парсинг исходного текста модуля заново. Отсюда и структурная защита от утечки макросов: препроцессорные директивы внутри модуля обрабатываются на этапе его собственной компиляции и не являются частью экспортируемого интерфейса — импортирующий код просто не видит текстовое содержимое модуля, только скомпилированный результат.When the compiler encounters export module name;, it compiles the module into a standalone artifact (a Binary Module Interface, BMI) — not a text file, but an already-parsed, semantically-checked representation of the module's exported interface. On import name;, the compiler loads that ready-made artifact directly, skipping lexing and re-parsing the module's source text. This is also where the structural protection against macro leakage comes from: preprocessor directives inside a module are processed during the module's own compilation and aren't part of the exported interface — importing code simply never sees the module's textual content, only the compiled result.

// пример module-единицы с частично приватной реализацией// an example module unit with a partly private implementation
export module geometry;

export struct Point { double x, y; };

export double distance(Point a, Point b);   // экспортируется// exported

namespace detail {
    double sqrt_impl(double x) { /* ... *//* ... */ }
}   // не помечено export — недоступно импортирующему коду вообще,// not marked export — completely inaccessible to importing code,
    // не просто "приватная секция", а невидимая сущность снаружи// not just a "private section" — an entity invisible from outside

Логический модуль не обязан жить в одном файле. Module implementation unit — отдельный файл, который принадлежит тому же модулю (директива module geometry; без export), но не является интерфейсом: в нём можно писать реализацию функций, объявленных в интерфейсном файле, без риска раздуть сам интерфейс телами функций.A logical module doesn't have to live in one file. A module implementation unit is a separate file belonging to the same module (a module geometry; directive, without export) that isn't part of the interface — it's where you write the implementation of functions declared in the interface file, without bloating the interface itself with function bodies.

// geometry.cppm — интерфейс модуля, только объявления// geometry.cppm — the module interface, declarations only
export module geometry;

export double distance(Point a, Point b);   // только объявление, без тела// declaration only, no body

// geometry_impl.cpp — implementation unit того же модуля// geometry_impl.cpp — an implementation unit of the same module
module geometry;   // без export — это НЕ интерфейс, а часть реализации// no export — this is NOT an interface, it's part of the implementation

double distance(Point a, Point b) {   // тело здесь, видно только внутри модуля geometry// the body lives here, visible only inside the geometry module
    return std::hypot(a.x - b.x, a.y - b.y);
}

Ещё один способ разбить крупный модуль на файлы — module partitions: export module geometry:shapes; объявляет часть ("партицию") модуля geometry, а сам главный интерфейсный файл собирает партиции воедино через export import :shapes;. Партиции видны друг другу внутри модуля, но снаружи модуль по-прежнему выглядит как единое целое — импортирующий код пишет один import geometry;, не подозревая о внутреннем разбиении на файлы.Another way to split a large module across files is module partitions: export module geometry:shapes; declares a "partition" of the geometry module, and the main interface file pulls the partitions together via export import :shapes;. Partitions are visible to each other inside the module, but from the outside the module still looks like a single unit — importing code writes one import geometry;, unaware of the internal split across files.

• cppreference — Modules
• WG21 P1103 — Merging Modules