Implementation:ClickHouse ClickHouse Nfpm Debug Symbols Package

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

Overview

Concrete tool for generating the clickhouse-common-static-dbg and clickhouse-keeper-dbg DEB and RPM packages provided by the nfpm external packaging tool and their YAML configurations.

Description

The debug symbol packages distribute the .debug files produced by the clickhouse_split_debug_symbols CMake macro (or the empty placeholders from clickhouse_make_empty_debug_info_for_nfpm) as optional, separately installable packages.

Two debug packages are defined:

• clickhouse-common-static-dbg -- Contains debug symbols for the main clickhouse binary. Declares replaces and conflicts with the legacy clickhouse-common-dbg package for smooth upgrades.
• clickhouse-keeper-dbg -- Contains debug symbols for the standalone clickhouse-keeper binary.

Both packages install their .debug files into the GNU standard debug directory at /usr/lib/debug/usr/bin/, where GDB and other debuggers automatically discover them via the .gnu_debuglink section in the stripped binary.

Usage

Use these package configurations when building debug symbol packages for ClickHouse distribution. The .debug files must be staged in the root/ subdirectory before invoking nfpm. If full debug symbols are not available, use the clickhouse_make_empty_debug_info_for_nfpm CMake macro to create placeholder files.

Code Reference

Source Location

• Repository: ClickHouse
• Files:
  • packages/clickhouse-common-static-dbg.yaml (lines 1--41)
  • packages/clickhouse-keeper-dbg.yaml (lines 1--36)

Signature

clickhouse-common-static-dbg.yaml

name: "clickhouse-common-static-dbg"
description: |
  debugging symbols for clickhouse-common-static
    This package contains the debugging symbols for clickhouse-common.

arch: "${DEB_ARCH}"
platform: "linux"
version: "${CLICKHOUSE_VERSION_STRING}"
vendor: "ClickHouse Inc."
homepage: "https://clickhouse.com"
license: "Apache"
section: "database"
priority: "optional"
maintainer: "ClickHouse Dev Team <packages+linux@clickhouse.com>"

replaces:
- clickhouse-common-dbg
conflicts:
- clickhouse-common-dbg

contents:
- src: root/usr/lib/debug/usr/bin/clickhouse.debug
  dst: /usr/lib/debug/usr/bin/clickhouse.debug
- src: ../AUTHORS
  dst: /usr/share/doc/clickhouse-common-static-dbg/AUTHORS
- src: ../CHANGELOG.md
  dst: /usr/share/doc/clickhouse-common-static-dbg/CHANGELOG.md
- src: ../LICENSE
  dst: /usr/share/doc/clickhouse-common-static-dbg/LICENSE
- src: ../README.md
  dst: /usr/share/doc/clickhouse-common-static-dbg/README.md

clickhouse-keeper-dbg.yaml

name: "clickhouse-keeper-dbg"
description: |
  debugging symbols for clickhouse-keeper
    This package contains the debugging symbols for clickhouse-keeper.

arch: "${DEB_ARCH}"
platform: "linux"
version: "${CLICKHOUSE_VERSION_STRING}"
vendor: "ClickHouse Inc."
homepage: "https://clickhouse.com"
license: "Apache"
section: "database"
priority: "optional"
maintainer: "ClickHouse Dev Team <packages+linux@clickhouse.com>"

contents:
- src: root/usr/lib/debug/usr/bin/clickhouse-keeper.debug
  dst: /usr/lib/debug/usr/bin/clickhouse-keeper.debug
- src: ../AUTHORS
  dst: /usr/share/doc/clickhouse-keeper-dbg/AUTHORS
- src: ../CHANGELOG.md
  dst: /usr/share/doc/clickhouse-keeper-dbg/CHANGELOG.md
- src: ../LICENSE
  dst: /usr/share/doc/clickhouse-keeper-dbg/LICENSE
- src: ../README.md
  dst: /usr/share/doc/clickhouse-keeper-dbg/README.md

API

# Generate clickhouse-common-static-dbg DEB:
nfpm package -p deb -f clickhouse-common-static-dbg.yaml

# Generate clickhouse-common-static-dbg RPM:
nfpm package -p rpm -f clickhouse-common-static-dbg.yaml

# Generate clickhouse-keeper-dbg DEB:
nfpm package -p deb -f clickhouse-keeper-dbg.yaml

# Generate clickhouse-keeper-dbg RPM:
nfpm package -p rpm -f clickhouse-keeper-dbg.yaml

I/O Contract

Inputs

clickhouse-common-static-dbg

Name	Type	Required	Description
root/usr/lib/debug/usr/bin/clickhouse.debug	Debug info file	Yes	DWARF debug symbols for the clickhouse binary, produced by clickhouse_split_debug_symbols or an empty placeholder from clickhouse_make_empty_debug_info_for_nfpm
../AUTHORS	Text file	Yes	Project authors list
../CHANGELOG.md	Text file	Yes	Project changelog
../LICENSE	Text file	Yes	Apache 2.0 license text
../README.md	Text file	Yes	Project readme
${CLICKHOUSE_VERSION_STRING}	Environment variable	Yes	Version string for the package
${DEB_ARCH}	Environment variable	Yes	Target architecture

clickhouse-keeper-dbg

Name	Type	Required	Description
root/usr/lib/debug/usr/bin/clickhouse-keeper.debug	Debug info file	Yes	DWARF debug symbols for the clickhouse-keeper binary, or an empty placeholder
../AUTHORS	Text file	Yes	Project authors list
../CHANGELOG.md	Text file	Yes	Project changelog
../LICENSE	Text file	Yes	Apache 2.0 license text
../README.md	Text file	Yes	Project readme
${CLICKHOUSE_VERSION_STRING}	Environment variable	Yes	Version string for the package
${DEB_ARCH}	Environment variable	Yes	Target architecture

Outputs

Name	Type	Description
clickhouse-common-static-dbg_${VERSION}_${ARCH}.deb	Debian package	Debug symbols for the main ClickHouse binary
clickhouse-common-static-dbg-${VERSION}.${ARCH}.rpm	RPM package	Debug symbols for the main ClickHouse binary (RPM format)
clickhouse-keeper-dbg_${VERSION}_${ARCH}.deb	Debian package	Debug symbols for the Keeper binary
clickhouse-keeper-dbg-${VERSION}.${ARCH}.rpm	RPM package	Debug symbols for the Keeper binary (RPM format)

Installed File Layout

clickhouse-common-static-dbg

/usr/lib/debug/usr/bin/clickhouse.debug                        # Debug symbols
/usr/share/doc/clickhouse-common-static-dbg/AUTHORS
/usr/share/doc/clickhouse-common-static-dbg/CHANGELOG.md
/usr/share/doc/clickhouse-common-static-dbg/LICENSE
/usr/share/doc/clickhouse-common-static-dbg/README.md

clickhouse-keeper-dbg

/usr/lib/debug/usr/bin/clickhouse-keeper.debug                 # Debug symbols
/usr/share/doc/clickhouse-keeper-dbg/AUTHORS
/usr/share/doc/clickhouse-keeper-dbg/CHANGELOG.md
/usr/share/doc/clickhouse-keeper-dbg/LICENSE
/usr/share/doc/clickhouse-keeper-dbg/README.md

Usage Examples

Building debug packages with real debug symbols

export CLICKHOUSE_VERSION_STRING="24.3.1.1"
export DEB_ARCH="amd64"

# Stage the debug file (produced by clickhouse_split_debug_symbols):
mkdir -p packages/root/usr/lib/debug/usr/bin
cp build/stripped/lib/debug/bin/clickhouse.debug \
   packages/root/usr/lib/debug/usr/bin/clickhouse.debug

# Generate the package:
cd packages
nfpm package -p deb -f clickhouse-common-static-dbg.yaml

Using debug symbols to analyze a core dump

# Install the debug package on the target system:
dpkg -i clickhouse-common-static-dbg_24.3.1.1_amd64.deb

# GDB automatically finds the debug symbols via gnu_debuglink:
gdb /usr/bin/clickhouse /path/to/core.dump

# Verify debug symbols are loaded:
(gdb) info shared

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Debug_Package_Configuration