My Into Depth project is still fairly small, in the grand scheme of things. I’ve authored about 17k lines of code, which you’d think would compile pretty quickly, but I was seeing clean compile times of about 40 seconds. That is too long.<\/p>\n\n\n\n
Sure, I’m not just compiling the code I wrote. glad<\/code>, glm<\/code>, imgui<\/code>, and stb<\/code> increase the line count by about an order of magnitude to 120k. However, 40s is 40s, and I wanted to see what I could do to reduce it.<\/p>\n\n\n\n
Problems<\/h1>\n\n\n\n
There are fundamentally two problems here – long full compilation times and long incremental compilation times. A full compilation happens after, e.g., make clean<\/code>, where everything is compiled fresh. This naturally takes longer, since all object files have to be generated. An incremental compilation is what happens most of the time, where you have an existing set of object files and just need to recompile one or two of them and re-link.<\/p>\n\n\n\n
The Compilation Process<\/h1>\n\n\n\n
To understand how we’re going to speed things up, its helpful to understand what, roughly, is happening in the first place.<\/p>\n\n\n\n
The Preprocessor<\/h3>\n\n\n\n
The first stage, before any compiling happens, is where the preprocessor runs over each .cpp<\/code> file and specifically handles # commands. The preprocessor doesn’t actually understand C++ syntax, but is more of a glorified find and replace tool.<\/p>\n\n\n\n
\n
It finds every #include<\/code> and copy-pastes the contents of that header file into the .cpp<\/code> file.<\/li>\n\n\n\n
It finds every #define<\/code>, i.e., macro, and replaces it with the corresponding text.<\/li>\n\n\n\n
It strips out all comments.<\/li>\n<\/ul>\n\n\n\n
The result is a massive, single file of pure C++ code called a translation unit<\/em>. For a standard codebase where your C++ file has many inputs, the translation unit can be pretty large.<\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
The Compiler<\/h3>\n\n\n\n
The compiler translates the C++ code in each translation unit into raw machine code – the binary instructions that your specific CPU understands – as an object file.<\/em> On Linux\/Mac, these are .o<\/code> files, and on Windows these are .obj<\/code> files.<\/p>\n\n\n\n
Object files contain:<\/p>\n\n\n\n
\n
A header<\/li>\n\n\n\n
a code segment with the binary instructions for the functions defined in the translation unit<\/li>\n\n\n\n
a data segment with initialized static variables <\/li>\n\n\n\n
a read-only data segment with initialized static constants<\/li>\n\n\n\n
a section for uninitialized static data (e.g., int stuffs[1000000];<\/code>)<\/li>\n\n\n\n
A symbol table<\/em> listing the functions and variables that this translation unit can offer to others.<\/li>\n\n\n\n
A set of unresolved references that the object file expects to exist but doesn’t have just yet – functions or global variables it needs from other object files.<\/li>\n\n\n\n
Debugging information.<\/li>\n<\/ul>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
Concepts like structs only matter during the compilation phase, where they inform the compiler how much memory to allocate on the stack or what offsets to look at variables for. The resulting object files only care about memory addresses, function blocks, and global variables.<\/p>\n\n\n\n
The Linker<\/h3>\n\n\n\n
Once all of the .cpp<\/code> files have been compiled into a bunch of .obj<\/code> files, the linker<\/em> will handle the task of resolving references. If an object file needs a reference that the linker cannot find, it will issue the undefined reference<\/code> or unresolved external symbol<\/code> errors we know so well. Similarly if it finds multiple object files offering the same function signatures, it will output a multiple definitions<\/code> error.<\/p>\n\n\n\n
When building a executable (as opposed to a library), the linker starts by creating a new, empty file on disk (e.g., game.exe<\/code>). This file has an OS-specific format, such as ELF on Linux and PE on Windows.<\/p>\n\n\n\n
Next, the linker reads every .obj<\/code> file and copies the machine code binary into the executable, stacking them into one large, contiguous section.<\/p>\n\n\n\n
Each object file listed its unresolved symbols, along with where, in its compiled code block, the address of the symbol should be written once the symbol is finally resolved. The linker thus works through the copied binary sections and writes the appropriate jump instructions to jump to the right function calls or load the right global variable address. This process is called relocation<\/em>.<\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
The linking step also handles any libraries that your executable depends on. Any static library<\/em> (.a<\/code> for ‘archive’ file on Linux, .lib<\/code> on Windows) is basically a collection of object files, and is copied into your executable like the other objects. Any shared library<\/em> (.so<\/code> file on Linux, .dll<\/code> for ‘dynamic linked library’ on Windows) is not<\/em> copied, but the linker instead records a reference to it in the executable that the dynamic linker <\/em> connects when your OS goes to execute your file.<\/p>\n\n\n\n
Once the linker has completed relocation, it is done, and game.exe<\/code> is a self-contained block of machine code (except for references to dynamic libraries). You can actually delete all of the .obj<\/code> files and the executable will work just fine. The primary reason .obj<\/code> files are kept around is for incremental builds.<\/p>\n\n\n\n
<\/p>\n\n\n\n
Faster Clean Builds<\/h2>\n\n\n\n
Now that we have an understanding of the compilation process, we can reason about changes that will speed up compile time. The first such speedup will be for clean builds<\/em>, which is a complete build that runs the entire compilation pipeline without using any cached work.<\/p>\n\n\n\n
Under a typical build structure, many object files are produced and then linked:<\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
The trick here is the unity build<\/em>, which collapses the project’s many object files into just one:<\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
This is achieved by creating a .cpp<\/code> file that includes all of the project’s other .cpp<\/code> files, and then only have our Makefile build that one target.<\/p>\n\n\n\n
In practice, the linker still needs to do some work. Most code bases will still link against libraries, and it is recommended to compile external dependencies that we do have the source for into separate .obj<\/code> files and link against them.<\/p>\n\n\n\n
Time is saved in the linking phase by not having to stitch together potentially thousands of small object files. All of the memory math is handled by the compiler, which has access to all of the definitions.<\/p>\n\n\n\n
The primary time savings typically comes from eliminating redundant header parsing. In compilation, each translation unit receives copies of the headers it includes. The same header, such as <vector><\/code>, may be used in many translation units, and will be repeatedly parsed for each one. Having a single translation unit allows the #pragma once<\/code> guards to do their work and ensure the preprocessor only copies each header once, so each header is only parsed once.<\/p>\n\n\n\n
Unity builds also benefit from being able to do more inlining, as methods across translation units either cannot be inlined, or require link-time optimization to be enabled, which makes linking that much slower. In a unity build, everything is in one object file, so the entire program can be optimized.<\/p>\n\n\n\n
The final speedup comes from reduced disk I\/O. The compiler does not need to repeatedly read header files or write many object files.<\/p>\n\n\n\n
Moving to a unity build dropped clean build times for ~45s to under 5s!<\/p>\n\n\n\n
<\/p>\n\n\n\n
Faster Incremental Builds<\/h1>\n\n\n\n
During typical development, code is rebuilt incrementally. Here, a full build has already happened, you edit one or two .cpp<\/code> files, and run make<\/code> again. In an incremental build, only the .obj<\/code> files for the two edited .cpp<\/code> files need to be recompiled, followed by linking.<\/p>\n\n\n\n
Using a unity build means changing a single .cpp <\/code>file requires the compiler to do the full work of producing the one .obj<\/code> file all over again. As such, large projects will tend to use standard builds for typical development and unity builds for release builds or CI\/CD pipelines.<\/p>\n\n\n\n
We can use another technique to speed up incremental builds. Here, we aim to reduce the time it takes to compile individual object files.<\/p>\n\n\n\n
Time can be saved by reducing the work done by the preprocessor in copying header files included in other header files by using forward declarations<\/em> instead.<\/p>\n\n\n\n
Consider the following example, where a Weapon<\/code> struct is defined in weapon.h<\/code> and it is used by a Player<\/code> struct in player.h<\/code>: <\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
If we later change Weapon<\/code>, such as by adding a new int cooldown<\/code>, and go to compile, the build system will see that weapon.h<\/code> has changed. The player.h<\/code> file includes weapon.h<\/code>, so it is marked for recompilation and any file that includes player.h<\/code> is also recompiled. A simple field change has cascaded into a large number of updated object files.<\/p>\n\n\n\n
As written, player.h<\/code> must include weapon.h<\/code>, because Player<\/code> contains a Weapon<\/code>, and the compiler needs to know its size. We can avoid this dependency by using a pointer instead. The compiler cares about memory layouts, and pointers are all the same size, so we can use a forward declaration<\/em> to promise the compiler that Weapon<\/code> exists somewhere and avoid including weapon.h<\/code>:<\/p>\n\n\n\n<\/figure>\n\n\n\n
<\/p>\n\n\n\n
Now, if Weapon<\/code> is changed, player.h<\/code> is completely unaffected. Any .cpp<\/code> files that merely include player.h<\/code> no longer need to be recompiled.<\/p>\n\n\n\n
The same trick works for methods as well. Passing a struct like Weapon<\/code> by value will require knowing its size. Changing to a pointer or reference (which is basically a pointer) removes that requirement, and a forward declaration is enough to promise that the type will eventually be defined.<\/p>\n\n\n
\n<\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
The Best of Both Worlds<\/h1>\n\n\n\n
We can get the benefits of both unity builds during full recompilation and forward declarations during incremental builds by modifying our Makefile<\/code> to run a default incremental build when make<\/code> is involved and have a separate command, make unity<\/code>, that compiles unity.cpp<\/code> directly into an executable:<\/p>\n\n\n\n
# --------------------------------------------------------- # TARGET 2: The Unity Build # --------------------------------------------------------- # Notice this target does NOT depend on $(OBJS). It bypasses them. unity: src\/unity.cpp \t$(CXX) $(CFLAGS) src\/unity.cpp -o $(TARGET) $(LDFLAGS)<\/code><\/pre>\n\n\n\n
![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/06\/Compilation-2.jpg\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/06\/2026-06-28_14-13.png\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-04_13-37.png\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-04_13-52.png\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-04_13-56.png\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-05_14-24.png\")
<\/figure>\n<\/div>\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-05_14-38.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/timallanwheeler.com\/blog\/wp-content\/uploads\/2026\/07\/2026-07-05_14-52.png\")
<\/figure>\n<\/div>\n\n\n