1. 从一次 Exec format error 说起:代码开发工具链没配对,代码再对也白搭
上周把一段在 x86 开发机上跑得好好的 C++ 程序拷到 ARM 板卡,连 main 都没进去就退出了,终端只留下 Exec format error。排查一圈才发现,问题不在代码,在代码开发工具链没配对:主机上的 gcc 默认生成 x86-64 指令,板卡的 ARM 核根本不认识。linux-arm 交叉编译这件事,核心不是写多少代码,而是让编译器、链接器、CMake 和运行时库都站在 ARM 这一侧。这篇笔记面向需要把 C++ 项目从 x86 主机部署到 ARM 板卡的开发者,从 toolchain 文件写到部署验证,把参数、链接顺序和翻车点一次讲清。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 交叉编译工具链:代码开发工具的第一道门槛
2.1 为什么 x86 上的 gcc 不能直接编 ARM 程序
在 x86 主机上直接敲 g++ main.cpp -o camera_demo,生成的是 x86-64 可执行文件。这个文件放到 ARM 板卡上,内核加载时发现 ELF 头里的机器类型对不上,就会报 Exec format error。这不是权限问题,也不是动态库缺失,而是指令集和 ABI 完全不匹配。交叉编译工具链的作用,就是用一套运行在 x86 上的编译器,生成 ARM 架构的目标文件,再交给 ARM 版本的链接器去链接。
一套 aarch64 交叉编译工具链通常包含 aarch64-linux-gnu-gcc、aarch64-linux-gnu-g++、aarch64-linux-gnu-ld、aarch64-linux-gnu-ar、aarch64-linux-gnu-strip 等。CMake 本身不关心这些工具装在哪,它只认 toolchain 文件里指定的编译器路径。所以第一步不是改 CMakeLists.txt,而是把 toolchain 文件写对。工具链没进 PATH 时,CMake 配置阶段就会报找不到编译器,这时候先跑 aarch64-linux-gnu-gcc --version 确认命令可用,再往下走。
注意:交叉编译工具链的版本要和板卡上的 glibc 版本大致匹配。主机工具链太新、板卡系统太旧,运行时可能报
GLIBC_2.xx not found。这个坑在部署阶段才会暴露,配置阶段看不出来。
2.2 写一个可复用的 aarch64-toolchain.cmake
CMake 的 toolchain 文件不需要很长,关键是四个变量:系统名、处理器架构、C 编译器、C++ 编译器。下面这份 aarch64-toolchain.cmake 可以直接放在项目里复用:
cmake复制# aarch64-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
# 如果工具链不在默认 PATH,可以显式指定绝对路径
# set(CMAKE_C_COMPILER /opt/toolchain/bin/aarch64-linux-gnu-gcc)
# set(CMAKE_CXX_COMPILER /opt/toolchain/bin/aarch64-linux-gnu-g++)
CMAKE_SYSTEM_NAME 设为 Linux,告诉 CMake 这是为目标系统 Linux 做交叉编译,不是主机本地编译。CMAKE_SYSTEM_PROCESSOR 设为 aarch64,影响 CMake 对目标架构的判断。CMAKE_C_COMPILER 和 CMAKE_CXX_COMPILER 是最关键的两行,它们决定后续所有编译动作走哪套工具链。注释掉的绝对路径写法适合工具链没加入 PATH 的场景,实际项目里我更推荐用绝对路径,避免 CI 环境里 PATH 不一致导致配置漂移。
写完之后,配置命令要显式带上 toolchain 文件:
bash复制cmake -S . -B build-aarch64 \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-toolchain.cmake
-S . 指定源码目录,-B build-aarch64 指定构建目录,-DCMAKE_TOOLCHAIN_FILE 是入口。构建目录单独命名很重要,x86 本地构建和 ARM 交叉构建不要共用一个目录,否则 CMake 缓存里会留着上一次的编译器路径,后面怎么改 toolchain 文件都不生效。
2.3 配置时怎么确认 CMake 真的用了交叉编译器
配置成功后不要急着编译,先看 CMake 缓存里的编译器路径:
bash复制grep -E 'CMAKE_(C|CXX)_COMPILER:' build-aarch64/CMakeCache.txt
如果输出是 /usr/bin/c++ 或 /usr/bin/gcc,说明 toolchain 文件没生效,常见原因是 -DCMAKE_TOOLCHAIN_FILE 路径写错,或者构建目录里已经有旧的 CMakeCache.txt。这时候删掉 build-aarch64 重新配置,不要手工改缓存。确认输出是 aarch64-linux-gnu-gcc 和 aarch64-linux-gnu-g++ 之后,再执行 cmake --build build-aarch64 -j。
编译完成后可以用 file 看产物架构:
bash复制file build-aarch64/camera_demo
正常输出里应该出现 ARM aarch64。如果还是 x86-64,说明编译阶段又走了主机编译器,回到缓存检查那一步。这个验证动作花不了几秒钟,但能省掉后面拷到板卡上才发现跑不起来的来回折腾。
3. CMakeLists 与 SDK 库链接:顺序错了,符号就找不到
3.1 include 与 link 目录:把头文件和库文件接进来
交叉编译环境里,厂商 SDK 通常给的是 ARM 版本的 include 和 lib 目录。CMakeLists 里要把这两个目录指进来,否则编译阶段找不到头文件,链接阶段找不到库文件。下面是一份贴近实际项目的 CMakeLists.txt 骨架:
cmake复制cmake_minimum_required(VERSION 3.10)
project(camera_demo)
set(CMAKE_CXX_STANDARD 11)
include_directories(${CMAKE_SOURCE_DIR}/sdk/include)
link_directories(${CMAKE_SOURCE_DIR}/sdk/lib)
add_executable(camera_demo main.cpp)
target_link_libraries(camera_demo
vendor_sdk
vendor_core
crypto
ssl
pthread
dl
z)
include_directories 把 SDK 头文件目录加到编译搜索路径,main.cpp 里 #include 的厂商头文件才能被找到。link_directories 把 SDK 库目录加到链接器搜索路径,后面 target_link_libraries 里的 vendor_sdk 才能被解析成 libvendor_sdk.so 或 libvendor_sdk.a。这里的 vendor_sdk、vendor_core 是厂商库名占位,实际项目里按 SDK 提供的库文件名替换,但链接顺序的逻辑不变。
add_executable 生成目标可执行文件,target_link_libraries 决定这个目标链接哪些库。注意不要把 link_directories 写成全局的 link_libraries,后者会把库塞给所有目标,项目一大就容易出现无关目标被强行链接的问题,排查起来很费劲。
3.2 target_link_libraries 的顺序为什么不能随便写
链接器解析符号是从左到右扫描的。target_link_libraries 里写的库顺序,会原样传给链接器。如果 vendor_sdk 依赖 vendor_core 里的符号,那么 vendor_sdk 必须放在 vendor_core 前面。写成 vendor_core vendor_sdk,链接器先扫 vendor_core,此时还没有未解析符号,等扫到 vendor_sdk 时发现它需要 vendor_core 里的函数,但 vendor_core 已经被扫过了,链接器不会回头再找,于是报 undefined reference。
这就是为什么示例里把 vendor_sdk 放在最前面,vendor_core 紧跟其后,再往后是 crypto、ssl、pthread、dl、z 这些底层依赖。底层依赖放后面,是为了让上层库的未解析符号能在后面被满足。实际项目里如果 SDK 库之间还有更复杂的依赖,先把依赖关系画出来,按“上层在前、底层在后”排一遍,再编译。
提示:遇到
undefined reference不要先怀疑函数名拼错,先看链接命令里库的顺序。链接器不会告诉你“顺序反了”,它只会说某个符号找不到,这个报错很容易把人带偏。
3.3 用 VERBOSE=1 看链接器实际吃了什么
CMake 默认把链接命令藏起来,出问题时看不到实际传了哪些 -l 和 -L。用 make VERBOSE=1 可以把完整命令打出来:
bash复制cmake --build build-aarch64 --verbose
输出里会有一长串 aarch64-linux-gnu-g++ ... -L.../sdk/lib -lvendor_sdk -lvendor_core -lcrypto -lssl -lpthread -ldl -lz。重点看三件事:-L 指向的是不是 ARM 版 SDK 的 lib 目录,-l 的顺序是不是上层库在前、底层库在后,有没有混进主机路径下的 x86 库。如果 -L 指到了 /usr/lib/x86_64-linux-gnu,链接阶段可能直接报 skipping incompatible,或者链接成功但运行时崩溃。
我一般会在 CI 里保留一份 --verbose 的构建日志,出问题时先翻链接命令,比在 CMakeLists 里反复猜要快得多。链接顺序这个问题属于典型的“编译通过、链接翻车”,血泪经验就是:只要动了 SDK 库,就把 verbose 打开跑一遍。
4. 部署到 ARM 板卡:从 scp 到 ldd 的验证闭环
4.1 拷贝可执行文件和依赖库
交叉编译产物不能只拷一个可执行文件。动态链接的 SDK 库、系统库都要在板卡上能找到,否则运行阶段会报 error while loading shared libraries。常见做法是把可执行文件和厂商 SDK 的动态库一起拷到板卡的应用目录:
bash复制# 主机上执行,board-ip 替换为板卡地址
scp build-aarch64/camera_demo root@board-ip:/opt/app/
scp sdk/lib/libvendor_sdk.so root@board-ip:/opt/app/lib/
scp sdk/lib/libvendor_core.so root@board-ip:/opt/app/lib/
scp 的第一个参数是主机上的文件,第二个参数是板卡上的目标路径。/opt/app/ 放可执行文件,/opt/app/lib/ 放厂商动态库。系统库如 libcrypto.so、libssl.so、libpthread.so 一般板卡系统自带,不需要手工拷;如果板卡系统裁剪过,缺什么再补什么,不要一次性把主机上的库全拷过去,ABI 不匹配反而会引入新问题。
拷完之后给可执行文件加执行权限:
bash复制chmod +x /opt/app/camera_demo
这一步看起来简单,但漏掉就会报 Permission denied,和架构问题混在一起容易误判。部署脚本里把 chmod 和启动命令写在一起,能少一次手工排查。
4.2 用 readelf 和 ldd 确认架构与依赖
在板卡上先看 ELF 头,确认机器类型是 AArch64:
bash复制readelf -h /opt/app/camera_demo | grep Machine
正常输出是 Machine: AArch64。如果显示 Advanced Micro Devices X86-64,说明拷上去的还是主机编译的版本,回到第 2 章检查 toolchain 文件和构建目录。readelf 比 file 更底层,板卡上没有 file 命令时也能用。
再看动态库依赖:
bash复制ldd /opt/app/camera_demo
ldd 会列出每个依赖库的解析路径。如果 libvendor_core.so 显示 not found,说明运行时库路径没配好。注意 ldd 本身有安全风险,只对可信文件用;生产环境可以用 readelf -d 看 NEEDED 条目替代。
4.3 运行时库路径:LD_LIBRARY_PATH 与 rpath 的取舍
最直接的解决办法是设置 LD_LIBRARY_PATH:
bash复制export LD_LIBRARY_PATH=/opt/app/lib:$LD_LIBRARY_PATH
/opt/app/camera_demo
LD_LIBRARY_PATH 会告诉动态链接器优先去 /opt/app/lib 找库。缺点是它依赖启动环境,换个终端、换个服务启动方式就可能丢。更稳的做法是在链接时写 rpath,把库搜索路径编进可执行文件:
cmake复制target_link_options(camera_demo PRIVATE
-Wl,-rpath,'$ORIGIN/lib')
$ORIGIN 表示可执行文件所在目录,$ORIGIN/lib 就是可执行文件旁边的 lib 目录。这样板卡上不需要每次 export,拷到 /opt/app/ 下就能按相对路径找库。rpath 的优先级高于 LD_LIBRARY_PATH 的说法在不同 glibc 版本上有差异,实际项目里我一般两者都留:rpath 保底,LD_LIBRARY_PATH 方便临时换库调试。
注意:rpath 里的
$ORIGIN在 CMake 中要写成'$ORIGIN/lib',单引号不能省,否则 shell 会把$ORIGIN当变量展开成空字符串。
5. 代码开发工具链避坑:五类报错的现象、原因与解决
5.1 链接期:undefined reference 与 cannot find -lxxx
现象一:链接报 undefined reference to 'Vendor_Init'。 原因通常是 target_link_libraries 里库顺序反了。vendor_sdk 依赖 vendor_core 的符号,但 vendor_core 写在了 vendor_sdk 前面,链接器扫过 vendor_core 之后不再回头。解决方法是把上层库放前面、底层库放后面,改成 vendor_sdk vendor_core crypto ssl pthread dl z,然后重新跑 cmake --build build-aarch64 --verbose 看链接命令里的 -l 顺序。
现象二:链接报 cannot find -lvendor_sdk。 原因有两个常见方向:link_directories 指向的目录里没有 libvendor_sdk.so,或者库文件名不是 libvendor_sdk.so 这种 lib 前缀格式。先 ls sdk/lib 确认文件名,再看 CMakeLists 里的 link_directories 是不是写成了相对路径导致解析到别的目录。解决方法是把 link_directories 改成绝对路径,或者用 target_link_directories 绑定到具体目标,避免全局路径污染。
5.2 编译期:Exec format error 与 CMake 缓存残留
现象三:板卡运行报 Exec format error。 原因通常是编译时用了主机 gcc,不是交叉编译器。常见触发场景是构建目录里残留了上一次本地编译的 CMakeCache.txt,后面即使带了 -DCMAKE_TOOLCHAIN_FILE,CMake 也可能沿用缓存里的编译器。解决方法是删掉 build-aarch64 整个目录,重新执行 cmake -S . -B build-aarch64 -DCMAKE_TOOLCHAIN_FILE=...,然后用 grep CMAKE_CXX_COMPILER: build-aarch64/CMakeCache.txt 确认编译器路径,最后用 file 或 readelf -h 确认产物是 AArch64。
现象四:链接报 skipping incompatible .../libvendor_sdk.so when searching for -lvendor_sdk。 原因是拿 x86 版本的 SDK 库给 ARM 链接器用。厂商 SDK 一般会按平台分目录,sdk/lib/x86_64 和 sdk/lib/aarch64 不要混。解决方法是把 link_directories 指到 ARM 版 lib 目录,并用 file sdk/lib/libvendor_sdk.so 确认库文件本身是 ARM 架构。这个坑在“主机上能编译、板卡上跑不了”的场景里很常见,本质是代码开发工具链的搜索路径没隔离干净。
5.3 运行期:error while loading shared libraries
现象五:板卡运行报 error while loading shared libraries: libvendor_core.so: cannot open shared object file。 原因是运行时动态链接器找不到 libvendor_core.so。编译链接成功只说明链接阶段找到了库,不代表运行阶段也能找到。解决方法是把 libvendor_core.so 拷到板卡 /opt/app/lib/,然后设置 export LD_LIBRARY_PATH=/opt/app/lib:$LD_LIBRARY_PATH,或者在 CMake 里加 -Wl,-rpath,'$ORIGIN/lib' 重新链接。验证时用 ldd /opt/app/camera_demo 看依赖是否全部解析,not found 消失再启动。
这五类报错覆盖了链接期、编译期和运行期,实际排查时按“先看架构、再看链接命令、最后看运行时依赖”的顺序走,基本不会绕远路。代码开发工具链的问题往往不是单个点,而是 toolchain 文件、CMake 缓存、库路径三处中有一处没对齐,逐项确认比反复改代码有效。
6. 多平台构建的收尾习惯:工具链文件分目录,验证走三遍
项目里只要同时存在 x86 本地调试和 ARM 板卡部署,我就会把 toolchain 文件按平台分目录放,构建目录也分开命名。目录结构大概是这样:
| 用途 | toolchain 文件 | 构建目录 | 验证命令 |
|---|---|---|---|
| x86 本地调试 | 不指定,用默认编译器 | build-x86 |
file build-x86/camera_demo |
| ARM 板卡部署 | cmake/toolchains/aarch64-toolchain.cmake |
build-aarch64 |
readelf -h build-aarch64/camera_demo |
构建命令也固定成两条,不混用:
bash复制# x86 本地构建
cmake -S . -B build-x86
cmake --build build-x86 -j
# ARM 交叉构建
cmake -S . -B build-aarch64 \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-toolchain.cmake
cmake --build build-aarch64 -j
这样做的直接好处是 CMake 缓存不会互相污染,切换平台时不需要反复删目录。另一个好处是排查时能快速判断问题出在“平台配置”还是“代码本身”:同样的源码在 build-x86 里能过,在 build-aarch64 里链接报错,优先查库顺序和 SDK 架构;两边都报错,再回去看代码。
从那以后我每次交叉编译前都强制走一遍:先确认 toolchain 文件路径,再看 CMakeCache.txt 里的编译器,编译完用 readelf 看架构,部署后用 ldd 看依赖。这四步花不了几分钟,但能挡住大部分“代码没问题、环境有问题”的玄学故障。希望帮到你。
