Implementation:ClickHouse ClickHouse CMake Project Configuration

Knowledge Sources	ClickHouse
Domains	Build_System, C++
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for configuring the ClickHouse build system provided by the root CMakeLists.txt project declaration and option definitions.

Description

The root CMakeLists.txt is the entry point for CMake configuration of ClickHouse. At line 18 it declares the project:

project(ClickHouse LANGUAGES C CXX ASM)

This 696-line file orchestrates the entire build by:

Requiring CMake >= 3.25 and setting policy CMP0126 to NEW (prevents cache variables in contrib from overriding normal variables).
Detecting architecture and OS via included modules (cmake/arch.cmake, cmake/target.cmake).
Defining the C++ standard as C++23 and the C standard as C11.
Setting compiler flags: -falign-functions=64 for stable benchmark results, -fasynchronous-unwind-tables for the Query Profiler, -ffp-contract=off for consistent floating-point results.
Defining ThinLTO settings for non-test release builds: -flto=thin -fwhole-program-vtables.
Defining the clickhouse_add_executable macro for malloc interposition.
Adding subdirectories in order: contrib, base, src, programs, utils.

The version information comes from cmake/autogenerated_versions.txt, which currently defines version 26.2.1.1.

Usage

Invoke CMake to configure the build before compiling. The Ninja generator is the recommended (and expected) choice. A typical invocation creates a build directory with all necessary Ninja files, configuration headers, and compile_commands.json for IDE integration.

Code Reference

Source Location

Repository: ClickHouse
File: CMakeLists.txt
Lines: 1-696

Signature

cmake -S . -B build -G Ninja \
    [-DCMAKE_BUILD_TYPE=RelWithDebInfo] \
    [-DCMAKE_C_COMPILER=clang] \
    [-DCMAKE_CXX_COMPILER=clang++] \
    [-DENABLE_TESTS=ON] \
    [-DENABLE_LIBRARIES=ON] \
    [-DGLIBC_COMPATIBILITY=ON] \
    [-DENABLE_THINLTO=ON] \
    [-DSPLIT_DEBUG_SYMBOLS=OFF] \
    [-DWERROR=ON]

Import

# Standard configuration with defaults:
cmake -S . -B build -G Ninja

# Build after configuration:
ninja -C build clickhouse

I/O Contract

Inputs

Name	Type	Required	Description
`CMAKE_BUILD_TYPE`	String	No (default: `RelWithDebInfo`)	Build type: `Release`, `Debug`, `RelWithDebInfo`, or `MinSizeRel`
`ENABLE_TESTS`	Boolean	No (default: `ON`)	Build unit tests (disables ThinLTO when enabled)
`ENABLE_LIBRARIES`	Boolean	No (default: `ON`)	Enable all external libraries (S3, Kafka, ODBC, etc.)
`GLIBC_COMPATIBILITY`	Boolean	No (default: `ON` on Linux amd64/aarch64)	Enable glibc compatibility shims for portable binaries
`ENABLE_THINLTO`	Boolean	No (default: `ON` when tests and sanitizers are off, Linux only)	Enable Clang ThinLTO link-time optimization
`SPLIT_DEBUG_SYMBOLS`	Boolean	No (default: `OFF`)	Separate debug symbols into a distinct directory
`WERROR`	Boolean	No (default: `ON`)	Treat compiler warnings as errors
`ENABLE_FUZZING`	Boolean	No (default: `OFF`)	Enable libfuzzer-based fuzzing instrumentation
`SANITIZE`	String	No	Enable sanitizer builds: `address`, `memory`, `thread`, `undefined`
Source tree	Directory	Yes	ClickHouse source with populated `contrib/` submodules
`cmake/autogenerated_versions.txt`	File	Yes	Version definitions (currently 26.2.1.1)

Outputs

Name	Type	Description
`build/build.ninja`	File	Ninja build file containing all compilation and link rules
`build/compile_commands.json`	File	Compilation database for IDE and tooling integration
`build/includes/configs/config.h`	File	Generated configuration header with feature flags
`build/src/Common/config_version.cpp`	File	Generated source file with version information compiled into the binary

Usage Examples

Standard Release Build

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DCMAKE_C_COMPILER=clang-19 \
    -DCMAKE_CXX_COMPILER=clang++-19
ninja -C build clickhouse

Debug Build With Tests

cmake -S . -B build_debug -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DENABLE_TESTS=ON
ninja -C build_debug clickhouse unit_tests_dbms

ASan Build

cmake -S . -B build_asan -G Ninja \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DSANITIZE=address \
    -DENABLE_TESTS=ON
ninja -C build_asan clickhouse

Minimal Build Without External Libraries

cmake -S . -B build_minimal -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DENABLE_LIBRARIES=OFF \
    -DENABLE_TESTS=OFF
ninja -C build_minimal clickhouse

Related Pages

Implements Principle

Principle:ClickHouse_ClickHouse_CMake_Build_Configuration

Requires Environment

Environment:ClickHouse_ClickHouse_Linux_Build_Environment

Uses Heuristic

Page Connections

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

Principle

Implementation

Heuristic

Environment