Basics Master - Part 0

The C Compilation Model

This section will provide you a way to figure out what actually is happening when you use gcc or clang to compile a C source code into a fully functional executable binary file. It undergoes 4 stages before getting into executable. Here is a deep dive on each of them.

#c #introduction

The C Compilation Model: A Deep Dive

Understanding how C code transforms from human-readable text into a running program is one of the most illuminating things you can learn as a systems programmer. It demystifies errors that otherwise feel like black magic, and it gives you genuine control over your tools. Let’s walk through each stage carefully.

The Big Picture: Why Multiple Stages?

Before diving in, it’s worth asking: why does this pipeline exist at all? Why not just translate C directly into machine code in one shot?

The answer is separation of concerns. Each stage solves a distinct, well-scoped problem. The preprocessor handles text substitution. The compiler handles language semantics. The assembler handles instruction encoding. The linker handles combining pieces. Each stage has a clean input and output, which also makes the toolchain composable — you can swap out the assembler, or use a different linker, without redesigning everything.

Now, let’s follow a simple file through the whole journey.

// hello.c
#include <stdio.h>
#define GREETING "Hello, world"

int main(void) {
    printf("%s\n", GREETING);
    return 0;
}

Stage 1: The Preprocessor

The preprocessor is, conceptually, the simplest stage — it is purely a text manipulation engine. It knows nothing about C syntax, types, or semantics. It just reads your source file and produces a new, larger, modified text file.

You can see its output directly by running:

gcc -E hello.c -o hello.i

The .i extension is conventional for preprocessed C.

What the preprocessor actually does

#include directives are literally a copy-paste operation. When the preprocessor sees #include <stdio.h>, it finds that header file on your system (usually somewhere like /usr/include/stdio.h), reads its entire contents, and splices them in place of the #include line. That’s it. There’s no magic — stdio.h is just a text file full of function declarations, and the preprocessor physically inserts it into your source.

This is why including a single standard header can balloon your translation unit from a few lines to thousands. If you run wc -l hello.i after preprocessing, you’ll often see 700–1000 lines for what started as 7.

#define macros are text substitution rules. #define GREETING "Hello, world" tells the preprocessor: “wherever you see the token GREETING, replace it with the token sequence "Hello, world".” This happens before the compiler ever sees your code. The compiler will only ever see the substituted result.

This is the root of a classic C pitfall. Consider:

#define SQUARE(x) x * x   // dangerous!

int result = SQUARE(1 + 2); 
// Expands to: 1 + 2 * 1 + 2  →  5, not 9!

// Safe version uses parentheses:
#define SQUARE(x) ((x) * (x))

Because macros are textual, not semantic, they don’t respect operator precedence unless you parenthesize defensively. The compiler never sees SQUARE — it sees the expanded result.

Conditional compilation (#ifdef, #ifndef, #if) lets you include or exclude blocks of code based on defined symbols. This is how cross-platform code works:

#ifdef _WIN32
    // Windows-specific code
#else
    // POSIX code
#endif

The preprocessor strips out the inactive branch entirely. The compiler only ever sees one path.

Line markers are another thing the preprocessor adds — special comments that tell the compiler “this code originally came from line 47 of stdio.h.” This is how error messages can point back to your original source file even after all that copy-pasting.

Stage 2: The Compiler

This is the intellectual heart of the pipeline. The compiler takes the preprocessed text (.i file) and transforms it into assembly language (.s file). You can inspect this output with:

gcc -S hello.c -o hello.s

This stage is itself a multi-phase process internally, and understanding those phases explains a lot.

Lexing and Parsing

First, the compiler lexes the source — breaking the character stream into tokens (int, main, (, void, ), etc.). Then it parses those tokens according to C’s grammar, building an Abstract Syntax Tree (AST), which is a tree representation of your program’s structure.

At this point, the compiler starts knowing about meaning, not just text. It knows that int main(void) declares a function, that printf is being called with two arguments, and so on.

Semantic Analysis

The compiler then type-checks your program. It verifies that you’re not passing a char* where an int is expected, that variables are declared before use, that return types match function signatures. This is where many of your familiar compiler errors originate — “incompatible types”, “undeclared identifier”, and so on.

A crucial insight: the compiler works on one translation unit at a time. A translation unit is essentially one .c file after preprocessing. The compiler does not see other .c files. It compiles them independently.

This is why you need declarations (like those in header files) — the compiler needs to know the signature of printf to type-check your call to it, even though printf’s actual implementation lives in the C standard library, which the compiler never touches. The header provides the declaration; the linker (later) will find the definition.

Optimization

Before generating assembly, modern compilers perform extensive optimization passes on an intermediate representation of your code. Techniques include:

  • Constant folding: computing 2 + 3 at compile time, replacing it with 5
  • Dead code elimination: removing branches or variables that can never be reached
  • Inlining: replacing a function call with the function’s body directly, avoiding call overhead
  • Loop unrolling: duplicating loop body iterations to reduce branching

The optimization level you choose (-O0, -O1, -O2, -O3) controls how aggressively these passes run.

Code Generation

Finally, the compiler emits assembly language — human-readable mnemonics for the target CPU’s instruction set (x86-64, ARM, RISC-V, etc.). The assembly for our main function will contain instructions to set up a stack frame, load the address of the format string into a register, call printf, and return 0.

Stage 3: The Assembler

The assembler’s job is comparatively mechanical. It takes the assembly (.s) file and translates each mnemonic into its binary encoding, producing an object file (.o). You can stop here with:

gcc -c hello.c -o hello.o

An object file is in a binary format — on Linux this is ELF (Executable and Linkable Format), on macOS it’s Mach-O, on Windows it’s COFF/PE. You can inspect it with tools like objdump or nm.

nm hello.o          # list symbols in the object file
objdump -d hello.o  # disassemble the machine code

The object file is almost an executable, but with one critical limitation: it contains unresolved references. Our hello.o contains machine code for main, but the call to printf is left as a placeholder — a reference to a symbol named printf that exists somewhere else. The object file essentially says: “I need something called printf. Whoever links me should provide it.”

This is a fundamental concept. The object file records both what it provides (its own symbols) and what it needs (external symbols). This is the contract that the linker will fulfill.

Stage 4: The Linker

The linker is the stage that most developers understand least, and it’s the source of some of the most confusing errors in C. Its job is to combine multiple object files and libraries into a single executable, resolving all those placeholder references along the way.

gcc hello.o -o hello    # gcc invokes the linker (ld) for you

Symbol Resolution

The linker maintains a global symbol table. It scans all provided object files and libraries, building a map of which symbol is defined where. Then it resolves every undefined reference by finding the matching definition.

When hello.o says “I need printf”, the linker finds printf’s definition in the C standard library (libc), notes its address, and patches the placeholder in hello.o’s machine code with the real address.

This is why you get “undefined reference to…“ errors — the linker searched through everything you gave it and could not find a definition for a symbol that some object file needs. Common causes:

undefined reference to `sqrt`

This happens when you use sqrt from <math.h> but forget to link the math library: gcc hello.c -lm. The -lm flag tells the linker to also search libm.so for symbol definitions.

The Difference Between Declaration and Definition

This is a core C concept that the compilation model makes concrete. A declaration tells the compiler “this thing exists, here’s its type.” A definition actually creates the thing — allocates memory for a variable, or provides the body of a function.

// Declaration — tells the compiler the signature; no code generated
extern int global_counter;
int add(int a, int b);

// Definition — actually creates the variable and function
int global_counter = 0;
int add(int a, int b) { return a + b; }

You can have many declarations across many files (as long as they’re consistent), but exactly one definition per symbol across the entire program. This is called the One Definition Rule (ODR). Violate it and the linker will complain:

multiple definition of `add`

Static vs. Dynamic Linking

The linker can incorporate library code in two ways.

With static linking, the linker physically copies the relevant machine code from library archives (.a files) into your executable. The result is a self-contained binary — it has everything it needs and doesn’t depend on the system having any particular library installed. The tradeoff is larger binary size and the fact that if the library has a bug fix, you must recompile.

With dynamic linking, the linker only records a reference to the shared library (.so on Linux, .dylib on macOS, .dll on Windows). The actual library code stays in a separate file on disk. At runtime, the OS’s dynamic linker/loader loads the shared library into memory and resolves the references — a process called load-time linking. This means smaller binaries, shared memory between processes using the same library, and the ability to update the library without recompiling dependent programs.

Relocation

One more thing the linker does: relocation. Object files are compiled without knowing what final address they’ll sit at in the executable. The linker assigns each section a final address, then patches all address references throughout the machine code to reflect the real, final layout. This is why object files contain relocation tables — lists of places that need to be patched once addresses are known.

Stage 5: The Executable

The final output is a complete, executable binary. On Linux, you can inspect it:

file hello           # confirm it's an ELF executable
ldd hello            # show which shared libraries it depends on
objdump -d hello     # disassemble the full executable
readelf -h hello     # show ELF header information

When you run ./hello, the OS kernel reads the ELF header, maps the program’s segments into virtual memory, and if the program uses dynamic libraries, invokes the dynamic linker (ld-linux.so) to load and link those. Then control is transferred to _start — a small piece of startup code provided by the C runtime that initializes the environment and calls your main.

Putting It All Together: A Mental Model

Here’s a useful way to think about the whole pipeline through the lens of what each stage knows about:

The preprocessor knows about files and text substitution but is blind to C itself. The compiler knows about C semantics and one file at a time but knows nothing about other source files. The assembler knows about CPU instructions but nothing about the program’s structure. The linker knows about the whole program — all the object files together — but nothing about C syntax.

This layered ignorance is elegant design. Each tool is sharp, focused, and composable.

Why This Matters Practically

Every confusing error in C has a home in this model. “Implicit declaration of function” means the compiler didn’t see a declaration before the call — a header is missing. “Undefined reference” means the linker couldn’t find the definition — a library or object file is missing from the link command. “Multiple definition” means two translation units both defined the same symbol — you put a function body in a header that got included twice. “Macro expanded unexpectedly” means you forgot that the preprocessor is doing naive text substitution.

When something goes wrong, ask yourself: which stage failed? That question will guide you directly to the fix. Therefore, the C compiler itself is the first helper. For learning more about C, we can use the manpages or specifically the man 3 for getting more help.