Clang 交叉编译时，`--sysroot` 应该怎么配

很多人第一次用 Clang 做交叉编译，都会把注意力放在 --target，结果命令能过一半，却在找头文件、链接库甚至板端运行时连续踩坑。问题通常不在编译器本身，而在 --sysroot 没配、配错，或者配了一个并不完整的目标根目录。

这篇文章就按实际排错顺序来讲：先看 --sysroot 为什么不能省，再看一个可用的 sysroot 到底应该从哪来，最后分别说明命令行和 CMake 里的正确写法。读完后，你可以据此判断当前错误是路径拼错、根镜像不完整，还是 --target 与 sysroot 混用了不同平台。

为什么 --sysroot 不能省略

结论先说在前面：Clang 本身并不自带目标系统的头文件和库。它支持多目标代码生成，主要依赖 --target 指定架构和 ABI；但一旦缺少 --sysroot，标准头文件、标准库、启动文件就很容易回退到宿主机路径，比如 x86_64 Linux 上的 /usr/include 和 /lib。

这也是为什么有些项目表面上“能编译”，一到链接阶段就开始报错，或者程序拷到 ARM 板子上才暴露问题。常见后果包括：

• fatal error: 'stdio.h' file not found：说明 --sysroot 路径下没有 usr/include，或者目录拼写错误，例如写成了 usr/inc。
• ld: cannot find crt1.o: No such file or directory：说明 sysroot 里缺少 lib/ 或 usr/lib/ 下的启动文件，例如 crt*.o、Scrt1.o。
• 编译通过但运行时报 cannot open shared object file: libm.so.6：说明你指向的是不完整根镜像，比如只拷了头文件，没有把库文件一并带上。
• 链接阶段出现 undefined reference to 'printf'：看似是代码问题，实际往往是链接时没有找到目标平台对应的 C 运行库。
• 程序上板后直接 Segmentation fault：比起源码 bug，更应该先怀疑目标架构、libc 或动态链接器已经和 sysroot 混用。

--sysroot 的本质，就是把编译和链接时的“标准系统根目录”重定向到目标平台。只有这样，#include <stdio.h> 才会去目标系统里找头文件，-lc 才会链接到目标系统里的 libc.so，而不是误用宿主机版本。

--sysroot 路径应该从哪里来

一个可用的 sysroot 不是随便新建一个空目录就行，它必须是目标系统“用户空间”根镜像的完整副本，至少要覆盖 /usr/include 和 /usr/lib，很多情况下还需要 /lib 里的启动文件和动态链接器。

实践里常见来源主要有三类：

1. 直接使用 NDK 提供的 sysroot

如果目标是 Android，Android NDK r21+ 已经提供现成的 sysroot，路径通常在：

toolchains/llvm/prebuilt/<host>/sysroot

它配合具体的 arch-api 组合使用，例如 aarch64-linux-android30。这类 sysroot 一般完整度较高，适合作为 Android 交叉编译的默认来源。

2. 使用 Buildroot 或 Yocto 的输出目录

在嵌入式 Linux 项目里，更常见的来源是 Buildroot 或 Yocto 构建产物。构建完成后，下面这些目录通常就是标准 sysroot：

output/host/<toolchain>/sysroot
output/staging

这类路径的好处是与项目工具链、目标库版本、目标 libc 通常保持一致，适合长期构建和自动化集成。

3. 从目标设备手动提取根镜像

如果没有现成 SDK，也可以从目标设备手动整理 sysroot。例如文中给出的方式是：

rsync -a v /usr/include /usr/lib /lib /etc rootfs/

除此之外，还要补全关键动态链接器，例如 lib/ld-linux-aarch64.so.1。否则即便编译和链接通过，程序真正运行时仍可能因为缺运行时组件而失败。

这里有一个容易被忽略的细节：--sysroot 路径末尾不要加斜杠。Clang 内部会自己处理路径拼接，末尾多一个 / 反而可能触发 no such file or directory 一类误报。

Clang 命令行里怎么正确传 --sysroot

在命令行中，--sysroot 需要显式指定，而且要放在所有源文件和 -o 之前。它对标准头文件和标准库的搜索优先级，高于你手工追加的 -I 和 -L。

典型写法如下：

clang --target=aarch64-linux-gnu 
--sysroot=/home/book/100ask_imx6ull-sdk/Buildroot_2020.02.x/output/host/arm-buildroot-linux-gnueabihf/sysroot 
-I/usr/local/mylib/include 
-L/usr/local/mylib/lib 
main.c -o main

这里有三个判断点最关键：

• --target 和 --sysroot 必须匹配。例如 --target=armv7a-linux-androideabi19，就应该搭配 NDK 里的 Android sysroot，不能把 aarch64 工具链和 armv7 的 sysroot 混在一起。
• --sysroot 会重定向所有标准路径。也就是说，#include <stdio.h> 会去查 $SYSROOT/usr/include/stdio.h，而 -lc 会去链接 $SYSROOT/usr/lib/libc.so。
• 即便同时使用了 --gcc-toolchain，例如指向 /usr/local/arm-linux-gnueabihf，--sysroot 也依然要单独指定。Clang 不会自动从 toolchain 路径里帮你推导目标根目录。

换句话说，--target 决定“给谁生成代码”，--sysroot 决定“从谁那里拿头文件和库”。这两个参数缺一不可，也不能各指各的系统。

CMake 里怎么设置 sysroot

CMake 不直接识别你手写的 --sysroot 参数，通常要通过两个变量配合：

• CMAKE_SYSROOT：CMake 会把它转换成 Clang 的 --sysroot 选项。
• CMAKE_FIND_ROOT_PATH：控制 find_package()、find_library() 等查找行为，应该包含与 CMAKE_SYSROOT 相同的路径。

很多“命令行能编，CMake 就找不到库”的问题，都出在这里只设了 CMAKE_SYSROOT，却没约束 CMake 的查找根路径。典型错误写法是：

set(CMAKE_SYSROOT "/path/to/sysroot")

这样做的后果是，CMake 可能能找到 FindXXX.cmake，但继续解析时却跑到宿主机环境里找 XXXConfig.cmake 或实际库文件，最终产生交叉编译和本机路径混用的问题。

更稳妥的写法是放在 CMakeLists.txt 开头或 toolchain file 中：

set(CMAKE_SYSROOT "/home/book/100ask_imx6ull-sdk/sysroot")
set(CMAKE_FIND_ROOT_PATH "/home/book/100ask_imx6ull-sdk/sysroot")
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

这里的 ONLY 非常关键。它会强制 CMake 只在 CMAKE_FIND_ROOT_PATH 内搜索，从而避免误用宿主机的 /usr/lib/cmake、/usr/include 或其他本地库路径。

最容易忽略的风险：不要混用不同平台的 sysroot

sysroot 不是“一次配好，永远复用”的通用目录。不同目标平台通常都需要各自独立的 sysroot，包括但不限于：

• 不同架构：ARM32、ARM64、RISC-V
• 不同操作系统：Linux、Android、Baremetal
• 不同 C 运行库：glibc、musl

这些差异会直接影响头文件内容、ABI、动态链接器位置、标准库实现和 ELF 架构信息。把不匹配的 sysroot 混进去，编译器不一定第一时间报错，但生成的结果很可能在目标设备上无法运行。

最典型的情况，就是把 x86_64 的 libc.so 混入 ARM64 程序。此时构建过程未必会立刻失败，但你到板子上执行 file 检查二进制或库文件时，往往就能发现 ELF 架构根本对不上。

一份实用排查清单

如果你正在排查 Clang 交叉编译环境，可以直接按下面这几个问题自查：

• --sysroot 是否显式传入，而不是只写了 --target？
• sysroot 下是否同时存在 /usr/include 与 /usr/lib，必要时还有 /lib？
• 是否缺少 crt1.o、Scrt1.o、动态链接器这类启动或运行时关键文件？
• --target、sysroot、libc 类型、目标系统是否完全一致？
• 在 CMake 中，是否同时设置了 CMAKE_SYSROOT 和 CMAKE_FIND_ROOT_PATH？
• 是否误把宿主机的 /usr/include、/usr/lib、/usr/lib/cmake 混进了交叉编译搜索路径？

只要这几项有一项不成立，问题就很可能不是源码本身，而是 sysroot 的来源、完整性或匹配关系出了偏差。