1. 一条 cmake 命令救不了场:交叉编译到底卡在哪
一个很常见的场面:一套 C/C++ 源码在 x86 构建机上编得好好的,拷到 ARM64 板子上执行,报 cannot execute binary file;改在板子上原地编,又卡在内存和编译时间上。两次都栽在同一个地方——代码开发工具链里少配了一环:交叉编译。要解决的不是某个库怎么调,而是用 CMake 生成构建描述、Ninja 执行构建、aarch64 交叉编译器产出机器码,让构建机上能稳定产出 ARM64 可执行文件。适合手里有一套 C/C++ 源码、要把产物搬到板子上、又不想在板子上装整套编译环境的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具选型:CMake、Ninja 与交叉编译器各管一段
2.1 三个角色别混:配置器、执行器、翻译器
CMake 干两件事:探测主机和目标环境,把工程里的构建逻辑翻译成某个构建器能读的文件。它本身一个 .c 都不编。Ninja 也只干一件事:读 CMake 生成的 build.ninja,按依赖图尽快把一条条命令行执行掉。真正把源码变成 aarch64 机器码的,是交叉编译器。
职责分清,出问题才知道该看哪一层:配置阶段报错,去看 CMake 的探测结果和缓存;构建阶段报错,去看 build.ninja 里那条具体命令行到底拼成了什么样。混在一起,就容易变成改参数碰运气。
build/CMakeCache.txt 是这套流程里的黑匣子。配置过一次之后,编译器路径、编译选项、功能开关全被写进去,后面再给 -D 有时不生效,就是因为缓存里的旧值还压着。
2.2 为什么用 Ninja,为什么不在板子上直接编
CMake 如果生成 Makefile,会顺带塞进大量隐式规则和中间目标,一个文件出错,屏幕上滚过的是一堆自动生成的规则;Ninja 的构建文件是「一个目标一条命令行」的平铺结构,报错时能直接定位到挂掉的那一行。另外 Ninja 不靠隐式推导,所有相关性都由 CMake 一次性写死,排查时没有第二处需要怀疑的地方。
不在板子上直接编,理由更实际:板子的 CPU 和内存本来就紧张,编译工具链在它上面是实打实的负担;更麻烦的是板子上的系统往往是裁剪过的,缺头文件、缺完整的 libc 开发包,编到一半报某个系统头找不到,你会花很久才意识到不是源码的问题。交叉编译把这些麻烦全留在构建机上,板子只负责跑。
2.3 交叉编译器必须显式指定
CMake 默认调 cc / gcc,那是主机的编译器,产出的必然是同架构产物。-DCMAKE_C_COMPILER 和 -DCMAKE_CXX_COMPILER 是唯一能把人换掉的开关。
不要在 CMakeLists.txt 里写 set(CMAKE_C_COMPILER ...)。那是硬编码,换一台构建机或者换一套工具链就得改源码,而且会坑到后面接手的人。这两个值应该从命令行或者 toolchain 文件进来,和源码保持分离。
还有一个前提常被忽略:编译器本身得在 PATH 里,名字得对得上。C++ 源码还要确认 g++ 那一份也装了,只装 C 编译器,配置阶段会在 CXX 探测那一步失败。
2.4 开工前的三项自检
bash复制# 1) 配置器与构建器是否就位
cmake --version
ninja --version
# 2) 交叉编译器在不在 PATH 里,C 和 C++ 两份都要有
which aarch64-linux-gnu-gcc
which aarch64-linux-gnu-g++
# 3) 它默认面向的目标三元组是什么,这一步最容易被跳过
aarch64-linux-gnu-gcc -dumpmachine
-dumpmachine 输出 aarch64-linux-gnu 才算对。如果输出的是 x86_64 相关的前缀,说明 PATH 里那个 gcc 只是主机编译器改了个名,或者装的根本是另一个包。这一条比看 --version 靠谱:版本号只说明它装上了,三元组才说明它面向谁。
两个 which 都必须有输出。少一个,后面 CMake 会在探测阶段就直接失败,而错误信息通常只说「找不到编译器」,不会告诉你少装的是 C++ 那一份。
3. 交叉编译环境落地:从装编译器到 toolchain 文件
3.1 先备好交叉编译器
Ubuntu 22.04 这类构建机上,常见做法是用包管理器装:
bash复制# 构建机是 x86_64,装的是面向 aarch64 的 GCC 交叉工具链
sudo apt update
sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
C 和 C++ 是两个包,分别装。只装前者,配置阶段会在 CXX 探测那里报找不到编译器,而错误往往出现得很晚,容易误以为是源码问题。装完不需要重启,但已经开着的 shell 要确认 /usr/bin 在 PATH 里,否则 which 依然查不到。
装完立刻回到上一章的三项自检,尤其是 -dumpmachine。这一步花十秒,能省掉后面半小时的怀疑。
3.2 系统名:交叉编译和本机编译的分水岭
CMake 判断「编译机是否等于运行机」,靠的是 CMAKE_SYSTEM_NAME。不设它,CMake 会认为你在本机编译,于是按主机路径去找依赖库;即使编译器已经换成 aarch64 的,链接阶段照样可能拽进主机上的库,最后在板子上跑起来报错。
设成 Linux 之后,CMake 走交叉编译分支,查找库和头文件的行为随之切换。这一步不是可有可无的修饰,它决定的是整套查找策略,不是单个变量。
顺带一个习惯:构建目录一定要独立,不要在源码目录里直接 cmake .。生成的 CMakeCache.txt、build.ninja 和中间产物会污染源码树,清理时很麻烦,也容易误提交。
3.3 toolchain 文件:把那几个 -D 固化下来
cmake复制# toolchain-aarch64.cmake
# 目标系统:决定 CMake 走交叉编译分支,而不是按主机环境查找依赖
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
# 目标三元组对应的交叉编译器,必须是 PATH 里真实存在的可执行文件
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
# 不要在文件里再写死主机上的库搜索路径,交叉编译时那是最常见的污染源
这四项就是命令行里那几个 -D 的等价写法。CMAKE_SYSTEM_NAME 影响整套查找策略,CMAKE_SYSTEM_PROCESSOR 影响的是库搜索目录的命名规则,两个都要给。
用文件的好处是构建脚本里只出现一个 -DCMAKE_TOOLCHAIN_FILE=toolchain-aarch64.cmake,不容易漏项。代价是多一个文件要维护,改动时得记得它在哪。
注意:命令行 -D 和 toolchain 文件不要同时写同一组变量。两处都写,排查时你看不出到底哪个生效了,出问题只能靠删缓存重来。
3.4 一次性命令还是固化文件,看场景挑
| 场景 | 推荐写法 | 理由 |
|---|---|---|
| 单人排查、复现别人的构建 | 命令行 -D 全量给 |
一眼看全所有参数,便于贴给别人 |
| 团队协作、持续集成 | toolchain 文件 + 构建脚本 | 参数只有一份,不容易漏 |
| 临时换一个编译器版本 | 命令行覆盖 | 改完即用,不必动文件 |
| 一套源码要出多个架构 | 每架构一个 toolchain 文件 | 互不干扰,切换只换文件名 |
不管走哪种,最终都要落到「一条命令能重跑」上。构建这类事,能重跑比能跑通更重要——能跑通只说明这次运气好,能重跑才说明参数配对了。
4. 参数逐个过一遍:一次能跑通的 CMake 配置与构建
4.1 完整配置命令
bash复制mkdir build && cd build
cmake -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/opt/codec-custom \
-DUNIX=ON \
-DBUILD_SHARED_LIBS=OFF \
-DENABLE_LZMA2=ON \
-DENABLE_AES=ON \
-DENABLE_THREADS=ON \
-DENABLE_ARM64=ON \
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
..
.. 指向源码目录,整条命令只做配置,不编译。-G Ninja 决定生成 build.ninja 而不是 Makefile。这条命令本身可以反复重跑,但没必要——真正每次都该重跑的是下一章的构建命令。
下面几节按参数分组解释。同一个参数写错和漏写,表现完全不同,分开看更清楚。
4.2 平台与产物形态:UNIX 和 BUILD_SHARED_LIBS
-DUNIX=ON 强制启用 POSIX 兼容模式。这套源码里有按平台条件编译的代码,不给这个开关,配置阶段就会按非 POSIX 分支走,去链接主机上根本不存在的接口。交叉编译到 Linux,这个开关没有「看情况」的余地,漏了就是构建阶段的报错。
-DBUILD_SHARED_LIBS=OFF 控制要不要生成动态库。这套源码并不对外提供动态库接口,设成 ON 只会生成一批没人链接的 .so,顺带把运行时依赖关系带进设备——到了板子上就得配库搜索路径,凭空多一层出错的地方。静态链接,一个二进制拷过去就能跑。
这两项合起来决定的是「产物长什么样」,比优化参数重要得多。产物形态错了,跑得再快也没用。
4.3 功能开关:LZMA2、AES、THREADS
三个 ENABLE_* 决定编进去哪些能力。ENABLE_LZMA2 是压缩算法本体,关掉等于白编。ENABLE_AES 是加密包支持,如果你的设备只处理不加密的数据,关掉能少一块代码,镜像也小一点。
ENABLE_THREADS 决定多线程解压是否可用。关掉不会编译失败,但解压会退回单线程。目标板是单核、或者你打算限制它的 CPU 占用,这个开关要单独评估,别默认全开。
| 参数 | 建议值 | 作用 | 什么时候改 |
|---|---|---|---|
CMAKE_BUILD_TYPE |
Release |
决定优化级别与调试符号 | 需要定位崩溃时临时换 RelWithDebInfo |
CMAKE_INSTALL_PREFIX |
有写权限的目录 | 安装产物落到哪 | 打包流程有固定目录时按流程改 |
UNIX |
ON |
走 POSIX 分支 | 交叉编译到 Linux 时不要关 |
BUILD_SHARED_LIBS |
OFF |
是否生成动态库 | 需要给别的程序链接时才考虑打开 |
ENABLE_ARM64 |
ON |
ARM64 专用优化 | 工具链不支持时关掉,见下一章 |
4.4 ARM64 优化与编译器指定的组合
-DENABLE_ARM64=ON 启用 ARM64 专用优化,包括用 NEON 向量指令加速解码路径。代价是它会给编译器追加类似 -march=armv8-a+crypto+simd 的目标选项——工具链不认这个组合,编译就直接失败,而且报错位置离这个开关很远,不看配置命令很难联想到它。
-DCMAKE_C_COMPILER 和 -DCMAKE_CXX_COMPILER 是整条命令里最关键的两个值。生成 ARM64 二进制就靠它们,前面所有功能开关都只是决定「编进去什么」,这两个决定「编成什么架构」。
有一点要留意:这两个变量一旦被写进 CMakeCache.txt,后面改就不生效了。换编译器必须删缓存重来,具体做法在下一章第一条里。
4.5 构建与安装
bash复制# 执行构建:Ninja 按 build.ninja 的依赖图并行执行
cmake --build build -j"$(nproc)"
# 安装:按 CMAKE_INSTALL_PREFIX 把产物落到目标目录
cmake --install build
用 cmake --build 而不是直接敲 ninja,好处是将来构建器换了,脚本不用改。-j"$(nproc)" 把并行度设成构建机核数;构建机同时在跑别的任务时降到一半更稳,否则容易在内存上被打爆,表现是编译器进程被系统直接杀掉,日志里只有一句被中断。
cmake --install 会往 /opt 下面写,普通用户没有权限,这一步失败是权限问题,不是构建问题。别看到报错就去翻编译日志,先看错误里说的是哪个目录。
5. 代码开发工具链避坑:五类构建失败的现象、原因与解法
5.1 改了编译器,产物还是 x86
现象:命令里明明给了 aarch64-linux-gnu-gcc,编完用 file 一看还是 x86-64。
原因:build 目录里已经有上一次配置生成的 CMakeCache.txt,编译器路径被缓存了。CMake 对编译器这类变量的处理是「一旦确定就不再改」,新的 -D 盖不住它。
解决:删掉整个 build 目录重新配置,只删 CMakeFiles 不够,缓存还在。
bash复制cd ..
rm -rf build && mkdir build && cd build
# 重新跑完整配置命令,别只补那一个 -D
5.2 ENABLE_ARM64 打开后编译失败
现象:编译到解码相关文件时报 unrecognized command-line option '-march=armv8-a+crypto+simd',或者 NEON intrinsic 相关的报错。
原因:这个开关要求交叉工具链支持该 -march 组合。老版本工具链、或者被裁剪过的工具链,不认这个组合。
解决:先确认工具链能力,再决定是补工具链还是降级——把 -DENABLE_ARM64=ON 去掉,改用 -DENABLE_NEON=OFF,先拿到能跑的产物。不要在同一个 build 目录里反复改参数硬试,缓存会让你的每次尝试都不可信。
5.3 漏了 UNIX=ON,配置阶段就走偏
现象:配置能过,构建时报找不到某个只在另一种平台上存在的头文件,或者出现一批平台宏相关的告警。
原因:源码按平台宏选实现,没有 POSIX 模式就落到另一个分支。
解决:交叉编译到 Linux 一律显式 -DUNIX=ON。改完重跑一次配置就行;如果还不对,删缓存再来,别在旧缓存上继续叠参数。
5.4 安装到 /opt 报 Permission denied
现象:cmake --install build 报错,提示无法创建目录或写入文件。
原因:CMAKE_INSTALL_PREFIX 指向 /opt 下的目录,普通用户没有写权限。
解决:要么用 sudo 执行安装,要么把前缀改到有权限的路径,打包时再拷到最终位置。安装前缀只决定「放进哪个目录」,跟产物能不能在板子上跑没有关系,别因为它报错就去怀疑编译器选错了。
5.5 产出一堆 .so,拷到板子上跑不起来
现象:构建成功,产物目录里是一批 .so,拷到板子上执行提示找不到共享库。
原因:BUILD_SHARED_LIBS 没关,动态库被生成出来,运行时得靠库搜索路径找到它们,而这套源码本来就不对外提供动态库接口。
解决:显式 -DBUILD_SHARED_LIBS=OFF,重新配置并重建,确认产物是一到两个可执行文件而不是一堆 .so。这一条和 5.4 的表现都是「跑不起来」,但一个发生在安装阶段、一个发生在板上运行阶段,先看错误出现在哪一步再动手。
6. 产物验收与脚本固化:三个命令确认它真能上板
6.1 三个验收命令
bash复制# 1) 文件类型与目标架构
file build/<可执行文件名>
# 期望:ELF 64-bit LSB executable, ARM aarch64
# 2) ELF 头里的 Machine 字段
readelf -h build/<可执行文件名> | grep Machine
# 期望:Machine: AArch64
# 3) 动态依赖,确认没意外链进主机的库
readelf -d build/<可执行文件名> | grep NEEDED
第三条在静态链接时可能没有输出,那不是失败,是好事。有输出才要逐条看:这些库在板子上存不存在。
6.2 上板跑一次真实数据
把二进制拷到板子上,用同一份输入跑一遍。同类四核 ARM64 开发板上实测:开启 ARM64 优化后,解压 1GB 固件包从 28 秒降到 19 秒,约 32%。这个数字只在同一份数据、同一条命令下有意义,换个包就没法比。板上起不来时,先看 6.1 第三条有没有多余依赖,再看文件权限——拷过去常常丢掉可执行位。
6.3 固化成脚本
bash复制#!/usr/bin/env bash
set -euo pipefail
BUILD=build
rm -rf "$BUILD" && mkdir -p "$BUILD" && cd "$BUILD"
cmake -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$HOME/codec-out" \
-DUNIX=ON -DBUILD_SHARED_LIBS=OFF \
-DENABLE_LZMA2=ON -DENABLE_AES=ON -DENABLE_THREADS=ON \
-DENABLE_ARM64=ON \
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
..
cmake
