Principle:ClickHouse ClickHouse CMake Build Configuration
| Knowledge Sources | |
|---|---|
| Domains | Build_System, C++ |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
CMake-based build system configuration is the process of using CMake to generate native build files for a large C++ project, managing hundreds of compile-time options, compiler flags, and platform-specific settings from a single declarative configuration.
Description
ClickHouse uses CMake as its meta-build system to generate Ninja build files for compilation. The root CMakeLists.txt file (696 lines) serves as the central configuration point where the project is declared, compiler standards are set, platform detection occurs, and all major build options are defined.
The project declaration at line 18 is:
project(ClickHouse LANGUAGES C CXX ASM)
This declares a multi-language project using C, C++, and assembly. The C++ standard is set to C++23 (CMAKE_CXX_STANDARD 23), the C standard to C11, and the project requires CMake version 3.25 or higher.
CMake's strength in this context is its ability to abstract platform differences. The same CMakeLists.txt handles Linux (amd64, aarch64, s390x, riscv64), macOS (Darwin), and FreeBSD targets, with platform-specific settings included conditionally via cmake/ modules such as cmake/arch.cmake, cmake/target.cmake, and platform-specific default library configurations under cmake/linux/, cmake/darwin/, and cmake/freebsd/.
A key design decision is the use of the Ninja generator rather than Makefiles. Ninja provides faster incremental builds due to its minimal overhead and implicit dependency tracking. The project enables colored compiler output specifically for Ninja builds.
ClickHouse defines a large number of build-time options using CMake's option() command. These options control which features are compiled into the binary, whether tests are built, which sanitizers are enabled, and how the binary is linked. The default build type, if not specified, is RelWithDebInfo (Release with Debug Information), which provides optimized code with debugging symbols.
Usage
Use CMake-based build configuration when:
- A project must support multiple platforms, compilers, and build types from a single source tree.
- Fine-grained control over compile-time features is needed (enabling/disabling specific libraries, sanitizers, or optimizations).
- The project is large enough that build system abstraction and incremental compilation are essential for developer productivity.
- Cross-compilation support is required (ClickHouse supports building native helper tools alongside cross-compiled targets).
Theoretical Basis
CMake operates in two phases:
Configuration phase: CMake reads CMakeLists.txt files, evaluates conditions, sets variables, and builds an internal representation of targets and their dependencies. This is where options are resolved and platform detection occurs.
Generation phase: CMake produces native build files (Ninja, Makefiles, etc.) from its internal representation. The generated files contain the exact compiler commands, dependency graphs, and link orders needed to build all targets.
The configuration flow for ClickHouse follows this structure:
1. cmake_minimum_required(VERSION 3.25)
2. project(ClickHouse LANGUAGES C CXX ASM)
3. Include platform detection modules (arch, target, tools, ccache)
4. Set build type (default: RelWithDebInfo)
5. Define options (ENABLE_TESTS, GLIBC_COMPATIBILITY, ENABLE_THINLTO, WERROR, etc.)
6. Configure compiler flags (C++23, -O3 for release, debug info, -falign-functions=64)
7. Configure linker flags (--no-export-dynamic, --gc-sections, ThinLTO)
8. Define macro clickhouse_add_executable (malloc interposition)
9. Add subdirectories: contrib/ -> base/ -> src/ -> programs/
10. Generate config.h, config_version.cpp, compile_commands.json
The version information is maintained in cmake/autogenerated_versions.txt, which is updated by CI tooling. This file defines VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH, and VERSION_GITHASH, which are propagated into the compiled binary.
ThinLTO (Thin Link-Time Optimization) is enabled by default for release builds without tests or sanitizers. It uses -flto=thin and -fwhole-program-vtables to enable cross-translation-unit optimizations at link time, significantly improving runtime performance at the cost of longer link times.