Precompiled headers (PCH)
Precompiled headers are the fastest incremental-build optimization for C++ projects that include heavy headers (STL, boost, project-wide includes). HelpMake has first-class PCH support across GCC, Clang, MSVC, and both Zig C modes.
Quick example
Compiler: g++
Version: std=c++20
Output: build/app
PCH: include/pch.hpp
InputFiles {
src/*.cpp
}
Includes {
include
}Then in every .cpp:
#include "pch.hpp"
// … rest of the fileOn the first build, HelpMake:
- Compiles
include/pch.hppintobuild/HelpMake/headers/gcc/pch.hpp.gch - Adds
-include include/pch.hppto every subsequent compile command - Reuses the compiled header on every future build until it becomes stale
The savings grow with header size - for a header including <vector>, <string>, <map>, and <regex>, expect 2–5× faster compile times.
How the cache works
Cache location:
build/HelpMake/headers/<compiler-name>/<header-basename><pch-ext>Examples:
build/HelpMake/headers/gcc/pch.hpp.gch
build/HelpMake/headers/clang/pch.hpp.pch
build/HelpMake/headers/msvc/pch.hpp.pch
build/HelpMake/headers/zig-c++/pch.hpp.pch
build/HelpMake/headers/zig-cc/pch.hpp.pchPer-toolchain, so switching Compiler: never reuses a foreign PCH. The old cache is left in place and skipped.
Invalidation
HelpMake rebuilds the PCH when any of these are true:
- The header file (
PCH:value) is newer than the compiled PCH - Any dependency in the depfile for the PCH is newer
--rebuildis passed--cleanwas run (deletes the entirebuild/HelpMake/headers/tree)
When it rebuilds, every source file that depends on the PCH also recompiles automatically (the object files are older than the new PCH).
Per-toolchain extensions
| Toolchain | PCH extension | Injection flag | Notes |
|---|---|---|---|
| GCC | .gch | -include <header> | Uses header path, not PCH path |
| Clang | .pch | -include-pch <pch> | Uses PCH binary |
| MSVC | .pch | /Yu<header> /Fp<pch> | Source-file-based, requires first-include rule |
| Zig C++ | .pch | -include-pch <pch> | Same as Clang |
| Zig CC | .pch | -include-pch <pch> | Same as Clang, but -x c-header |
| Zig | - | - | Not supported (one-shot) |
| Generic | - | - | Not supported |
Common pitfalls
MSVC requires the header to be the first include
MSVC's PCH model is stricter than GCC/Clang. Every .cpp that uses the PCH must begin with:
#include "pch.hpp"with no #include before it. Otherwise the compile fails with:
fatal error C1010: unexpected end of file while looking for precompiled headerHelpMake generates a synthetic build/HelpMake/headers/msvc/pch.cpp that includes the header, and passes /Yc + /Yu correctly - but the first-include rule is on your sources, not on HelpMake.
GCC uses -include <header>, not -include-pch <pch>
For GCC, -include-pch doesn't exist. Instead:
- PCH is compiled to
pch.hpp.gchnext topch.hpp - GCC automatically finds and uses it when you
-include pch.hpp
HelpMake handles this by passing -include include/pch.hpp (the header path), not -include-pch <pch binary>. This is a GCC-specific quirk that "just works" if you trust the mechanism.
Zig C++ / Zig CC cache the PCH differently from Clang
Zig's toolchain is LLVM-based but its PCH validation is stricter. If you switch Zig's target triple, or update Zig itself, cached PCHs can become incompatible. If you see "PCH was compiled with a different compiler," run:
hm --clean
hm -bChanging flags invalidates the PCH
Adding -DNDEBUG or changing -std= invalidates the PCH because the preprocessor state changed. HelpMake tracks flag changes (via the compiler fingerprint) and rebuilds the PCH when it sees one.
How to tell if PCH is working
Run with --verbose:
hm -b --verboseYou'll see:
[HelpMake] PCH Command: g++ -std=c++20 -Iinclude -Wall -x c++-header include/pch.hpp -o build/HelpMake/headers/gcc/pch.hpp.gchon the first build, or after invalidation. On subsequent builds you'll see the PCH step skipped and every source compile get -include include/pch.hpp added.
When not to use PCH
- One-shot builds (
--no-sep): PCH adds no value if you recompile everything anyway - Very small projects: setup overhead (~1s) exceeds savings
- Projects with many disjoint headers: if no single header is included by >50% of sources, split into multiple PCH files or skip it
The best PCH covers 80%+ of your sources and includes only stable, rarely-changed headers (STL, third-party libraries). Project headers that change frequently belong in regular includes, not the PCH.
