Workflow:ClickHouse ClickHouse Building From Source
| Knowledge Sources | |
|---|---|
| Domains | Build_Systems, C++_Development, Database_Engineering |
| Last Updated | 2026-02-08 17:00 GMT |
Overview
End-to-end process for building the ClickHouse database system from source code using CMake and Ninja, producing a single monolithic binary that serves as server, client, and multiple utility tools.
Description
This workflow covers the complete compilation pipeline for ClickHouse, from cloning the repository through producing the final executable. ClickHouse uses a "busybox-style" architecture where a single binary (`clickhouse`) dispatches to different sub-applications (server, client, local, keeper, benchmark, and many others) based on the invoked symlink name or first command-line argument. The build system relies on CMake for configuration and Ninja for parallel compilation. It manages over 100 third-party dependencies via git submodules and a vendored Poco C++ framework. The output is a statically-linked binary that can run on any compatible Linux system.
Usage
Execute this workflow when you need to compile ClickHouse from source, whether for development, testing custom patches, building with sanitizers (ASan, TSan, MSan, UBSan), creating debug builds, or producing release binaries for deployment. This is the primary workflow for any ClickHouse contributor or developer.
Execution Steps
Step 1: Clone Repository and Initialize Submodules
Clone the ClickHouse repository including all git submodules. ClickHouse depends on over 100 third-party libraries managed as submodules under the `contrib/` directory. The repository uses a script (`contrib/update-submodules.sh`) to selectively initialize only the submodules needed for the current build configuration rather than fetching all of them.
Key considerations:
- Use `--recursive` when cloning or run `git submodule update --init` separately
- The `contrib/update-submodules.sh` script can optimize by skipping unneeded submodules
- The build will fail early if submodules are missing (checked via `contrib/sysroot/README.md` existence)
Step 2: Configure Build with CMake
Run CMake to generate build files, specifying the desired build type and options. ClickHouse supports multiple build configurations including Release, RelWithDebInfo, Debug, and sanitizer builds (ASan, TSan, MSan, UBSan). The root `CMakeLists.txt` orchestrates the entire configuration, including architecture detection, toolchain setup, compiler cache (ccache), and feature toggles for optional components like Keeper, fuzzing support, and Rust components.
Key considerations:
- Default build type is `RelWithDebInfo` if not specified
- Build into a separate directory (e.g., `build/`, `build_debug/`, `build_asan/`)
- Use the system's Clang compiler (GCC is not supported)
- Do not pass `-j` to Ninja; let it auto-detect parallelism
- Key CMake options include `ENABLE_CLICKHOUSE_ALL`, `ENABLE_FUZZING`, `ENABLE_CLICKHOUSE_KEEPER`
Step 3: Compile Third-Party Dependencies
The build system compiles all required third-party libraries from the `contrib/` directory. The `contrib/CMakeLists.txt` file defines the `add_contrib` function and sequences the compilation of dependencies with proper ordering. This includes core libraries like OpenSSL, Boost, zlib, protobuf, and the vendored Poco C++ framework (Foundation, JSON, Net, NetSSL_OpenSSL, XML, Util, Redis). The `base/` directory also provides essential utility libraries including glibc compatibility shims for static linking.
Key considerations:
- Warnings are suppressed for third-party code
- UBSan is disabled for contrib to avoid false positives
- The glibc compatibility layer (`base/glibc-compatibility/`) provides musl-based reimplementations for portable static binaries
- The vendored Poco framework provides networking, HTTP, SSL, and JSON capabilities
Step 4: Compile Base Libraries
Build the ClickHouse base utility libraries under `base/base/`. These provide fundamental types (wide integers, decimals, BFloat16), SIMD-optimized string operations, memory management primitives, sanitizer interfaces, and cross-platform abstractions. The `base/harmful/` library poisons dangerous C functions to prevent their accidental use.
Key considerations:
- Wide integer support (128-bit, 256-bit) is critical for ClickHouse's type system
- SIMD-optimized string search (`find_symbols.h`) and comparison (`memcmpSmall.h`) are performance-critical
- The harmful library enforces code safety by trapping calls to non-thread-safe functions
Step 5: Compile Core Source and Programs
Build the main ClickHouse source tree (`src/`) and the program entry points (`programs/`). The `programs/main.cpp` file serves as the universal entry point, maintaining a priority-ordered dispatch table that maps application names to their entry functions. Each sub-application (server, client, local, keeper, benchmark, etc.) is built as a separate library and linked into the final binary.
Key considerations:
- The dispatch table in `programs/main.cpp` has priority ordering for argument disambiguation
- Short aliases are supported (e.g., `chl` for local, `chc` for client)
- Optional components like Keeper require NuRaft and can be disabled
- The binary disables `dlopen` for security and configures sanitizer defaults
Step 6: Link Final Binary
Link all compiled objects and libraries into the final `clickhouse` binary. The resulting executable is a statically-linked monolithic binary that includes all sub-applications. Symlinks are created for each application name (e.g., `clickhouse-server`, `clickhouse-client`, `clickhouse-local`) that point to the same binary.
Key considerations:
- The final binary supports self-extracting mode for compressed distribution
- Debug symbols can be split into separate files using `split_debug_symbols.cmake`
- The binary includes a hash section for integrity verification (`hash-binary` subcommand)
Step 7: Verify Build
Validate the build by running the compiled binary with basic commands. Check that the server can start, the client can connect, and fundamental operations work correctly.
Key considerations:
- Run `clickhouse local -q "SELECT 1"` for a quick sanity check without starting a server
- Run `clickhouse server --config-file ./programs/server/config.xml` to test server mode
- Check `clickhouse client -q "SELECT 1"` against a running server