The Preprocessor

The preprocessor is a macro language layered over C++ that shares only the tokenizer. #include copies a file in. #define establishes a substitution. #if and #ifdef delete regions. None of these operations knows what a type is, what a scope is, or whether the result will parse.

That is what makes it so effective for the job it was built for — a mechanism to share declarations that needs no cooperation from the compiler, the build system or the language — and it is what makes every one of its failure modes the same failure mode wearing different clothes. Each hazard below is "the substitution was textual and I reasoned about it as though it were semantic".

The preprocessed output is a real artifact you can read. g++ -E prints it, and doing so once for a header-heavy file changes how most engineers think about C++ builds.

A function-like macro is not a function. Its arguments are token sequences, substituted as written, and the result is re-parsed in whatever context it landed in. Two consequences follow immediately, and both bite constantly.

First, precedence. #define SQUARE(x) x * x expands SQUARE(a + b) to a + b * a + b, which is not the square of anything. Parenthesising the parameters and the whole replacement list fixes this specific case and is the reason macro definitions are full of parentheses.

Second, evaluation. Arguments are substituted, not evaluated, so a macro that mentions a parameter twice evaluates its argument twice. MAX(i++, j) increments i once or twice depending on which branch wins. No amount of parenthesising fixes that, because the problem is not precedence but that the macro is not a function call.

Third — the one that gives "hygiene" its name — a macro that declares a temporary can capture a name from the call site. If the macro uses tmp and the caller passes an expression mentioning their own tmp, the two collide silently. Scheme's syntax-rules and Rust's macro_rules! are hygienic precisely because they rename such bindings automatically; the C preprocessor cannot, because it does not know that tmp is a binding.

Because inclusion is textual and macros persist for the rest of the translation unit, a header can change the meaning of every header included after it. A macro named min, max, ERROR or interface defined by one header silently rewrites identifiers in the next one. The Windows headers' min/max macros breaking std::min is the canonical example, and NOMINMAX exists as an entire configuration flag to work around it.

This is why "include what you use", "headers must be self-contained" and "include your own header first in the corresponding .cpp" are standard rules. A header that only compiles when something else was included before it is a landmine: it works everywhere it is currently used and breaks the first time someone reorders an include list or writes a new file.

It is also why macro leakage is a real design concern for library authors. A macro is not namespaced, not scoped and not overridable; defining one in a public header means claiming that identifier in every translation unit of every consumer, forever. Prefixing macro names with a library-specific tag is the only available mitigation, and #undef at the end of a header is the only way to unclaim one.

The #ifdef family selects which code exists in this translation unit. It is how one source tree targets several platforms, several compilers, several feature sets and several build types. It is also the mechanism by which a project acquires a combinatorial number of programs that share a name.

Code inside a false branch is not compiled, so it is not parsed for anything beyond matching #if/#endif nesting, not type-checked, and not covered by any test. A configuration nobody builds is a configuration that has already rotted. With n independent boolean flags there are 2^n translation units and a CI matrix that samples a handful, so the failure mode is a build that has been broken for months for a platform nobody compiles nightly.

The preferred modern alternative is to make the branch a *language-level* condition wherever possible — if constexpr, a trait, a template specialisation — because those are type-checked even when not taken. That converts a text problem into a semantic one, which is the general direction the whole language has been moving in for twenty years.

There is no artifact representing "the compiled form of a header". #include names a file and the preprocessor pastes its text; the compiler then parses that text as part of this translation unit, and again as part of the next one. A project with two hundred .cpp files that all include the same five-thousand-line header parses a million lines of it.

Precompiled headers are the traditional mitigation: parse one designated header set once, serialise the compiler's internal state, and reload it per unit. They work, and they are fragile in exactly the way you would expect — the serialised state is compiler-, version- and flag-specific, and a mismatch is a rebuild at best.

C++20 modules remove the mechanism rather than optimizing it. A module interface is compiled once into a binary artifact; importing it reads that artifact instead of re-parsing text, and macros defined inside the module do not leak to importers. That last property is the one that matters most for this lesson: it converts inclusion from a textual operation into a semantic one, which retires include-order dependence and macro leakage together. See [[modules]] and [[interface-files]].