Implementation:Duckdb Duckdb CMake Project Configuration

Metadata

Field	Value
Type	Implementation (External Tool Doc)
Source Files	`CMakeLists.txt:L1-50` (project setup), `CMakeLists.txt:L400-470` (build options), `Makefile:L349-353` (release target)
Domains	Build_System

Overview

Concrete tool for configuring the DuckDB build system using CMake and Makefile convenience targets. This implementation translates the declarative project specification in DuckDB's CMakeLists.txt into platform-native build files (Ninja, Make, etc.) by invoking CMake with the appropriate generator and option flags. A set of Makefile convenience targets wraps common configuration and build invocations for developer ergonomics.

Code Reference

Core CMake Invocation

The canonical command to configure a release build of DuckDB is:

cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../..

This is typically executed from within the build output directory (e.g., build/release/), with ../.. pointing back to the repository root where the top-level CMakeLists.txt resides.

Key CMake Options

Option	Type	Default	Description
`CMAKE_BUILD_TYPE`	String	(none)	Build variant: `Release`, `Debug`, `RelWithDebInfo`, or `MinSizeRel`
`BUILD_UNITTESTS`	BOOL	`TRUE`	Compile the unit-test suite
`BUILD_BENCHMARKS`	BOOL	`FALSE`	Compile benchmark binaries
`DISABLE_UNITY`	BOOL	`FALSE`	Disable unity (jumbo) builds; compile each translation unit separately
`BUILD_MAIN_DUCKDB_LIBRARY`	BOOL	`TRUE`	Build the main `libduckdb` shared/static library target
`EXTENSION_STATIC_BUILD`	BOOL	`FALSE`	Statically link extensions into the main library
`TREAT_WARNINGS_AS_ERRORS`	BOOL	`FALSE`	Promote compiler warnings to errors (`-Werror`)

Makefile Convenience Target (Release)

The top-level Makefile provides a release target that automates directory creation, CMake configuration, and the build step:

release:
	mkdir -p build/release && \
	cd build/release && \
	cmake $(GENERATOR) $(FORCE_COLOR) ${WARNINGS_AS_ERRORS} ${FORCE_32_BIT_FLAG} ${DISABLE_UNITY_FLAG} ${DISABLE_CRASH_FLAG} ${DISABLE_SANITIZER_FLAG} ${STATIC_LIBCPP} ${CMAKE_VARS} -DCMAKE_BUILD_TYPE=Release ../.. && \
	cmake --build . --config Release

The $(GENERATOR) variable defaults to -G "Unix Makefiles" but can be overridden by setting the GEN environment variable (e.g., GEN=ninja selects the Ninja generator).

I/O Contract

Inputs

Input	Description
`CMakeLists.txt` (root)	Top-level project declaration: project name, version, minimum CMake version, global options, subdirectory inclusions
`CMakeLists.txt` (subdirectories)	Per-component build declarations (sources, targets, dependencies)
Environment variable `GEN`	Selects the CMake generator (e.g., `ninja`)
Environment variable `FORCE_COLOR`	Forces coloured compiler output
Environment variable `CMAKE_VARS`	Additional `-D` flags passed through to CMake

Outputs

Output	Location	Description
Release build directory	`build/release/`	Contains generated build files, object files, and final artefacts for a Release build
Debug build directory	`build/debug/`	Contains generated build files, object files, and final artefacts for a Debug build
`CMakeCache.txt`	`build/<variant>/CMakeCache.txt`	Cached values of all resolved CMake variables for the configuration
Native build files	`build/<variant>/`	`build.ninja`, `Makefile`, or IDE project files depending on the chosen generator

Usage Examples

Configure a Release Build with Ninja

mkdir -p build/release
cd build/release
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../..

Configure a Debug Build with Unit Tests

mkdir -p build/debug
cd build/debug
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNITTESTS=TRUE ../..

Configure with Static Extensions and No Unity Build

mkdir -p build/release
cd build/release
cmake -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DEXTENSION_STATIC_BUILD=TRUE \
    -DDISABLE_UNITY=TRUE \
    ../..

Use the Makefile Convenience Target

# Default generator (Unix Makefiles)
make release

# Use Ninja generator
GEN=ninja make release

# Pass extra CMake variables
CMAKE_VARS="-DBUILD_BENCHMARKS=TRUE" make release

Page Connections

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

Principle

Implementation

Heuristic

Environment