skip to content

In C++20, how does a named module's interface unit differ from a header, and what can an importing file actually see?

level: middleimportance: should knowfreq 48%

answer

  1. compiled once, not pasted in
  2. export decides the importer's view
  3. module linkage for the rest
  4. implementation unit imports the primary
  5. global module fragment holds #includes

basics

~20 s

A module interface unit is compiled once into a binary interface; an importer sees only its exported declarations, never its macros or unexported names, and the importer's own macros cannot change how the module was compiled.

solid answer

~40 s

A header is pasted textually into every file that includes it, so every translation unit re-parses it and the includer's macros can change its meaning. A C++20 module interface unit starts with `export module mathlib;` and is compiled once into a built module interface that importers load with `import mathlib;`. Only namespace-scope declarations marked `export` are visible to importers; unexported ones get **module linkage**, so the module's other units can use them while importers cannot name them. Macros defined in a named module never reach importers, and imports are order-independent. A module implementation unit (`module mathlib;`) implicitly imports the primary interface, and `#include`s go in a global module fragment (`module;` before the module declaration), whose declarations importers do not see by name lookup.

code

cpp · 22 lines
cpp
// mathlib.cppm - primary module interface unit
module;
#include <cmath>
export module mathlib;

#define MATHLIB_PI 3.14159265358979

export namespace mathlib {
  double circle_area(double r) { return MATHLIB_PI * r * r; }
  double hypot2(double a, double b);
}
namespace mathlib {
  double helper(double x) { return x * x; }   // not exported: module linkage
}

// mathlib_impl.cpp - module implementation unit
module;
#include <cmath>            // needed again: the interface's fragment does not carry over
module mathlib;             // implicitly imports the primary interface
namespace mathlib {
  double hypot2(double a, double b) { return std::sqrt(helper(a) + helper(b)); }
}

go deeper

for a junior

Recall the shape: export module name; in the interface, export on what importers may use, import name; in the user, and that macros do not travel through an import.

for a middle

Explain the BMI, module linkage versus internal linkage, the implicit import in an implementation unit, and why a global module fragment's includes are invisible to importers.

for a senior

Show that you can reason about visibility versus linkage when a build fails, and that members defined in a class inside a named module are no longer implicitly inline.

for a principal

Weigh the gains of isolation and single parsing against BMIs being compiler- and flag-specific, which shapes how a library can ship modules at all.

## What a header actually is Before C++20 the only way to share declarations was `#include`. The preprocessor copies the header's text into the including file, so a header is not a unit of its own: it is re-parsed in every **translation unit** (a source file after preprocessing) that includes it, and its meaning depends on whatever macros happen to be defined above the `#include` line. A header pulled into 400 source files is parsed 400 times, precompiled headers aside. ## What a named module is C++20 adds **named modules**. A module is a set of **module units**, each a translation unit that begins with a module declaration: - **Primary module interface unit** – `export module mathlib;`. Exactly one per module. It says what the module offers. - **Module implementation unit** – `module mathlib;` (no `export`). It holds definitions and cannot itself be imported. - **Partitions** – `mathlib:vec` and similar, which split a large module; they are a topic of their own. The compiler turns an interface unit into a **built module interface** (BMI – Clang writes a `.pcm` file) plus an ordinary object file. An importer reads the BMI instead of re-parsing source text, which is where the build-time gain comes from. A BMI is a compiler artefact, not a portable file format: it depends on the compiler and on dialect options such as `-std`. ## What `export` controls Inside the module's purview (everything after the module declaration), a namespace-scope declaration is either: 1. **Exported** – written as `export int f();`, in an `export { ... }` block or inside `export namespace mathlib { ... }`. Importers find it by ordinary name lookup. 2. **Not exported** – it gets **module linkage**. Other units of the same module can use it; an importer cannot. Clang reports the attempt as "declaration of 'helper' must be imported from module 'mathlib' before it is required". 3. **Internal linkage** (`static`, an unnamed namespace) – visible only in its own unit, not even in the module's implementation units. Exporting such a name is ill-formed. One more rule surprises people: in the global module a member function defined inside its class is implicitly `inline`, but a member function attached to a named module is not. Writing the body in the class no longer means the definition is copied into every importer. ## Macros and order independence Importing a named module never makes macros visible. A `#define` in the interface unit is gone at the module boundary, and the importer's macros cannot leak into the module either, because the module was compiled before the importer existed. Two consequences: - For named modules, `import a; import b;` means the same as `import b; import a;` – no include-order effect can change meaning. - Configuration that a header expresses as a macro (`#define MATHLIB_USE_SIMD 1`) needs another channel: a `constexpr` variable, a separate small header, or a header unit (`import "config.h";`), which is the one form of import that does carry macros. ## The global module fragment A module unit that needs a legacy header puts it before the module declaration: ```cpp module; // global module fragment starts #include <cmath> export module mathlib; // module purview starts ``` Declarations from the fragment are attached to the **global module**, not to `mathlib`, and name lookup in an importing unit only finds declarations that appear after the module declaration. So an implementation unit that calls `std::sqrt` needs its own `#include <cmath>` in its own fragment – the interface unit's include does not travel with the implicit import. ## The comparison in one table | Question | Header with `#include` | Named module with `import` | |---|---|---| | Parsed how often | Once per including translation unit | Once, into a BMI | | Who decides what is visible | Everything in the text | Only `export`ed declarations | | Macros cross the boundary | Yes, both ways | No | | Include or import order matters | Yes | No | | Non-public helpers | Need a `detail` namespace by convention | Module linkage hides them | ## What interviewers listen for A good answer separates **visibility** (what name lookup finds) from **linkage** (whether the symbol exists for the linker): an unexported function with module linkage is still a real symbol in the object file, and the build still links the module's object file. A strong candidate also mentions that modules are a C++20 language feature whose build-system and toolchain support arrived later and unevenly, which is why many codebases still ship headers.

  • If a function in a module is not exported, does its symbol disappear from the object file?
    No. An unexported namespace-scope function has **module linkage**: it is still an external symbol that the module's other units link against, and Clang emits it with a module-qualified mangled name. `export` controls name lookup in importers, not whether the linker sees a symbol; only internal linkage (`static`, an unnamed namespace) keeps it local to one unit.
  • Can an implementation unit write import mathlib; to get the interface?
    No, and it does not need to. A unit declared `module mathlib;` already imports the primary interface implicitly, and the standard makes `import mathlib;` inside a unit of `mathlib` an error. It sees the interface's exported and module-linkage declarations, but not its internal-linkage names or the declarations from the interface's global module fragment.

A header is a recipe photocopied into every cookbook that wants it; a module is a sealed jar from one kitchen, with a label listing exactly what the buyer may use.

  • A module is just a precompiled header with new syntax.
  • Macros defined in a module interface are visible to every importer.
  • Every declaration in a module interface unit is exported automatically.
  • Unexported module functions have internal linkage like static functions.
  • An implementation unit sees the headers the interface unit included.
  • Import order matters the same way include order does.

Assumes C++20, which introduced named modules; the rules were checked against the C++23 draft N4950 and are unchanged in the C++26 draft N5050.