Offensive Security Researcher & Quantum Cryptography Analyst

Standard C++ Compilation Process: Preprocessing, Compiling, Linking, and Execution

Abdul Wahab Junaid
standard C++ compilation process

standard C++ compilation process

When I first started learning C++, I typed my code into an editor, hit “run,” and a working program magically appeared a second later. It wasn’t until much later, when I hit a string of baffling linker errors, that I actually stopped to ask: what happens between me hitting “compile” and getting an executable file? It turns out there’s a whole pipeline running under the hood, and understanding it changed the way I debug code forever.

In this article, I’m going to walk you through the entire C++ build pipeline — preprocessing, compilation, assembly, linking, and finally execution — in plain language, with real code, real compiler commands, and real output. By the end, you won’t just know that g++ main.cpp -o main “builds your program.” You’ll know exactly what happens at every single stage, why it happens that way, and how to use that knowledge to fix bugs faster.

Why Understanding the Compilation Process Matters

A lot of beginners treat the compiler as a black box: source code goes in, executable comes out. That’s fine until something breaks. The moment you see an error like undefined reference to 'foo()' or fatal error: header.h: No such file or directory, you need to know which stage of the pipeline failed, because each stage fails for completely different reasons.

Here’s the short version of what’s coming:

  1. Preprocessing — text substitution and file inclusion
  2. Compilation — translating C++ source into assembly
  3. Assembly — turning assembly into machine code (object files)
  4. Linking — combining object files and libraries into one executable
  5. Execution — the operating system loads and runs the program

Let’s go through each one.

Stage 1: Preprocessing

Before a single line of your C++ code is actually “understood” by the compiler, it passes through the preprocessor. The preprocessor is a text-substitution tool. It doesn’t know anything about C++ syntax, types, or functions — it just processes directives that start with #.

Common preprocessor directives include:

Here’s a small example:

#include <iostream>
#define PI 3.14159

int main() {
    std::cout << "Value of PI is: " << PI << std::endl;
    return 0;
}

If I run only the preprocessing stage using GCC:

g++ -E main.cpp -o main.i

The -E flag tells the compiler to stop after preprocessing and dump the result. If you open main.i, you’ll see something surprising: the entire contents of <iostream> (and everything it includes) pasted directly into the file — often thousands of lines — followed by your main() function with PI literally replaced by 3.14159.

This is an important realization: #include is just a copy-paste operation. There is no “importing” in the way languages like Python or Java do it. This is also why large header files can slow down compilation — every single translation unit that includes them has to reprocess all that text.

What Happens Internally

The preprocessor works line by line, building an internal token stream. When it sees #include "file.h", it opens that file, reads its contents, and inserts them verbatim at that exact location before continuing. Macros defined with #define are handled similarly — anywhere the macro name appears as a token, it’s textually replaced.

This is why macros can be dangerous. Consider:

#define SQUARE(x) x * x

int result = SQUARE(1 + 2); // becomes 1 + 2 * 1 + 2 = 5, not 9!

Because the preprocessor does dumb text substitution, SQUARE(1 + 2) becomes 1 + 2 * 1 + 2, not (1+2) * (1+2). This is one of the most common “gotchas” in early C++ and one of the reasons modern C++ strongly prefers const/constexpr and inline functions over macros.

Stage 2: Compilation (Source to Assembly)

Once preprocessing finishes, the actual compiler front end takes over. This is where real C++ understanding begins: lexical analysis (tokenizing), parsing (building an Abstract Syntax Tree), semantic analysis (type checking, name resolution, overload resolution), and finally code generation into assembly language for the target CPU architecture.

To see just this stage:

g++ -S main.cpp -o main.s

The -S flag stops after generating assembly. Open main.s and you’ll see something like:

.LC0:
    .string "Value of PI is: "
main:
    push    rbp
    mov     rbp, rsp
    ...
    call    operator<<
    ...
    mov     eax, 0
    pop     rbp
    ret

This is human-readable (if you know assembly) x86-64 code that directly corresponds to your C++ logic. Every function call, every arithmetic operation, every loop your compiler could figure out gets translated here.

Compile-Time Errors Happen Here

This stage is where most beginner errors are caught — syntax errors, type mismatches, missing semicolons, calling undeclared functions, and so on. For example:

int main() {
    int x = "hello"; // type error
    return 0
}

Compiling this gives errors like:

error: invalid conversion from 'const char*' to 'int'
error: expected ';' before '}' token

These are compile-time errors, meaning the compiler itself refuses to produce assembly because your code doesn’t make semantic sense. This is different from linker errors, which I’ll get to shortly.

Stage 3: Assembly (Assembly to Machine Code)

The next stage takes the human-readable assembly and converts it into raw machine code — binary instructions the CPU can actually execute — stored inside an object file (.o on Linux/macOS, .obj on Windows).

g++ -c main.cpp -o main.o

The -c flag tells the compiler to compile and assemble but not link. If you try to run main.o directly, it won’t work — it’s not a complete executable. It contains machine code, but it also contains unresolved symbols: references to things like std::cout or operator<< that live in the C++ standard library, not in your file.

You can inspect an object file’s symbols using nm:

nm main.o

You’ll see entries like:

                 U _ZSt4cout
0000000000000000 T main
                 U _ZNSolsEPFRSoS_E

The U means “undefined” — this symbol is used here but defined somewhere else. The T means “defined in the text (code) section” — main is fully defined right here. This distinction is the whole reason the next stage exists.

Stage 4: Linking

Linking is the process of taking one or more object files, resolving all those “undefined” symbol references, and combining everything — your code plus the C++ standard library plus any other libraries — into a single executable file.

g++ main.o -o main

The linker’s job is essentially bookkeeping at scale: it scans every object file and library for symbol definitions, matches them against every undefined reference, and calculates final memory addresses for every function and variable. If it can’t find a definition for something you referenced, you get the infamous:

undefined reference to `someFunction()'

This is a linker error, not a compiler error — and it’s important to know the difference. A linker error means your code was syntactically and semantically fine (the compiler was happy), but the actual machine code for something you called doesn’t exist anywhere in the files being linked. This usually happens when:

Here’s a concrete example that produces a linker error:

// main.cpp
#include <iostream>
void greet(); // declared, never defined

int main() {
    greet();
    return 0;
}

g++ main.cpp -o main

Output:

undefined reference to `greet()'
collect2: error: ld returned 1 exit status

Notice this compiled fine — the compiler didn’t complain, because as far as it’s concerned, greet() exists somewhere (it trusts the declaration). It’s the linker that discovers, at the very end, that no object file actually contains machine code for greet().

Multiple Translation Units

Real projects rarely live in one file. Say I split things up:

// greet.cpp
#include <iostream>
void greet() {
    std::cout << "Hello from greet()!" << std::endl;
}

// main.cpp
void greet();
int main() {
    greet();
    return 0;
}

Each .cpp file is compiled independently into its own object file — this independent unit is called a translation unit. Then:

g++ -c greet.cpp -o greet.o
g++ -c main.cpp -o main.o
g++ main.o greet.o -o main
./main

Output:

Hello from greet()!

This is the fundamental reason C++ projects can be built incrementally: if I only change main.cpp, I only need to recompile main.o, not greet.o, then re-link. On large codebases, this saves enormous amounts of build time — it’s the whole idea behind build systems like Make and CMake.

Stage 5: Execution

Once linking succeeds, you have a genuine executable file. Running it (./main on Linux/macOS or main.exe on Windows) triggers the operating system’s loader, which:

  1. Reads the executable format (ELF on Linux, PE on Windows, Mach-O on macOS)
  2. Allocates memory segments — typically a text segment (your compiled code), a data segment (global/static variables), a heap (for dynamic memory via new/malloc), and a stack (for function calls and local variables)
  3. Resolves any dynamic library dependencies (shared .so/.dll/.dylib files) if you linked dynamically rather than statically
  4. Jumps execution to the entry point, which eventually calls your main()

This is also where runtime errors occur — things the compiler and linker cannot catch, like null pointer dereferences, out-of-bounds array access, division by zero, or stack overflows from infinite recursion. These are logic problems that only manifest when the CPU actually executes the faulty instruction.

Compiler Optimization and Performance Considerations

One thing that surprised me once I understood the pipeline is just how much the compilation stage can transform your code before it ever becomes assembly. The compiler doesn’t just translate your logic literally — depending on the optimization level you request, it can reorder instructions, eliminate dead code, inline small functions, unroll loops, and even remove variables entirely if it can prove they’re unused.

GCC exposes this through the -O family of flags:

g++ -O0 main.cpp -o main   # no optimization (default) - fastest to compile, easiest to debug
g++ -O1 main.cpp -o main   # basic optimizations
g++ -O2 main.cpp -o main   # more aggressive optimizations, commonly used for release builds
g++ -O3 main.cpp -o main   # maximum optimization, including aggressive inlining and vectorization
g++ -Os main.cpp -o main   # optimize for smaller binary size

Here’s a small example that shows the effect. Consider:

int add(int a, int b) {
    return a + b;
}

int main() {
    int result = add(3, 4);
    return result;
}

At -O0, the compiler generates a genuine function call to add() in the assembly — a call instruction, stack setup, the works. At -O2 or -O3, the compiler will typically inline this tiny function entirely, and may even compute 3 + 4 at compile time, replacing the whole thing with a single instruction that loads 7 directly. This is why debugging optimized (-O2/-O3) builds can feel disorienting — breakpoints on specific lines may never trigger, because those lines might not exist anymore in the generated machine code. This is also exactly why it’s standard practice to compile with -O0 (or -g -Og) during development and debugging, and switch to -O2 only for the final release build.

Putting It All Together: One Command, Five Hidden Stages

When you type:

g++ main.cpp -o main

GCC silently performs all four build stages (preprocessing, compiling, assembling, linking) back to back, then the OS handles execution when you run it. You can verify every intermediate stage yourself:

g++ -E main.cpp -o main.i    # Stage 1: Preprocessing
g++ -S main.i -o main.s      # Stage 2: Compilation to assembly
g++ -c main.s -o main.o      # Stage 3: Assembly to machine code
g++ main.o -o main           # Stage 4: Linking
./main                       # Stage 5: Execution

I’d genuinely recommend running this sequence yourself on a small file at least once. Watching your own #include statements expand into thousands of lines, or watching a .cpp file collapse into cryptic assembly, makes the whole process click in a way that reading about it never quite does.

Best Practices Around the Build Process

Common Mistakes and How to Debug Them

SymptomLikely StageLikely Cause
fatal error: file.h: No such filePreprocessingWrong include path or missing file
expected ';' before...CompilationSyntax error
invalid conversion from...CompilationType mismatch
undefined reference to...LinkingMissing definition or unlinked object/library
multiple definition of...LinkingSame non-inline function/variable defined in two translation units
Segmentation faultExecutionInvalid memory access at runtime

When I hit an error, the very first thing I do now is ask: is this a compiler error (something about my syntax or types) or a linker error (something about missing symbols)? That single question narrows down where to look by an order of magnitude.

Real-World Applications

Understanding this pipeline isn’t just academic. It directly helps with:

Interview Questions on This Topic

  1. What are the four main stages of C++ compilation?
  2. What’s the difference between a compile-time error and a linker error?
  3. Why does #include sometimes cause slow build times?
  4. What is a translation unit?
  5. What’s the difference between static and dynamic linking?
  6. Why do C++ projects use header files at all if the preprocessor just copies them in?
  7. What happens if the same non-inline function is defined in two .cpp files?

FAQs

Q: Is the preprocessor part of the compiler? Technically it’s a separate phase, though modern compilers like GCC and Clang bundle it into the same executable for convenience.

Q: Why do I get undefined reference even though my code compiles fine? Because compiling only checks syntax and semantics — it doesn’t verify that every referenced function actually has machine code generated for it somewhere. That check happens at the link stage.

Q: Does every #include slow down compilation? Yes, to some degree — each include textually expands into your file before compilation starts, so heavier headers mean more text to parse. This is one reason precompiled headers and modules (introduced in C++20) exist.

Q: What’s the difference between compiling and building? “Compiling” usually refers narrowly to source-to-object translation, while “building” refers to the entire pipeline: preprocessing, compiling, assembling, and linking.

Summary and Key Takeaways

The C++ build process isn’t magic — it’s a well-defined pipeline: preprocessing expands your text, compilation translates it to assembly after checking syntax and types, assembly converts that into machine code stored in object files, linking stitches every object file and library together into one executable, and finally the OS loads and executes that binary. Once you can mentally separate compiler errors from linker errors from runtime errors, debugging becomes dramatically faster because you immediately know which stage to investigate.

References

Exit mobile version