Modules

export marks a declaration as part of the module's public API, making it visible to anyone who writes import. Declarations without export stay internal to the module. export also forms the module declaration itself: export module name;.

#include is preprocessor text substitution — the header's text is pasted in and re-parsed. import loads an already-compiled Binary Module Interface, so macros do not leak in, import order is irrelevant, and only exported names become visible.

#include textually copies a header into every translation unit, so the same code is re-parsed repeatedly (slow builds), macros leak across files, include order matters, and there is no real encapsulation. Modules fix all four by compiling an interface once and isolating it semantically.

A BMI is a compiler-generated binary file holding the already-parsed semantic representation of a module interface. Consumers read the BMI instead of the source .cppm. Extensions vary: .gcm (GCC), .pcm (Clang), .ifc (MSVC).

An interface unit starts with export module name; and declares the module's public API — it is what consumers' import sees. An implementation unit starts with module name; (no export) and only defines bodies; consumers never see or compile it directly.

They remain fully usable inside the module — across its interface and implementation units — but are invisible to any consumer that writes import. This is real encapsulation: helper functions and details stay private without needing a separate detail namespace convention.

With #include, every translation unit re-parses the header's full text. A module interface is parsed once into a BMI; every consumer then reads that pre-digested semantic representation instead of re-tokenizing and re-analyzing the same source again and again.

Macros are a preprocessor concept with no scope, and stopping their uncontrolled leakage is a core goal of modules. import transfers compiled semantic entities, not preprocessor text, so a #define inside a module simply never reaches the consumer.

A PCH is a non-standard compiler cache of a header's textual state — macros still leak and one PCH usually serves the whole project. A BMI is a standard module artifact with real encapsulation: only exported names are visible and macros never cross the import boundary.

A module's BMI must be built before any consumer that imports it, so the build is now dependency-ordered. The build system must scan sources to discover import edges and schedule compilation in topological order — plain file timestamps are not enough.

export import X; imports module or partition X and re-exports its names to anyone importing the current module. A plain import X; keeps X private; export import builds facade modules and joins partitions into a primary interface.

It is the region opened by a bare module; line, before export module name;, where legacy #include directives are allowed. Entities pulled in there are usable inside the module but are not exported to consumers — it is the compatibility bridge to old headers.

A header unit is an existing header compiled into BMI form and pulled in via import <vector>;. It removes re-parsing cost, but unlike a named module its macros still reach the consumer — so it is a migration bridge, not full module encapsulation.

A partition is a named sub-unit of one module, written export module math:basic;. Partitions let you split a large module across files while still presenting one module to consumers. The primary interface gathers them, often via export import :basic;.

Migrate incrementally, bottom-up: start with leaf libraries that have no outgoing dependencies, wrap legacy headers in the global module fragment, and move up the dependency graph. Use header units for not-yet-converted deps; require a module-aware build system like CMake 3.28+.

If one TU #includes a header while another imports a module wrapping the same code, the same entity gets two definitions through different paths. They must be token-for-token identical; any drift between header and module is an ODR violation, often silent and unchecked.

A BMI is a private serialization of one compiler's internal semantic representation; the C++20 standard never defines its format. It is unportable between compilers and often between versions of the same one, so every toolchain must regenerate it from source.