C compilation — preprocessor, compiler, assembler, linker: Worked examples

Intuition What this page is

The parent note told you the four stages of turning hello.c into a program: Preprocessor → Compiler → Assembler → Linker. This page makes you use that knowledge on every case you can hit in real life — every kind of error, every stopping point, every degenerate input. By the end, no compilation scenario should surprise you.

A quick vocabulary refresher so we never use a word before it's clear:

stage ::: one of the four tools in the pipeline.
symbol ::: a name for a function or global variable (e.g. main, printf). Think of it as a label on a box of code.
defined symbol ::: a symbol whose actual code/data lives right here in this file — the box has stuff in it.
undefined symbol ::: a symbol used here but whose code lives elsewhere — an empty box waiting to be filled.
translation unit ::: the single stream of C text the compiler actually digests — one .c file after the preprocessor has pasted in all its headers and expanded all its macros. One .c in, one translation unit out.
relocation ::: the linker's act of filling the empty address holes left by earlier stages. Each call printf was left blank; once the linker decides where printf sits in memory, it patches that final address into every hole. "Re-location" = writing in the real location.

The whole page hangs on one picture — which stage owns what. Here is what the figure below shows, in words, so you can follow it even without the image: across the top are the five files of the pipeline as labelled boxes, in order — .c, .i, .s, .o, exe — joined left-to-right by white arrows. Between each pair of files sits the coloured stage box that does that transformation: blue cpp (Preprocessor) turns .c into .i, yellow cc1 (Compiler) turns .i into .s, green as (Assembler) turns .s into .o, red ld (Linker) turns .o into exe. Dashed coloured vertical lines drop from each joint showing the stop-early flag that "snips" the pipeline there (-E, -S, -c, and none for the full build). Under each stage box is a short label naming the kind of error that stage owns ("missing paste", "grammar & types", "bad mnemonic", "empty/doubled box"). The italic caption spells the file trail I S O exe.

Figure — C compilation — preprocessor, compiler, assembler, linker

The scenario matrix

Every problem about C compilation is really the question: "At which stage does something happen (or break)?" Here is the full grid of case classes. Each cell is covered by a worked example below.

#	Case class	What triggers it	Which stage owns it
A	Clean full build	valid, self-contained program	all 4 run, no error
B	Macro text-substitution trap	`#define` used naively	Preprocessor
C	Conditional compilation	`#ifdef` toggles code	Preprocessor
K	Missing header file	`#include` target not found	Preprocessor
D	Syntax / type error	bad C grammar or types	Compiler
L	Malformed assembly	broken `.s` fed to `as`	Assembler
E	Undefined reference	symbol used, never defined	Linker
F	Duplicate definition	same symbol defined twice	Linker
G	Missing library flag	library function used, `-l` absent	Linker
H	Degenerate input: empty file	`.c` with nothing runnable	Compiler/Linker boundary
I	Stop-early flags	`-E`, `-S`, `-c`	pick your exit stage
J	Real-world multi-file build	split project + separate compile	Compiler then Linker

We now walk them one at a time. Signs of trouble = the stage that complains. That mapping is the whole skill.

Case A — the clean full build

Worked example Statement (cell A)

#include <stdio.h>
int main(void){ printf("hi\n"); return 0; }

You run gcc hello.c -o hello. Trace what each stage does and predict the exit status of the program.

Forecast: Before reading on — does this compile and link and run? What number does main hand back to the operating system?

Step 1 — Preprocessor. What: #include <stdio.h> is replaced by the entire text of stdio.h, which contains the declaration int printf(const char*, ...);. The result — one .c plus all pasted headers — is the translation unit the compiler will read. Why this step? The compiler needs to know printf's shape (return type, argument types) to type-check the call — the header is that promise.

Step 2 — Compiler. What: real C → assembly. The call becomes a call printf instruction, but the address of printf is left blank — a hole marked "fill me later". Why: the compiler doesn't know where printf will live in memory; that's not its job.

Step 3 — Assembler. What: assembly → object file hello.o with a symbol table: main = defined, printf = undefined. Why: raw bytes are what the CPU eats, and the table records which boxes are still empty.

Step 4 — Linker. What: finds printf inside the C library (libc, linked automatically), fills the hole (this hole-filling is relocation — patching the real address into every blank), and adds startup code that calls main. Why: one runnable file needs every box filled.

Verify: main executes return 0;, so the exit status is 0 (success). Run ./hello; echo $? → prints hi then 0.

Case B — the macro substitution trap

Worked example Statement (cell B)

#define SQUARE(x) x*x
int main(void){ return SQUARE(3+1); }

Note: no parentheses around x. What integer does the program return?

Forecast: Guess the "intended" value first (four squared), then guess what the dumb text engine actually produces.

Step 1 — Preprocessor expands the macro as pure text. What: every SQUARE(x) → x*x, and x → the literal text 3+1. So SQUARE(3+1) becomes the characters 3+1*3+1. Why this step? The preprocessor has no idea about arithmetic or types — it only swaps tokens. This is the single most important fact in the chapter.

Step 2 — Compiler now sees ordinary C. What: it evaluates 3+1*3+1 using normal precedence: * before +, so it is 3 + (1*3) + 1. Why: by the time the compiler runs, the macro is long gone — it only sees the expanded text.

Step 3 — Arithmetic. 3 + 3 + 1 = 7. Not 16.

Verify: 3+1*3+1 = 3+3+1 = 7. The fix is #define SQUARE(x) ((x)*(x)), which expands to ((3+1)*(3+1)) = 16. Both values are checked below.

Case C — conditional compilation

Worked example Statement (cell C)

int main(void){
#ifdef DEBUG
    return 42;
#else
    return 7;
#endif
}

You compile once with gcc case.c and once with gcc -DDEBUG case.c. What does each return?

Forecast: Which return survives in each build?

Step 1 — Preprocessor checks whether DEBUG is defined. What: -DDEBUG on the command line is exactly like writing #define DEBUG at the top. Why this step? #ifdef is a compile-time switch resolved by the preprocessor — the branch it rejects is deleted from the text entirely before the compiler ever sees it.

Step 2 — Two different source texts result.

Without -DDEBUG: the compiler sees only return 7;.
With -DDEBUG: the compiler sees only return 42;.

Why: this is how you ship one source file but produce a debug build and a release build — nothing is decided at runtime.

Verify: plain build returns 7; -DDEBUG build returns 42. Both checked below.

Case K — missing header file (preprocessor error)

Worked example Statement (cell K)

#include "helpers.h"     // this file does not exist
int main(void){ return 0; }

There is no helpers.h on disk. main itself is perfectly valid. Where does the build stop?

Forecast: main is flawless — so surely it compiles? Guess which stage even gets a chance to run.

Step 1 — Preprocessor tries to paste the header and fails immediately. What: #include "helpers.h" is a command to find that file and paste its text here. The preprocessor searches the current directory and include paths, finds nothing, and stops with fatal error: helpers.h: No such file or directory. Why this step? Pasting headers is the preprocessor's first job; it cannot produce a translation unit with a piece missing, so it aborts before the compiler ever runs.

Step 2 — Nothing downstream executes. What: because there is no completed translation unit, the compiler, assembler, and linker never even start. Why: the pipeline is strictly ordered — a fatal error at stage 1 halts everything.

Verify (structural): the message is a preprocessor fatal error about a missing file, and the perfectly-valid main is never reached. Owner = preprocessor. Checked below.

Case D — a compiler-stage error

Worked example Statement (cell D)

int main(void){ int x = "hello"; return x }

Two problems live here. Which stage reports them, and what are they?

Forecast: Is this a preprocessor, compiler, or linker complaint?

Step 1 — Preprocessor. What: no # directives → passes through untouched, producing a valid translation unit. Why: nothing for it to do; it never checks meaning.

Step 2 — Compiler catches BOTH issues. What:

int x = "hello"; — a string literal has type "pointer to char", not int. Type mismatch.
return x — missing semicolon ;. Syntax error.

Why this step? The compiler is the only stage that understands grammar and types. These never reach the assembler or linker — the build stops here.

Verify (conceptual): the error message names the compiler (error:), not undefined reference. Different diagnostic text ⇒ different owning stage. This is the diagnostic-reading skill, checked structurally below.

Case L — malformed assembly (assembler error)

Worked example Statement (cell L)

You hand-write a .s file (or a compiler bug emits one) containing a typo'd mnemonic:

.globl main
main:
    movqq $0, %rax      # "movqq" is not a real instruction
    ret

You run gcc bad.s -o app. Which stage rejects it?

Forecast: The compiler is skipped entirely here (input is already assembly). So who checks the mnemonics?

Step 1 — Preprocessor and compiler are bypassed. What: a .s file is already assembly, so gcc sends it straight to the assembler as. Why: there is no C text to expand or translate — those stages have nothing to do.

Step 2 — Assembler rejects the bad mnemonic. What: as reads each line and looks up its opcode in the instruction table. movqq is not a real instruction, so it reports Error: no such instruction: 'movqq $0,%rax' and produces no object file. Why this step? Encoding mnemonics into machine-code bytes is the assembler's sole job; an unknown mnemonic has no byte pattern to emit.

Step 3 — Linker never runs. What: with no .o produced, there is nothing to link. Why: the halted pipeline again — a stage-3 failure stops stage 4.

Verify (structural): the diagnostic is an assembler Error: no such instruction, distinct from a compiler error: and from a linker undefined reference. Owner = assembler. Checked below.

Case E — undefined reference (linker)

Worked example Statement (cell E)

void foo(void);            // declared: "foo exists somewhere"
int main(void){ foo(); return 0; }

There is no definition of foo anywhere. Where does this break?

Forecast: The compiler believed the declaration. So who catches the lie?

Step 1 — Compiler is satisfied. What: the prototype void foo(void); is a promise that foo will exist; the compiler type-checks the call foo() against it and emits a call foo with an empty address. Why: declarations exist precisely so the compiler can compile a call before seeing the definition.

Step 2 — Assembler. What: object file records foo = undefined in the symbol table. Why: the box is still empty.

Step 3 — Linker fails. What: it searches all object files and libraries for a defined foo, finds none, and reports undefined reference to 'foo'. Why this step? Resolving symbols is the linker's sole job; an unfillable box is fatal here.

Verify (structural): the failure text contains undefined reference and the exit is non-zero, marking the linker as owner. Checked below.

Case F — duplicate definition (linker)

Worked example Statement (cell F)

Two files each define the same global:

// a.c
int counter = 0;
// b.c
int counter = 5;

You run gcc a.c b.c -o app. What happens?

Forecast: Case E was an empty box. This is two full boxes with the same label. Which stage objects?

Step 1 — Each file compiles cleanly on its own. What: gcc -c a.c and gcc -c b.c both succeed; each object file has counter = defined. Why: a single file sees no conflict — the other file doesn't exist to it yet.

Step 2 — Linker sees the collision. What: two objects both claim to define counter. The linker cannot pick a memory slot for a symbol defined twice → multiple definition of 'counter'. Why this step? Merging symbol tables is the linker's job; a duplicate strong definition is a contradiction.

Verify (structural): error text says multiple definition, owner = linker. The fix: define once, and use extern int counter; in the other file (a declaration, an empty box the linker fills from the one definition).

Case G — missing library flag (linker)

Worked example Statement (cell G)

#include <math.h>
int main(void){ return (int)sqrt(16.0); }

On many systems gcc case.c fails, but gcc case.c -lm succeeds. Why — and what does it return when it works?

Forecast: math.h was included, so why isn't sqrt found?

Step 1 — Header ≠ code. What: #include <math.h> supplies only the declaration of sqrt. The compiler is happy. Why: headers are promises, not deliveries (see the parent note's steel-manned mistake).

Step 2 — Linker needs the actual sqrt code. What: the compiled sqrt lives in the math library libm, which — unlike libc — is not linked automatically. -lm says "also search libm". Why this step? Without it, sqrt stays an undefined symbol and the linker reports undefined reference to 'sqrt' — a linker error, not a compiler one.

Step 3 — When linked correctly, evaluate the arithmetic. What: the square root of 16.0 is 4.0; the cast (int) truncates it to 4, which becomes the exit status. Why: only after -lm fills the sqrt box does the program run to compute a value.

Verify: (int)sqrt(16.0) = 4. Without -lm the failure text is a linker undefined reference to 'sqrt'; with -lm the program's exit status is 4. Both facts checked below.

Case H — degenerate input: the near-empty file

Worked example Statement (cell H)

A file empty.c contains only a comment:

/* nothing here */

Trace gcc -c empty.c versus gcc empty.c -o app.

Forecast: Does anything go wrong, and if so, at which stage?

Step 1 — Preprocessor strips the comment. What: the resulting translation unit is empty. Why: comments never survive preprocessing.

Step 2 — Compiler + Assembler. What: an empty translation unit is legal C. gcc -c empty.c happily produces an empty.o that defines no symbols. Why: nothing to translate is not an error — just an empty object file.

Step 3 — Linker (full build only). What: linking needs an entry point main. There is none → undefined reference to 'main'. Why this step? The startup code always calls main; with main undefined, the box the linker must fill is empty.

Verify (structural): -c succeeds (exit 0), full build fails with undefined reference to 'main', owner = linker. This is Case E in disguise — the missing symbol is main itself. Checked below.

Case I — stop-early flags (choose your exit stage)

Step 1 — Map flags to exits. What:

flag	stops after	file produced
`-E`	Preprocessor	`.i` (expanded C on stdout)
`-S`	Compiler	`.s` (assembly)
`-c`	Assembler	`.o` (object, not runnable)
(none)	Linker	executable

Why this step? Each flag is a valve cutting the pipeline at one joint — invaluable for debugging which stage misbehaves. This is exactly the picture at the top of the page: each dashed "scissors" line is one of these flags snipping the pipeline after its stage.

Step 2 — Sanity mnemonic. The file trail spells I S O exe — "I Saw Our executable" (from the parent's mnemonic). The flag that stops at .o is -c, and .o is the last non-runnable file.

Verify (structural): the four flags map to {i, s, o, exe} in pipeline order. Checked below.

Case J — the real-world multi-file build

Worked example Statement (cell J)

A project split across two files:

// mathutil.c
int add(int a, int b){ return a + b; }
// main.c
int add(int, int);
int main(void){ return add(20, 22); }

You build it in two steps: gcc -c mathutil.c, gcc -c main.c, then gcc mathutil.o main.o -o app. What does app return, and why is this how big projects build?

Forecast: Which object file has the "empty box" and which has the "full box"?

Step 1 — Compile each .o independently. What:

main.o: main defined, add undefined (empty box).
mathutil.o: add defined (full box).

Why this step? Separate compilation means editing main.c later only needs main.c recompiled — the incremental build idea, and why make is fast.

Step 2 — Linker matches empty box to full box. What: add undefined in main.o is resolved to add defined in mathutil.o. Relocation patches the call address. Why: symbol resolution across objects is exactly the linker's purpose.

Step 3 — Runtime. main returns add(20, 22).

Verify: 20 + 22 = 42; exit status 42. Checked below.

Recall

Recall Which stage owns each error message?

fatal error: helpers.h: No such file or directory ::: Preprocessor (can't paste a missing header) error: expected ';' ::: Compiler (syntax) Error: no such instruction: 'movqq' ::: Assembler (unknown mnemonic, no byte pattern) undefined reference to 'foo' ::: Linker (empty box, no definition) multiple definition of 'counter' ::: Linker (two full boxes, same label) undefined reference to 'sqrt' after including math.h ::: Linker — missing -lm library flag undefined reference to 'main' from an empty file ::: Linker — no entry point defined

See also: Object Files and Symbol Tables, Static vs Dynamic Linking, C Preprocessor Directives, Assembly Language Basics, Compiler Optimization Levels (-O0..-O3).