skip to content

Your team's C++ math library has many #include consumers; how do you decide whether and how to also ship it as a C++20 named module?

level: principalimportance: should knowfreq 30%

answer

  1. every consumer's toolchain, not yours
  2. ship sources, not BMIs
  3. wrap the headers first
  4. attachment changes mangled names
  5. public macros need a new home

basics

~20 s

Adopt when every supported compiler and build system handles named modules; then ship a wrapper interface unit over the existing headers, export-using or extern "C++" style, so header and module users coexist and the symbol names stay unchanged.

solid answer

~40 s

It is a support-matrix decision before it is a code one. Every consumer's compiler, standard library and build system must handle C++20 named modules, and BMIs are specific to a compiler and its dialect flags, so you ship `.cppm` sources rather than BMIs. If that holds, start with a **wrapper**: an interface unit whose global module fragment includes the existing headers and whose purview does `export using mathlib::...;` (or includes them inside `extern "C++"` with an `EXPORT` macro). The declarations stay attached to the global module, so their mangled names do not change and header users and module users can link into one program. Public macros must become `constexpr` values or stay in a small header. Measure build time at the optimisation levels you actually ship before moving code into the module purview.

code

cpp · 26 lines
cpp
// mathlib.h - unchanged header, still the source of truth
#pragma once
namespace mathlib {
  double circle_area(double r);
  struct Vec2 { double x, y; };
  inline double dot(Vec2 a, Vec2 b) { return a.x * b.x + a.y * b.y; }
}

// mathlib.cppm - wrapper interface unit
module;
#include "mathlib.h"
export module mathlib;
export namespace mathlib {
  using mathlib::circle_area;
  using mathlib::Vec2;
  using mathlib::dot;
}

// new_consumer.cpp imports; old_consumer.cpp includes; both link into one program
#include <cstdio>
import mathlib;
double old_area();   // defined in old_consumer.cpp, which does #include "mathlib.h"
int main() {
  std::printf("%.2f %.2f %.1f\n", old_area(), mathlib::circle_area(2.0),
              mathlib::dot({1, 2}, {3, 4}));
}

go deeper

for a junior

Know that a library can offer both a header and a module, and that modules need compiler and build-system support everyone must have.

for a middle

Explain the wrapper interface unit, why macros in the public API need replacing, and why BMIs are not shipped.

for a senior

Know which wrapper styles keep the mangled names stable and prove header and module consumers can share one program in CI.

for a principal

Own the support matrix and the rollout: the minimum toolchains, when a move into the module purview justifies a major version, and how you measure the build-time benefit.

## The decision is about consumers A header-based library works for every consumer with a C++ compiler. A module-only library works only for consumers whose **whole toolchain** supports C++20 named modules: the compiler, the standard library (for `import std;`), the build system's dependency scanning, and tools that parse code such as IDE indexers and static analysers. Before any code changes, a lead needs answers to: 1. **Which compilers and versions must we support?** Support arrived feature by feature; header units are still marked experimental in Clang's documentation, and libc++ calls its `std` module experimental. 2. **Which build systems do consumers use?** A module build needs scanning and ordered compilation; a consumer whose build cannot do that cannot import you. 3. **How do we distribute?** A **BMI** depends on the compiler and on dialect options – Clang rejects a BMI built with `-std=c++20` when the importer uses `-std=c++23`. So libraries ship the interface source and each consumer's build compiles it. Clang also notes that a BMI is not an information-hiding mechanism. 4. **What does it buy?** Clang's documentation warns that the speedup at `-O0` shrinks at higher optimisation levels, because imported function bodies are still fed to the optimiser in each importer. Measure the real build. ## Three adoption shapes | Shape | What changes | Header users | Symbol names | |---|---|---|---| | Stay header-only | Nothing | Unaffected | Unchanged | | Wrapper module over headers | A new interface unit | Unaffected, can mix with importers | Unchanged | | Code moved into the module purview | Declarations attached to `mathlib` | Need a header kept in step, or lose access | Changed | **Export-using wrapper.** The interface unit includes the real headers in its global module fragment and re-exports names: ```cpp module; #include "mathlib.h" export module mathlib; export namespace mathlib { using mathlib::circle_area; using mathlib::Vec2; } ``` The declarations stay attached to the **global module**, so `mathlib::circle_area` keeps its existing mangled name and a program in which one file includes the header and another imports the module links against one definition. **extern "C++" wrapper.** Clang documents a second style: include the headers inside `extern "C++" { ... }` after the module declaration, with an `EXPORT` macro that expands to `export` only when a macro like `IN_MODULE_INTERFACE` is defined. Declarations with language linkage are attached to the global module, so the ABI is again unchanged, and it is easier to evolve towards a true module later. **Moving code into the purview** attaches declarations to the module. Under the Itanium C++ ABI that changes their names: Clang mangles `NS::foo()` exported from module `M` as `_ZN2NSW1M3fooEv` rather than `_ZN2NS3fooEv`, so already-compiled consumers stop linking, and a declaration in a module unit can no longer be defined in a non-module file. That is a major-version event. ## Macros in the public API Importers never see macros from a named module. List every macro consumers rely on: - Constants and feature switches become `constexpr` variables or `inline constexpr` values. - Function-like helpers become `constexpr` or templated functions. - Configuration that must be set **by the consumer before inclusion** cannot work through a module, because the module is compiled before the consumer exists; it needs a build-time option or a small header that consumers keep including. ## A rollout plan 1. Add the wrapper interface unit next to the headers; keep the headers as the single source of truth. 2. Build it in CI with every supported compiler, plus one consumer that includes and one that imports, in the same program. 3. Publish the interface source and document the minimum compiler and build-system versions. 4. Replace each public macro with a `constexpr` value or function, and list any that must stay in a small companion header. 5. Revisit moving code into the module purview only when no supported consumer still needs the headers, and treat that move as an ABI break. ## What makes it a principal question No answer is right for every library. A game engine whose studio controls one compiler can go module-first; a widely distributed math library cannot drop header users without stranding them. The judgement is weighing faster, cleaner builds for some consumers against support cost and fragmentation for all of them, and deciding which signal – compiler versions in the field, consumer build systems, measured build time – would move the library to the next stage.

  • Why not ship prebuilt BMIs with the library, as you ship headers?
    A BMI is tied to the compiler and its dialect options; Clang rejects one built with a different `-std`, and other compilers use their own formats. Consumers must compile the interface source themselves, so you ship `.cppm` files and document the toolchain they need.
  • When is moving code into the module purview worth the ABI break?
    When no supported consumer still needs the headers and you are cutting a major version anyway. It brings real module linkage for internals and no global-module baggage, but every compiled consumer must rebuild, because attached declarations get module-qualified mangled names.

  • Modules always make builds faster, so adopt them everywhere.
  • Ship the .pcm files so consumers do not need to compile anything.
  • Converting headers to modules never changes symbol names.
  • Consumers can keep configuring the library with #define before import.
  • If our own compiler supports modules, our consumers are covered.

Assumes C++20 named modules and C++23 import std; Clang facts are from the LLVM 23.1.4 documentation and Apple clang 21 runs, and toolchain support keeps changing release to release.