Implementation:ClickHouse ClickHouse Clickhouse Split Debug Symbols

Knowledge Sources	ClickHouse
Domains	Packaging
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for separating debug symbols from compiled ClickHouse binaries provided by the CMake build system in cmake/split_debug_symbols.cmake.

Description

This CMake module defines two macros that handle debug symbol management during the ClickHouse build process:

• clickhouse_split_debug_symbols -- The primary macro that extracts DWARF debug information into a separate .debug file, strips the original binary of debug sections (following Debian stripping policy), and creates a GNU debug link between the stripped binary and its debug file. It registers a POST_BUILD custom command on the specified CMake target so that splitting happens automatically after compilation.

• clickhouse_make_empty_debug_info_for_nfpm -- A companion macro that creates empty placeholder .debug files. This is needed when building nfpm packages in configurations where full debug information is not available, because nfpm requires all files referenced in its YAML specification to exist on disk at packaging time.

Both macros also register install commands so the outputs are included in CMake's install targets.

Usage

These macros are used in the ClickHouse CMake build configuration when building release packages. They are invoked from the CMakeLists.txt that defines the main clickhouse binary target. Use clickhouse_split_debug_symbols when building with full debug information, and clickhouse_make_empty_debug_info_for_nfpm when you need a structurally valid package without actual debug data.

Code Reference

Source Location

• Repository: ClickHouse
• File: cmake/split_debug_symbols.cmake (lines 3--37 for clickhouse_split_debug_symbols, lines 40--62 for clickhouse_make_empty_debug_info_for_nfpm)

Signature

clickhouse_split_debug_symbols

macro(clickhouse_split_debug_symbols)
   set(oneValueArgs TARGET DESTINATION_DIR BINARY_PATH)
   cmake_parse_arguments(STRIP "" "${oneValueArgs}" "" ${ARGN})

   # Validation: TARGET, BINARY_PATH, and DESTINATION_DIR are all required

   add_custom_command(TARGET ${STRIP_TARGET} POST_BUILD
       COMMAND mkdir -p "${STRIP_DESTINATION_DIR}/lib/debug/bin"
       COMMAND mkdir -p "${STRIP_DESTINATION_DIR}/bin"
       # Extract debug info into separate file:
       COMMAND "${OBJCOPY_PATH}" --only-keep-debug
               "${STRIP_BINARY_PATH}"
               "${STRIP_DESTINATION_DIR}/lib/debug/bin/${STRIP_TARGET}.debug"
       COMMAND chmod 0644
               "${STRIP_DESTINATION_DIR}/lib/debug/bin/${STRIP_TARGET}.debug"
       # Strip binary (removes .debug, .comment, .note sections per Debian policy):
       COMMAND "${STRIP_PATH}" --strip-debug
               --remove-section=.comment --remove-section=.note
               "${STRIP_BINARY_PATH}"
               -o "${STRIP_DESTINATION_DIR}/bin/${STRIP_TARGET}"
       # Link stripped binary to its debug file:
       COMMAND "${OBJCOPY_PATH}" --add-gnu-debuglink
               "${STRIP_DESTINATION_DIR}/lib/debug/bin/${STRIP_TARGET}.debug"
               "${STRIP_DESTINATION_DIR}/bin/${STRIP_TARGET}"
   )

   install(PROGRAMS ${STRIP_DESTINATION_DIR}/bin/${STRIP_TARGET}
           DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT clickhouse)
   install(FILES ${STRIP_DESTINATION_DIR}/lib/debug/bin/${STRIP_TARGET}.debug
           DESTINATION ${DEBUG_PATH} COMPONENT clickhouse)
endmacro()

clickhouse_make_empty_debug_info_for_nfpm

macro(clickhouse_make_empty_debug_info_for_nfpm)
   set(oneValueArgs TARGET BINARY DESTINATION_DIR)
   cmake_parse_arguments(EMPTY_DEBUG "" "${oneValueArgs}" "" ${ARGN})

   # Validation: TARGET, BINARY, and DESTINATION_DIR are all required

   add_custom_command(TARGET ${EMPTY_DEBUG_TARGET} POST_BUILD
       COMMAND mkdir -p "${EMPTY_DEBUG_DESTINATION_DIR}/lib/debug"
       COMMAND touch "${EMPTY_DEBUG_DESTINATION_DIR}/lib/debug/${EMPTY_DEBUG_BINARY}.debug"
   )

   install(FILES "${EMPTY_DEBUG_DESTINATION_DIR}/lib/debug/${EMPTY_DEBUG_BINARY}.debug"
           DESTINATION ${DEBUG_PATH} COMPONENT clickhouse)
endmacro()

I/O Contract

Inputs

clickhouse_split_debug_symbols

Name	Type	Required	Description
TARGET	CMake target name	Yes	The CMake target to attach the post-build command to (e.g., clickhouse)
DESTINATION_DIR	Filesystem path	Yes	Output directory where stripped binary and debug file will be placed
BINARY_PATH	Filesystem path	Yes	Path to the compiled binary containing debug symbols
${OBJCOPY_PATH}	External tool path	Yes (environment)	Path to the objcopy binary from GNU binutils, used for debug extraction and linking
${STRIP_PATH}	External tool path	Yes (environment)	Path to the strip binary from GNU binutils, used for stripping debug sections

clickhouse_make_empty_debug_info_for_nfpm

Name	Type	Required	Description
TARGET	CMake target name	Yes	The CMake target to attach the post-build command to
BINARY	String	Yes	Name of the binary for which to create the placeholder debug file
DESTINATION_DIR	Filesystem path	Yes	Output directory where the empty debug file will be created

Outputs

clickhouse_split_debug_symbols

Name	Type	Description
${DESTINATION_DIR}/bin/${TARGET}	Stripped ELF binary	The binary with debug sections removed and .gnu_debuglink section added, suitable for distribution
${DESTINATION_DIR}/lib/debug/bin/${TARGET}.debug	Debug info file	Separate file containing DWARF debug sections, with permissions set to 0644

clickhouse_make_empty_debug_info_for_nfpm

Name	Type	Description
${DESTINATION_DIR}/lib/debug/${BINARY}.debug	Empty file	Zero-byte placeholder file satisfying nfpm's requirement that all package contents exist at build time

Usage Examples

Splitting debug symbols from the ClickHouse binary

clickhouse_split_debug_symbols(
    TARGET clickhouse
    DESTINATION_DIR "${CMAKE_CURRENT_BINARY_DIR}/stripped"
    BINARY_PATH "$<TARGET_FILE:clickhouse>"
)

This produces:

• stripped/bin/clickhouse -- the stripped binary
• stripped/lib/debug/bin/clickhouse.debug -- the debug symbols

Creating an empty debug placeholder for nfpm

clickhouse_make_empty_debug_info_for_nfpm(
    TARGET clickhouse
    BINARY clickhouse
    DESTINATION_DIR "${CMAKE_CURRENT_BINARY_DIR}/stripped"
)

This produces:

• stripped/lib/debug/clickhouse.debug -- a zero-byte file

Verifying the debug link after splitting

# Check that the stripped binary has a debug link:
objdump -s -j .gnu_debuglink stripped/bin/clickhouse

# Verify the debug file contains DWARF info:
readelf -S stripped/lib/debug/bin/clickhouse.debug | grep debug

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Debug_Symbol_Splitting