Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 61 ยท Getting Started

The Preprocessor and Macro Expansion

Learn how a preprocessor works: includes, conditional compilation, object-like and function-like macros, stringizing, pasting, macro pitfalls and hygiene, with a runnable model.

Before a C or C++ compiler looks at your program, another program has already rewritten it. The preprocessor pastes in header files, deletes the parts that are switched off with #ifdef, and replaces every use of a macro with its definition. All of this happens on text (more exactly, on a stream of tokens), before parsing starts, so the compiler proper never sees a #define at all. That is why macros are both powerful and dangerous: they can do things no function can, and they do not understand the language they are rewriting.

This lesson explains what the preprocessor does, builds a small one you can run, and shows the classic macro traps. The ideas also apply well beyond C: assemblers have macros, so do Rust (macro_rules!) and Lisp, and template engines and code generators expand text in the same spirit. If you recall the compiler phases, the preprocessor sits in front of the lexer as a pre-pass.

What the preprocessor does

There are three jobs, each with its own directives:

Job Directives Effect
File inclusion #include "a.h" Replaces the line with the contents of the file
Conditional compilation #if, #ifdef, #ifndef, #else, #endif Keeps or discards lines
Macro definition and expansion #define, #undef Defines names whose uses are replaced
flowchart LR
    SRC["Source file and headers"] --> INC["Include files"]
    INC --> COND["Evaluate conditionals"]
    COND --> MAC["Expand macros"]
    MAC --> OUT["Expanded source"]
    OUT --> LEX["Lexer and the rest of the compiler"]

The expanded text is what the compiler really compiles. GCC and Clang show it with the -E option.

Inclusion is plain copying, so a header that is included twice is declared twice, which usually breaks the program (a type cannot be defined twice). The standard remedy is an include guard: wrap the header in #ifndef NAME_H / #define NAME_H / #endif. The first inclusion defines NAME_H, and later inclusions skip the body.

Conditional compilation selects code by configuration: platform-specific code, debug logging, optional features. In #if, the preprocessor can evaluate integer expressions and the operator defined(X). Names that are not defined count as 0.

Object-like and function-like macros

An object-like macro is a name replaced by a token sequence:

C
#define VERSION 3
#define BUFFER_SIZE (4 * 1024)

A function-like macro has parameters and is expanded only when the name is followed by (:

C
#define MAX(a, b) ((a) > (b) ? (a) : (b))

Expansion proceeds like this. The preprocessor reads the arguments (counting parentheses, so that commas inside nested parentheses do not split arguments), expands the macros inside each argument, substitutes the results for the parameters in the body, and then rescans the result for more macros. To stop endless recursion, a macro's own name is never expanded again while its replacement is being rescanned: #define LOOP LOOP + 1 expands to LOOP + 1, not forever.

Two special operators work on the parameters:

  • Stringizing #x turns the argument's text into a string literal. STR(hello world) becomes "hello world". The argument is not macro-expanded first.
  • Token pasting a ## b glues two tokens into one. CAT(value, 42) becomes the single identifier value42. This is how code generators create families of names.

A preprocessor you can run

The program below implements everything described so far in about 150 lines: include files from an in-memory file system, include guards, #ifdef, #ifndef, #if with defined, #else, object-like and function-like macros, # and ##, and the recursion guard. The test file contains the classic macro pitfalls.

Python A miniature C preprocessor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the output line by line:

  • int v = VERSION; becomes int v = 3;, and config.h was included twice without trouble, because the guard CONFIG_H was defined by the first inclusion.
  • SQUARE(1 + 2) becomes 1 + 2 * 1 + 2, which is 5, not 9. Always parenthesize each parameter and the whole body, as SAFE_SQUARE does.
  • MAX(i++, j) expands to ((i++) > (j) ? (i++) : (j)). The argument i++ appears twice, so i can be incremented twice. A function would evaluate its argument once. This double evaluation is the second classic trap, and it cannot be fixed with parentheses.
  • STR(hello world) is the string "hello world", and CAT(value, 42) is the identifier value42.
  • SWAP(tmp, y) becomes { int tmp = tmp; tmp = y; y = tmp; }. The macro's own temporary variable has the same name as the caller's variable, so the caller's tmp is captured: int tmp = tmp declares a new variable and initializes it with itself. SWAP2 uses an unlikely name for its temporary, which avoids the problem in practice but not in theory.
  • LOOP expands to LOOP + 1, once. The recursion guard stopped it.
  • The #ifdef and #if blocks keep exactly the branches that match.

Macro hygiene

The SWAP bug has a name: variable capture. The macro writer's identifier (tmp) and the user's identifier (tmp) clash because the preprocessor works on plain text and has no idea that two identifiers with the same spelling should mean different variables.

A macro system is called hygienic when it prevents this automatically. In the usual design, every identifier that the macro itself introduces gets a fresh, unique name for each expansion, and identifiers that come from the user's arguments keep their meaning. Scheme and Rust (macro_rules!) are hygienic: a tmp created inside the macro can never be confused with a tmp from the caller. The C preprocessor is not, so C programmers use conventions: long, ugly names for temporaries (swap_tmp_1), do { ... } while (0) to make a macro usable like a single statement, and GNU extensions such as __typeof__ and statement expressions for safe versions of MAX.

When to use a macro, and when not

Prefer a function, an inline function or a constexpr / const value in modern C and C++, because they respect scopes and types, evaluate arguments once, can be debugged, and show real names in error messages. Reach for the preprocessor for the things only it can do:

  • Include guards and conditional compilation, for platform and feature selection.
  • Source information, such as __FILE__, __LINE__ and assert.
  • Generating repetitive code with ##, for example creating a family of similarly named functions or a table of names and values (the X-macro technique).
  • Stringizing an identifier, for example to print the name of a variable or enum constant.

A note on other languages

Many languages avoid the textual approach. Java and Python have no preprocessor at all and use constants, functions and annotations. Rust's macro_rules! works on token trees and is hygienic, and its procedural macros transform syntax trees. Lisp macros are functions from syntax to syntax. C++ templates and constexpr replace many macro uses, and modern languages with compile-time evaluation (Zig, D, C++) let ordinary code run during compilation instead of using a separate macro language.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Given #define SQUARE(x) x * x, what does SQUARE(1 + 2) expand to, and what is its value?

    The preprocessor substitutes text. The multiplication binds tighter than the additions, giving 1 + 2 + 2 = 5. Parenthesizing the parameter and the body fixes it.
  2. 2. What problem does an include guard solve?

    The first inclusion defines a guard macro. Later inclusions find it defined and skip the body.
  3. 3. What does #define CAT(a, b) a ## b do with CAT(value, 42)?

    The ## operator pastes two tokens into one token, which here is an identifier.
  4. 4. Why is MAX(i++, j) dangerous when MAX is a macro?

    A macro substitutes the argument text wherever the parameter appears. If the body uses a parameter twice, any side effect happens twice.
  5. 5. What does it mean for a macro system to be hygienic?

    Hygienic expansion renames the macro's own bindings so that name clashes like the SWAP/tmp example cannot occur.

Summary

  • The preprocessor runs before the compiler proper. It includes files, evaluates conditionals and expands macros, all by rewriting tokens.
  • Include guards stop repeated declarations. #if, #ifdef and #ifndef select code by configuration.
  • Function-like macros collect arguments, expand them, substitute them into the body and rescan the result. A macro's own name is not expanded again inside its expansion.
  • #x makes a string from an argument and a ## b pastes tokens into one.
  • Textual substitution causes precedence bugs, double evaluation and variable capture. Parenthesize everything, avoid side effects in arguments and prefer functions and constants.
  • Hygienic macro systems (Scheme, Rust) rename macro-introduced identifiers to avoid capture.

Next, meet the language we will compile in Our Toy Language.