Implementation:ClickHouse ClickHouse Add Contrib Macro

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

Overview

Concrete tool for adding vendored third-party libraries to the ClickHouse build provided by the add_contrib CMake function in contrib/CMakeLists.txt.

Description

The add_contrib function is defined at lines 14-39 of contrib/CMakeLists.txt and is invoked approximately 90 times (lines 47-252) to register all vendored dependencies. It validates that submodule directories exist and are populated, then delegates to CMake's add_subdirectory to process the custom CMake wrapper.

The file also sets global flags for third-party code compilation:

• -w suppresses all compiler warnings (third-party code is not expected to be warning-clean).
• -ffunction-sections -fdata-sections enables linker garbage collection of unused code.
• UBSan is disabled for third-party code via -fno-sanitize=undefined when the undefined sanitizer is active.

Dependencies are added in a specific order to handle inter-dependencies. For instance, OpenSSL is added first so that all subsequent projects link against the vendored OpenSSL. The LLVM and protobuf builds are processed with dummy launchers disabled so that code generation tools (protoc, llvm-tblgen) can be built natively.

Usage

This function is used exclusively within contrib/CMakeLists.txt to register third-party libraries. Developers adding a new vendored dependency would add a new add_contrib invocation here.

Code Reference

Source Location

• Repository: ClickHouse
• File: contrib/CMakeLists.txt
• Lines: 14-39 (function definition), 47-252 (invocations)

Signature

function(add_contrib cmake_folder [base_folder1 ... base_folderN])

Import

# In contrib/CMakeLists.txt - add a new vendored library:
add_contrib (my-library-cmake my-library)

# When source and wrapper are in the same directory:
add_contrib (my-library)

# When multiple submodule directories must be verified:
add_contrib (aws-cmake
    aws
    aws-c-auth
    aws-c-cal
    aws-c-common
    aws-c-compression
    aws-c-event-stream
    aws-c-http
    aws-c-io
    aws-c-mqtt
    aws-c-s3
    aws-c-sdkutils
    aws-checksums
    aws-crt-cpp
    aws-cmake
)

I/O Contract

Inputs

Name	Type	Required	Description
cmake_folder	String (path)	Yes	Path to the directory containing the custom CMake wrapper CMakeLists.txt (relative to contrib/)
base_folder1..N	String (path)	No (defaults to cmake_folder)	One or more paths to submodule source directories that must exist and be non-empty for this dependency to be built

Outputs

Name	Type	Description
Static libraries	CMake targets	Compiled static library targets (typically aliased as ch_contrib::{name}) for linking by the main project. Examples: ch_contrib::openssl, ch_contrib::zlib, ch_contrib::protobuf
Header paths	CMake target properties	Include directories exported via target_include_directories for consuming targets

Usage Examples

Standard Library with Separate Wrapper

# Source in contrib/zlib-ng/, wrapper in contrib/zlib-ng-cmake/
add_contrib (zlib-ng-cmake zlib-ng)

Library with Single Directory

# Source and wrapper both in contrib/consistent-hashing/
add_contrib (consistent-hashing)

Complex Multi-Submodule Dependency

# AWS SDK: wrapper in contrib/aws-cmake/, sources across 14 submodule directories
add_contrib (aws-cmake
    aws
    aws-c-auth
    aws-c-cal
    aws-c-common
    aws-c-compression
    aws-c-event-stream
    aws-c-http
    aws-c-io
    aws-c-mqtt
    aws-c-s3
    aws-c-sdkutils
    aws-checksums
    aws-crt-cpp
    aws-cmake
)

Notable Dependencies in Build Order

# First: OpenSSL (all other projects use this version)
add_contrib (openssl-cmake openssl)
add_contrib (abseil-cpp-cmake abseil-cpp)
add_contrib (zlib-ng-cmake zlib-ng)
add_contrib (google-protobuf-cmake google-protobuf)
add_contrib (grpc-cmake grpc)
add_contrib (llvm-project-cmake llvm-project)
# ... then ~85 more libraries ...
add_contrib (jemalloc-cmake jemalloc)
add_contrib (boost-cmake boost)
add_contrib (arrow-cmake arrow)
add_contrib (rocksdb-cmake rocksdb)

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Third_Party_Dependency_Management

Requires Environment

• Environment:ClickHouse_ClickHouse_Linux_Build_Environment