Implementation:ClickHouse ClickHouse Common Library Build

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

Overview

Concrete tool for compiling ClickHouse's foundation utility libraries provided by the base/base/CMakeLists.txt and base/glibc-compatibility/CMakeLists.txt build definitions.

Description

The base layer compilation produces two critical static libraries:

The common library is defined at line 38 of base/base/CMakeLists.txt as:

add_library (common ${SRCS})

It compiles 26 source files including argsToConfig.cpp, cgroupsv2.cpp, demangle.cpp, getMemoryAmount.cpp, itoa.cpp, JSON.cpp, mremap.cpp, phdr_cache.cpp, Numa.cpp, and a generated GitHash.generated.cpp that embeds the Git commit hash. The library exports include directories and links against:

• ch_contrib::cityhash -- Fast non-cryptographic hashing
• boost::headers_only, boost::system -- Boost headers and system library
• Poco::Net, Poco::Net::SSL, Poco::Util, Poco::Foundation -- Networking, SSL, configuration
• ch_contrib::replxx -- Terminal line editing
• ch_contrib::cctz -- Time zone handling
• ch_contrib::fmt -- String formatting
• ch_contrib::magic_enum -- Compile-time enum reflection

The glibc-compatibility library is defined at line 37 of base/glibc-compatibility/CMakeLists.txt as:

add_library(glibc-compatibility STATIC ${glibc_compatibility_sources})

This library is gated by the GLIBC_COMPATIBILITY CMake option and is only built on Linux for amd64 or aarch64 architectures. It compiles musl-derived C sources plus architecture-specific assembly files (syscall.s, longjmp.s) and uses -fomit-frame-pointer to match glibc performance. The library and an optional memcpy object are linked to the global-libs interface, making them available to all targets.

Usage

These libraries are built automatically as part of the standard CMake build. The common library is a dependency of nearly every ClickHouse target. The glibc-compatibility library is automatically linked when GLIBC_COMPATIBILITY=ON.

Code Reference

Source Location

• Repository: ClickHouse
• File: base/base/CMakeLists.txt (line 38: common library)
• File: base/glibc-compatibility/CMakeLists.txt (line 37: glibc-compatibility library)

Signature

# common library (base/base/CMakeLists.txt)
add_library (common ${SRCS})
target_link_libraries (common PUBLIC
    ch_contrib::cityhash
    boost::headers_only
    boost::system
    Poco::Net
    Poco::Net::SSL
    Poco::Util
    Poco::Foundation
    ch_contrib::replxx
    ch_contrib::cctz
    ch_contrib::fmt
    ch_contrib::magic_enum
)

# glibc-compatibility library (base/glibc-compatibility/CMakeLists.txt)
add_library(glibc-compatibility STATIC ${glibc_compatibility_sources})
target_link_libraries(global-libs INTERFACE glibc-compatibility ${MEMCPY_LIBRARY})

Import

# Other targets link against the common library:
target_link_libraries(my_target PRIVATE common)

# glibc-compatibility is linked automatically via global-libs (no explicit import needed)

I/O Contract

Inputs

Name	Type	Required	Description
GLIBC_COMPATIBILITY	Boolean	No (default: ON on Linux amd64/aarch64)	Gates compilation of the glibc-compatibility library
WITH_COVERAGE	Boolean	No (default: OFF)	When ON, adds WITH_COVERAGE=1 preprocessor definition to common
Third-party libraries	CMake targets	Yes	ch_contrib::cityhash, boost::headers_only, boost::system, Poco::*, ch_contrib::replxx, ch_contrib::cctz, ch_contrib::fmt, ch_contrib::magic_enum
Architecture	Platform	Yes	Determines which assembly files are compiled for glibc-compatibility: amd64 uses musl/x86_64/, aarch64 uses musl/aarch64/

Outputs

Name	Type	Description
common	Static library	Foundation utility library (26 sources) linked by most ClickHouse targets
glibc-compatibility	Static library	musl-derived glibc compatibility shims (Linux amd64/aarch64 only)
memcpy	Object library	Optional optimized memcpy implementation (linked alongside glibc-compatibility)
Poco libraries	Static libraries	7 Poco framework components: Foundation, XML, JSON, Util, Net, Net::SSL, Crypto

Usage Examples

Verify common Library Sources

# List all source files compiled into the common library:
grep -A 30 'set (SRCS' base/base/CMakeLists.txt

Build Only Base Libraries

# After CMake configuration, build just the common library:
ninja -C build common

# Build the glibc-compatibility library:
ninja -C build glibc-compatibility

Check glibc-compatibility Status

# In CMake output, look for this message:
# "Some symbols from glibc will be replaced for compatibility"
cmake -S . -B build -G Ninja 2>&1 | grep "glibc"

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Base_Library_Compilation

Requires Environment

• Environment:ClickHouse_ClickHouse_Linux_Build_Environment