Implementation:ClickHouse ClickHouse Clickhouse Program Add Macro

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

Overview

Concrete tool for compiling individual ClickHouse program components into per-mode static libraries provided by the clickhouse_program_add and clickhouse_program_add_library macros in programs/CMakeLists.txt.

Description

The clickhouse_program_add macro (lines 91-93) is a thin wrapper around clickhouse_program_add_library (lines 68-89). Together they:

1. Accept a component name (e.g., server, client, local).
2. Convert the name to uppercase and replace hyphens with underscores to form variable prefixes (e.g., keeper-client becomes KEEPER_CLIENT).
3. Propagate source files (CLICKHOUSE_{NAME}_SOURCES), link dependencies (CLICKHOUSE_{NAME}_LINK), and include paths (CLICKHOUSE_{NAME}_INCLUDE) to the parent scope using PARENT_SCOPE.
4. Create a static library target named clickhouse-{name}-lib from the sources.
5. Link private dependencies and set include directories if specified.

The macro is invoked indirectly: each program subdirectory (e.g., programs/server/) is added via add_subdirectory, and within that subdirectory the macro is called. Currently, the following program components are built:

• Core modes: server, client, local
• Keeper modes: keeper, keeper-converter, keeper-client, keeper-bench, keeper-data-dumper, keeper-utils
• Utilities: benchmark, compressor, disks, format, obfuscator, git-import, su, install
• Diagnostic tools: check-marks, checksum-for-compressed-block, extract-from-config, static-files-disk-uploader
• ZooKeeper tools: zookeeper-dump-tree, zookeeper-remove-by-list

After all subdirectories are processed, the main programs/CMakeLists.txt links each component library into the final clickhouse executable via the clickhouse_program_install function, which also creates symlinks for each tool name.

Usage

This macro is used exclusively within programs/ subdirectories to register new program components. To add a new ClickHouse mode, create a new subdirectory under programs/, define the appropriate CLICKHOUSE_{NAME}_SOURCES variable, and call clickhouse_program_add.

Code Reference

Source Location

• Repository: ClickHouse
• File: programs/CMakeLists.txt
• Lines: 68-89 (clickhouse_program_add_library), 91-93 (clickhouse_program_add)

Signature

macro(clickhouse_program_add_library name)
    string(TOUPPER ${name} name_uc)
    string(REPLACE "-" "_" name_uc ${name_uc})

    # Propagate variables to parent scope
    set(CLICKHOUSE_${name_uc}_SOURCES ${CLICKHOUSE_${name_uc}_SOURCES} PARENT_SCOPE)
    set(CLICKHOUSE_${name_uc}_LINK ${CLICKHOUSE_${name_uc}_LINK} PARENT_SCOPE)
    set(CLICKHOUSE_${name_uc}_INCLUDE ${CLICKHOUSE_${name_uc}_INCLUDE} PARENT_SCOPE)

    add_library(clickhouse-${name}-lib ${CLICKHOUSE_${name_uc}_SOURCES})

    set(_link ${CLICKHOUSE_${name_uc}_LINK})
    if(_link)
        target_link_libraries(clickhouse-${name}-lib PRIVATE ${CLICKHOUSE_${name_uc}_LINK})
    endif()

    target_include_directories(clickhouse-${name}-lib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
    set(_include ${CLICKHOUSE_${name_uc}_INCLUDE})
    if (_include)
        target_include_directories(clickhouse-${name}-lib ${CLICKHOUSE_${name_uc}_INCLUDE})
    endif()
endmacro()

macro(clickhouse_program_add name)
    clickhouse_program_add_library(${name})
endmacro()

Import

# In a program subdirectory (e.g., programs/my-tool/CMakeLists.txt):
set(CLICKHOUSE_MY_TOOL_SOURCES
    my_tool_main.cpp
    my_tool_helper.cpp
)
set(CLICKHOUSE_MY_TOOL_LINK
    dbms
    clickhouse_common_io
)
clickhouse_program_add(my-tool)

I/O Contract

Inputs

Name	Type	Required	Description
name	String	Yes	Program component name (e.g., server, client, local, keeper). Hyphens are allowed and will be converted to underscores for variable names.
CLICKHOUSE_{NAME_UC}_SOURCES	CMake variable (list)	Yes	List of source files to compile into the component library. Set in the component's subdirectory before calling the macro.
CLICKHOUSE_{NAME_UC}_LINK	CMake variable (list)	No	Additional link dependencies beyond the defaults. Typically includes dbms and component-specific libraries.
CLICKHOUSE_{NAME_UC}_INCLUDE	CMake variable (list)	No	Additional include directories for the component.

Outputs

Name	Type	Description
clickhouse-{name}-lib	Static library target	Per-component static library (e.g., clickhouse-server-lib, clickhouse-client-lib, clickhouse-local-lib, clickhouse-keeper-lib)
Propagated variables	CMake variables	CLICKHOUSE_{NAME_UC}_SOURCES, CLICKHOUSE_{NAME_UC}_LINK, CLICKHOUSE_{NAME_UC}_INCLUDE are propagated to parent scope for use by the linking stage

Usage Examples

Standard Program Component (Server)

# In programs/server/CMakeLists.txt:
set(CLICKHOUSE_SERVER_SOURCES
    Server.cpp
    HTTPHandler.cpp
    # ... other server sources ...
)
set(CLICKHOUSE_SERVER_LINK
    dbms
    clickhouse_common_io
)
clickhouse_program_add(server)

Linking Components into the Final Binary

# In programs/CMakeLists.txt:
clickhouse_program_install(clickhouse-server server)
clickhouse_program_install(clickhouse-client client chc)
clickhouse_program_install(clickhouse-local local chl ch)

Conditional Component (Keeper)

# Keeper is only built if NuRaft is available:
if (ENABLE_CLICKHOUSE_KEEPER)
    add_subdirectory (keeper)
endif()

# And linked into the binary conditionally:
if (ENABLE_CLICKHOUSE_KEEPER)
    clickhouse_target_link_split_lib(clickhouse keeper)
endif()

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Program_Component_Compilation

Requires Environment

• Environment:ClickHouse_ClickHouse_Linux_Build_Environment