Heuristic:Duckdb Duckdb Unity Build Strategy
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Build_System |
| Last Updated | 2026-02-07 12:00 GMT |
Overview
DuckDB uses unity builds by default to dramatically reduce compilation time; disable with `DISABLE_UNITY=1` only for debugging, clang-tidy, or investigating include issues.
Description
Unity builds combine multiple `.cpp` files into single translation units, reducing redundant header parsing and enabling better whole-program optimization. DuckDB's custom implementation (via the `enable_unity_build` CMake function) generates `ub_*.cpp` files that `#include` multiple source files. This is enabled by default and is one of the primary reasons DuckDB builds faster than expected for its codebase size.
Usage
Apply this heuristic when deciding whether to enable or disable unity builds. Keep unity builds enabled (default) for normal development and CI. Disable unity builds (`DISABLE_UNITY=1 make`) only when:
- Running clang-tidy static analysis (needs per-file compilation)
- Debugging include dependency issues
- Investigating ODR (One Definition Rule) violations
The Insight (Rule of Thumb)
- Action: Leave unity builds at default (enabled) for normal development.
- Value: Reduces full rebuild time by 30-50% compared to per-file compilation.
- Trade-off: Individual file error messages may reference the unity file (`ub_*.cpp`) rather than the original source file. Incremental builds after changing a single file recompile the entire unity group.
- Override: Set `DISABLE_UNITY=1` in Makefile or `-DDISABLE_UNITY=1` in CMake to disable.
Reasoning
The DuckDB codebase has hundreds of `.cpp` files with shared headers. Without unity builds, each file independently parses all included headers, leading to massive redundancy. Unity builds amortize header parsing across all files in a group.
Code evidence from `CMakeLists.txt:99`:
option(DISABLE_UNITY "Disable unity builds." FALSE)
Makefile toggle from `Makefile:40-42`:
ifeq (${DISABLE_UNITY}, 1)
DISABLE_UNITY_FLAG=-DDISABLE_UNITY=1
endif
The unity build function from `CMakeLists.txt:695+` generates `ub_*.cpp` files that simply `#include` multiple source files, turning N compilation units into N/M compilation units (where M is the group size).