本文档记录了在 openEuler 24.03 (LTS-SP1) aarch64 操作系统、鲲鹏920 处理器上，源码编译 ClickHouse v26.3.17.4-lts 的完整过程，包含从环境准备、工具链自编译、指令集适配到最终 RPM 打包的每一步。

验证环境: Linux 6.6.0-140.0.0.134.oe2403sp1.aarch64, 16 核, 47 GiB 内存

---

1. 环境

项目	说明
操作系统	openEuler 24.03 (LTS-SP1) aarch64
内核版本	Linux 6.6.0-140.0.0.134.oe2403sp1.aarch64
处理器	鲲鹏920 (ARMv8.2-a), 16 核
内存	47 GiB
磁盘	69 GiB (系统盘), 编译需约 35 GiB 剩余空间，建议 100 GiB 以上
工具链	Clang 21 (自编译) + GCC 12 (系统自带)
构建工具	cmake + ninja 1.11.1 + ccache 4.8.3

---

2. 依赖包安装

yum install cmake gcc gcc-c++ make automake -y
yum install python3 ccache ninja-build nasm yasm gawk -y
yum install numactl -y
yum install rust -y
yum install qt-devel -y
yum install libhugetlbfs-devel -y
yum install cargo -y

说明: ninja-build 提供 ninja 构建工具，ccache 用于编译缓存加速，rust/cargo 用于 ClickHouse 中 Rust 组件的编译。

---

3. 源码下载

git clone --recurse-submodules -b v26.3.17.4-lts https://github.com/ClickHouse/ClickHouse.git

# 备份源码（建议）
tar -zcf ClickHouse-v26.3.17.4-lts.tar.gz ClickHouse
cd ClickHouse

--recurse-submodules 确保所有子模块一并拉取。备份文件可在后续操作出错时快速恢复。

---

4. 编译 LLVM 和 Clang

ClickHouse 26.3 依赖较新的 Clang 工具链，建议自编译 LLVM + Clang 21。

4.1 编译 LLVM

cd ClickHouse/llvm
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j 8 && make -j 8 install

4.2 编译 Clang（附带相关工具）

cd ../../clang
mkdir build && cd build
cmake -G "Unix Makefiles" \
  -DCMAKE_BUILD_TYPE=Release \
  ../../llvm \
  -DLLVM_ENABLE_PROJECTS="clang;compiler-rt;clang-tools-extra;openmp;lldb;lld"
make -j 8 && make install

# 验证
clang --version

LLVM_ENABLE_PROJECTS 启用了 clang、compiler-rt（运行时库）、clang-tools-extra（额外工具）、openmp（并行库）、lldb（调试器）、lld（链接器）。其中 lld 和 compiler-rt 对 ClickHouse 编译至关重要。

4.3 为 Clang 关联 GCC 运行时库

Clang 需要 GCC 的运行时库和 crt 对象文件来完成链接。在 aarch64 平台上执行：

cd /usr/local/lib/clang/21/lib/aarch64-unknown-linux-gnu/

# 建立符号链接，将 GCC 的运行时对象和库提供给 Clang 使用
ln -s /usr/lib/gcc/aarch64-openEuler-linux/12/crtendS.o .
ln -s /usr/lib64/libstdc++.so.6 /usr/lib64/libstdc++.so
ln -s /usr/lib/gcc/aarch64-openEuler-linux/12/crtbeginS.o .
ln -s /usr/lib/gcc/aarch64-openEuler-linux/12/libgcc.a .
ln -s /usr/lib/gcc/aarch64-openEuler-linux/12/libgcc_s.so .

注意: 路径中的 21 和 aarch64-openEuler-linux/12 需要根据实际 Clang 版本和 GCC 版本进行调整。如果不做此步骤，链接阶段会报缺少 crtbeginS.o、crtendS.o 等文件的错误。

---

5. 鲲鹏920 指令集适配

鲲鹏920 处理器基于 ARMv8.2-a 架构，不支持 ssbs、rcpc、bf16 等扩展指令集，需要降级适配。

5.1 修改 CPU 特性标志

文件: cmake/cpu_features.cmake（约第 52 行）

原值：

set (COMPILER_FLAGS "${COMPILER_FLAGS} -march=armv8.2-a+simd+crypto+dotprod+ssbs+rcpc+bf16")

修改为：

set (COMPILER_FLAGS "${COMPILER_FLAGS} -march=armv8.2-a+simd+crypto+dotprod")

文件: cmake/cpu_features.cmake（约第 54 行）

原值：

list(APPEND RUSTFLAGS_CPU "-C" "target_feature=+dotprod+ssbs+rcpc+bf16")

修改为：

list(APPEND RUSTFLAGS_CPU "-C" "target_feature=+dotprod")

5.2 注释 bfloat16 类型警告

文件: contrib/SimSIMD/include/simsimd/types.h（约第 365 行）

原值：

#warning "Unknown compiler or architecture for bfloat16."

修改为：

//#warning "Unknown compiler or architecture for bfloat16."

鲲鹏920 不支持 bfloat16，但该警告只是提示信息，不影响编译，直接注释掉即可。

---

6. 编译 ClickHouse

6.1 配置编译参数

current_directory=$(pwd)
build_dir="${current_directory}/ci/tmp/build"
temp_dir="${current_directory}/ci/tmp"
rm -rf "$build_dir" && mkdir -p "$build_dir"

cmake --debug-trycompile \
  -DPARALLEL_COMPILE_JOBS=16 \
  -DDISABLE_HERMETIC_BUILD=ON \
  -DBUILD_STRIPPED_BINARY=1 \
  -DENABLE_CLICKHOUSE_SELF_EXTRACTING=1 \
  -DENABLE_BUILD_PROFILING=OFF \
  -DPARALLEL_LINK_JOBS=4 \
  -DENABLE_THINLTO=ON \
  -DENABLE_TESTS=OFF \
  -DENABLE_RUST=OFF \
  -DCMAKE_VERBOSE_MAKEFILE=1 \
  -LA \
  -DCMAKE_BUILD_TYPE=Release \
  -DENABLE_UTILS=0 \
  -DENABLE_CHECK_HEAVY_BUILDS=1 \
  -DCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DCMAKE_INSTALL_SYSCONFDIR=/etc \
  -DCMAKE_INSTALL_LOCALSTATEDIR=/var \
  -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON \
  -DSPLIT_DEBUG_SYMBOLS=ON \
  -DBUILD_STANDALONE_KEEPER=1 \
  -DCMAKE_TOOLCHAIN_FILE=${current_directory}/cmake/linux/toolchain-aarch64.cmake \
  -S . -B "$build_dir"

关键参数说明：

参数	作用
PARALLEL_COMPILE_JOBS=16	并行编译任务数，根据 CPU 核数调整
PARALLEL_LINK_JOBS=4	并行链接任务数，链接消耗内存大，不宜过高
DISABLE_HERMETIC_BUILD=ON	禁用封闭构建，使用系统库而非下载的 sysroot
ENABLE_THINLTO=ON	开启 ThinLTO 优化，减小二进制体积
BUILD_STRIPPED_BINARY=1	生成剥离符号的二进制
SPLIT_DEBUG_SYMBOLS=ON	分离调试符号到独立文件
ENABLE_TESTS=OFF	关闭测试编译，加速构建
ENABLE_RUST=OFF	关闭 Rust 组件编译（本文档的环境 Rust 已安装但可选择性关闭以加速）
BUILD_STANDALONE_KEEPER=1	编译独立的 clickhouse-keeper 组件
ENABLE_CLICKHOUSE_SELF_EXTRACTING=1	支持自解压安装包

6.2 执行编译

ninja -C "$build_dir"

编译时长取决于机器性能。当前环境 (16核, 47GiB 内存) 完整编译约需 4-6 小时。如需加速，可适当增加 PARALLEL_COMPILE_JOBS（不超过 CPU 核数的 1.5 倍）并使用 ccache 加速后续增量编译。

6.3 安装

ninja -C "$build_dir" programs/install

---

7. RPM 打包

使用 nfpm 工具将编译产物打包为 RPM。

7.1 安装 nfpm

# 下载 nfpm 的 aarch64 RPM 包并安装
# 可从 https://github.com/goreleaser/nfpm/releases 获取
yum install -y ~/nfpm-2.41.3-1.aarch64.rpm

7.2 配置打包环境

cd packages/
ln -s / root

创建 / 的符号链接 root，供打包脚本使用。

7.3 移除 debug 包（可选）

mv clickhouse-keeper-dbg.yaml ~/
mv clickhouse-common-static-dbg.yaml ~/

如果不需要调试符号包，可以将对应的 YAML 配置文件移走，打包脚本会自动跳过。

7.4 执行打包

OUTPUT_DIR="$temp_dir" \
  BUILD_TYPE=release \
  VERSION_STRING=26.3.17.4 \
  DEB_ARCH=aarch64 \
  ./build --rpm

打包完成后，RPM 包会输出到 OUTPUT_DIR 指定的目录中。

---

8. 常见问题

8.1 CMake 报错 default_libs.cmake: build_clang_builtin

原因: Clang 的 builtins 库缺失，通常是 Clang 未正确安装或 GCC 运行时库链接不完整。

解决: 确认步骤 4.3 中的符号链接已正确创建，或检查 compiler-rt 是否正确编译安装。

8.2 链接时报错 cannot find crtbeginS.o

原因: Clang 需要 GCC 的 crt 对象文件来链接可执行文件。

解决: 执行步骤 4.3 中的符号链接操作，确保路径匹配系统 GCC 版本。

8.3 编译报错 target feature 'bf16' is not supported

原因: 鲲鹏920 不支持 bf16 指令集，但编译参数中启用了该特性。

解决: 按步骤 5.1 修改 cpu_features.cmake，去除 +bf16 标志。

8.4 内存不足导致编译失败

原因: 链接阶段（特别是 ThinLTO 开启时）消耗大量内存。

解决:

• 降低 PARALLEL_LINK_JOBS 的值（如改为 2 或 1）
• 增加 swap 空间
• 关闭 ENABLE_THINLTO（但会增加二进制体积）

---

9. 验证

编译完成后，可以通过以下方式验证：

# 检查 clickhouse 二进制
$build_dir/programs/clickhouse --version

# 检查 keeper 二进制
$build_dir/programs/clickhouse-keeper --version

# 查看 RPM 包
ls -lh "$temp_dir"/*.rpm