skip to content

When a C++20 module mathlib is split into partitions, what must the primary interface do with them, and how do imports constrain build order?

level: seniorimportance: should knowfreq 28%

answer

  1. interface vs internal partitions
  2. export import :name
  3. partitions are private to the module
  4. importer waits for the BMI
  5. no cycles in the import graph

basics

~20 s

Every interface partition must be re-exported by the primary interface with export import :name; internal partitions stay private. Partitions are importable only inside their module, and since an importer needs each imported unit's BMI first, imports form an acyclic build order.

solid answer

~40 s

A partition is a module unit named `mathlib:vec`. With `export module mathlib:vec;` it is an **interface partition**, and the primary interface must export it directly or indirectly, usually with `export import :vec;` – a violation is ill-formed, no diagnostic required. With `module mathlib:detail;` it is an **internal partition** that only the module's own units import. Partitions are imported as `import :vec;` from inside `mathlib`; `import mathlib:vec;` is not valid syntax, so outside code cannot reach a partition. In practice every import is a compile-order edge: a unit cannot be compiled until the BMI of each unit it imports exists, so the build must scan files for imports first, and a cyclic import is ill-formed. Editing an interface partition invalidates every importer's input; editing an implementation unit does not.

code

cpp · 21 lines
cpp
// detail.cppm - internal partition
module mathlib:detail;
namespace mathlib { double mul(double a, double b) { return a * b; } }

// vec.cppm - interface partition
export module mathlib:vec;
import :detail;
export namespace mathlib {
  struct Vec2 { double x, y; };
  double dot(Vec2 a, Vec2 b) { return mul(a.x, b.x) + mul(a.y, b.y); }
}

// mathlib.cppm - primary interface
export module mathlib;
export import :vec;   // required: every interface partition must be exported
export namespace mathlib { double length2(Vec2 v) { return dot(v, v); } }

// main.cpp
#include <cstdio>
import mathlib;
int main() { std::printf("%.1f\n", mathlib::length2({3, 4})); }

go deeper

for a junior

Know that a module can be split into partitions named module:part and that importers still import only the module name.

for a middle

Explain interface versus internal partitions, export import :name in the primary interface, and why partitions cannot be imported from outside.

for a senior

Diagnose a missing re-export that compiles silently, design the partition graph so it stays acyclic and shallow, and predict what an edit rebuilds.

for a principal

Treat the partition layout as build-graph architecture: it decides parallelism and rebuild cost across the whole codebase, not just file tidiness.

## Why partitions exist One interface file for a large library becomes a bottleneck: every edit to it forces a recompile of every importer, and nothing that imports it can start until it is built. **Module partitions** let one named module be built from several units while importers still see a single module, `mathlib`. A partition is a module unit whose declaration has a colon-suffix: | Unit | Declaration | Role | |---|---|---| | Primary interface | `export module mathlib;` | The face of the module; exactly one | | Interface partition | `export module mathlib:vec;` | Part of the public interface | | Internal partition | `module mathlib:detail;` | Shared internals, never public | | Implementation unit | `module mathlib;` | Definitions; cannot be imported | Clang's documentation notes that internal partitions are sometimes called implementation partitions, and that the name misleads: they are importable units, unlike implementation units. ## The rules the primary interface must follow 1. **Every interface partition must be exported**, directly or indirectly, by the primary interface. The usual spelling is `export import :vec;`. The standard makes a violation ill-formed with **no diagnostic required**, so a compiler may accept a module that silently hides part of its interface. 2. **Partition names are unique** within a module. 3. **Partitions are private to the module.** Inside `mathlib` a unit writes `import :vec;` or `import :detail;`. Outside, there is no syntax for it: Clang parses `import mathlib:vec;` as a module name followed by stray tokens and reports "expected ';' after module name". 4. **Implicit imports differ.** An implementation unit `module mathlib;` implicitly imports the primary interface; a partition does not, so a partition that needs something from the primary interface must import it explicitly – and must not create a cycle while doing so. Clang adds a practical warning: importing an internal partition into an interface unit triggers `-Wimport-implementation-partition-unit-in-interface-unit`, because Clang does not treat indirectly imported internal partitions as reachable by importers. Its advice is to import internal partitions only from implementation units. ## Imports are build edges With headers, every source file can be compiled in parallel; the preprocessor reads header text on demand. With modules, `import X;` needs X's **BMI** to exist before the importing unit can compile. That turns the import graph into a compile-order graph: - The build must first **scan** every file for its module declaration and imports, then schedule units in dependency order. Doing that scan is the build system's job. - The graph must be **acyclic**. The standard says a translation unit shall not have an interface dependency on itself, and its example rejects `M1 → M2 → M3 → M1`. In practice the build cannot even begin: when two interfaces import each other, each compile fails because the other's BMI does not exist yet. - A **deep chain** of partitions serialises the build: `:vec` before `:matrix` before the primary interface before every importer. A wide, shallow graph keeps cores busy. ## What a change rebuilds - Editing an **interface partition** or the primary interface changes a BMI, so every unit that imports `mathlib` is out of date. Clang works to limit the cascade: since Clang 19, in what its documentation still calls an experimental optimisation, a change in a non-direct dependency should not change a BMI's output unless it affects that compilation. - Editing an **implementation unit** produces no BMI at all, only an object file, so importers are untouched – the module equivalent of keeping a definition out of a header. - Moving rarely-changing declarations into their own interface partition, and volatile helpers into an internal partition used only by implementation units, keeps the rebuild set small. ## Header units sit in the same graph A header unit, `import "config.h";`, is also a separate translation unit with its own BMI, so it too must be built before any unit that imports it. It is the one import that carries macros, which makes it tempting for configuration headers, but Clang's documentation still labels header-unit support experimental, so most partitioned modules keep legacy headers in a global module fragment instead. ## Interview angle The question tests whether the candidate knows the two kinds of partition, the "must be re-exported, no diagnostic required" trap, and that modules trade the header model's free parallelism for a dependency-ordered build. A strong answer adds that a partition split is a build-graph design decision as much as a code-organisation one.

  • What goes wrong if the primary interface forgets export import :vec;?
    The program is ill-formed, but the standard requires no diagnostic, so a compiler may build it anyway. Importers of `mathlib` then cannot see `Vec2` or `dot`, and the error appears far from the cause, in a consumer that expected the type. Checking that every `export module mathlib:...;` file is re-exported belongs in code review or a script.
  • Why can a module change trigger more recompilation than people expect?
    Every importer depends on the imported BMI, so any change to an interface unit or interface partition makes all of them stale, and a long import chain also serialises the rebuild. Keeping volatile code in implementation units, which produce no BMI, limits the blast radius.
  • Can two partitions of the same module import each other?
    No. Any import cycle gives a unit an interface dependency on itself, which the standard forbids, and no build order exists in which both BMIs could be produced first. Move the shared declarations into a third partition that both import.

  • Interface partitions are exported automatically without export import.
  • Consumers can import mathlib:vec directly to save build time.
  • An internal partition is the same thing as an implementation unit.
  • Module units can still all compile in parallel like headers.
  • Two modules may import each other as long as only declarations are shared.
  • Changing an implementation unit forces every importer to rebuild.

Assumes C++20, which introduced module partitions; the partition and cycle rules read the same in the C++23 draft N4950 and the C++26 draft N5050.