Implementation:Duckdb Duckdb Add Library Unity

Overview

Concrete tool for compiling the DuckDB core library using unity build optimization provided by the CMake build system.

The add_library_unity() CMake function wraps the standard add_library() call with an optional unity build preprocessing step. When unity builds are enabled, source files are grouped into larger translation units before compilation, significantly reducing build times.

Code Reference

Source Locations

Component	Location
`add_library_unity()` function	`CMakeLists.txt:L754-763`
`enable_unity_build()` function	`CMakeLists.txt:L734-752`
Core library target definitions	`src/CMakeLists.txt:L1-151`

`add_library_unity()`

function(add_library_unity NAME MODE)
  set(SRCS ${ARGN})
  if(NOT DISABLE_UNITY)
    enable_unity_build(${NAME} SRCS)
  endif()
  add_library(${NAME} OBJECT ${SRCS})
  if(MSVC)
    target_compile_options(${NAME} PRIVATE /bigobj)
  endif()
endfunction()

`enable_unity_build()`

function(enable_unity_build UB_SUFFIX SOURCE_VARIABLE_NAME)
  set(files ${${SOURCE_VARIABLE_NAME}})

  # Generate unity build source files that #include groups of .cpp files
  # Each unity file includes a batch of source files as a single translation unit
  # The batch size is controlled by UNITY_BUILD_BATCH_SIZE (default: 40)

  # Replaces the source list variable with the generated unity files
  set(${SOURCE_VARIABLE_NAME} ${unity_files} PARENT_SCOPE)
endfunction()

Parameters

Parameter	Type	Description
`NAME`	String	The CMake target name for the library (e.g., `duckdb_catalog`, `duckdb_common`)
`MODE`	Enum	Library type: `OBJECT`, `STATIC`, or `SHARED`. In practice, module sub-libraries use `OBJECT` mode.
`SRCS` (via `ARGN`)	List	Variable-length list of `.cpp` source files to compile

I/O Contract

Inputs

Source files organized by module under src/:

src/
├── catalog/       → duckdb_catalog object library
├── common/        → duckdb_common object library
├── core_functions/→ duckdb_core_functions object library
├── execution/     → duckdb_execution object library
├── function/      → duckdb_function object library
├── main/          → duckdb_main object library
├── optimizer/     → duckdb_optimizer object library
├── parallel/      → duckdb_parallel object library
├── parser/        → duckdb_parser object library
├── planner/       → duckdb_planner object library
├── storage/       → duckdb_storage object library
└── transaction/   → duckdb_transaction object library

Outputs

Output	Target Name	Description
`libduckdb.so` (or `.dylib` / `.dll`)	`duckdb`	Shared library combining all module object libraries
`libduckdb_static.a` (or `.lib`)	`duckdb_static`	Static archive combining all module object libraries and third-party dependencies

Build Flags

Flag	Default	Effect
`DISABLE_UNITY`	`FALSE`	When set to `TRUE`, disables unity build grouping and compiles each source file individually
`BUILD_SHARED_LIBS`	`TRUE`	Controls whether the shared library target is built
`MSVC`	(auto-detected)	When compiling with MSVC, `/bigobj` is added to handle large unity translation units

Usage Examples

Standard Build (Unity Enabled)

mkdir -p build/release
cd build/release
cmake -DCMAKE_BUILD_TYPE=Release ../..
make -j$(nproc)

This invokes add_library_unity() for each module, groups source files into unity chunks, and compiles the core library.

Build Without Unity (Individual Compilation)

cmake -DDISABLE_UNITY=TRUE -DCMAKE_BUILD_TYPE=Debug ../..
make -j$(nproc)

Each .cpp file is compiled as its own translation unit. Useful for debugging or when incremental builds are preferred.

Build Static Library Only

cmake -DBUILD_SHARED_LIBS=FALSE -DCMAKE_BUILD_TYPE=Release ../..
make duckdb_static -j$(nproc)

Produces only the static archive libduckdb_static.a without building the shared library.

Using the Makefile Convenience Targets

# Release build (default)
make release

# Debug build
make debug

These top-level Makefile targets configure CMake and invoke the build with appropriate flags.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment