在 Linux 上配置树莓派 4B OpenCV 交叉编译

Debian 系（Debian、Ubuntu、Mint 等）#

如果你用的是 Debian 系，事情很简单。Debian 的 multiarch 支持非常成熟，直接 apt install 即可获得交叉编译工具链：

1
sudo dpkg --add-architecture arm64
2
sudo apt update
3
sudo apt install -y --no-install-recommends \
4
    gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
5
    binutils-aarch64-linux-gnu

然后配置 CMake 工具链文件，指定 sysroot 路径和交叉编译器即可开始编译。

非 Debian 系（Fedora、Arch、openSUSE 等）#

如果你用的是 Fedora、Arch Linux、openSUSE 等非 Debian 系发行版，问题就复杂了。这些发行版虽然也提供 aarch64-linux-gnu-* 交叉工具链包，但存在几个棘手的问题：

1. 工具链版本不一致，不同发行版提供的 binutils/gcc 版本可能与树莓派 sysroot 中的库 ABI 不兼容。
2. 库路径布局差异，非 Debian 系的 aarch64 工具链默认搜索路径与 Debian 的 multiarch 布局 /usr/lib/aarch64-linux-gnu/ 不同，导致链接器找不到库。
3. glibc 版本不匹配，Arch 等滚动发行版的 glibc 版本往往更新，链接到树莓派旧版 glibc 时可能出现符号未定义的问题。

使用容器是非常好的一种解决方案。在 Docker/Podman 容器中运行一个完整的 Debian 环境，将树莓派 sysroot 挂载进去，所有编译操作都在容器内完成。这样工具链和 sysroot 同属 Debian 生态，自然兼容。

各部分说明#

ENV 环境变量定义了交叉编译的目标三元组 aarch64-linux-gnu，以及工具链和 sysroot 的挂载路径。将这些路径抽取为变量，方便使用者替换为自己需要的版本。

apt 安装的软件包分为几类：

• build-essential：编译基础设施
• gcc-aarch64-linux-gnu：ARM64 交叉编译器、汇编器和链接器
• cmake ninja-build：Ninja 构建系统
• rsync：从树莓派同步文件
• pkg-config dpkg-dev：用于查找依赖库和生成正确的 pkg-config 路径

entrypoint.sh是容器启动时自动执行的脚本。它的任务是建立符号链接，让交叉工具链的默认搜索路径指向我们挂载的树莓派 sysroot：

• 将 ${SYSROOT_MOUNT}/usr/include 链接为工具链的 include 目录
• 将 ${SYSROOT_MOUNT}/usr/lib/${TARGET_TRIPLE} 链接为工具链的 lib 目录

这样当你使用 #include <opencv2/core.hpp> 时，编译器实际上会从树莓派的 sysroot 中寻找这个头文件。

CC/CXX 环境变量指定了交叉编译器，并通过 --sysroot 参数将 sysroot 设置为编译的根目录。GCC 的 --sysroot 选项会改变所有标准搜索路径（/usr/include、/usr/lib 等）的根前缀，效果等同于将 sysroot 模拟为 /。

PKG_CONFIG_SYSROOT_DIR 告诉 pkg-config 在 sysroot 中查找 .pc 文件，而 PKG_CONFIG_PATH 指定了 .pc 文件的具体搜索路径。这对于 CMake 找到 OpenCV 的依赖库至关重要。

构建和运行容器#

1
# 构建镜像
2
docker build -t rpi-cross-compiler .
3

4
# 运行容器，将 sysroot 挂载进去
5
docker run --rm -it \
6
    -v ~/rpi-sysroot:/sysroot:ro \
7
    -v $(pwd):/workspace \
8
    rpi-cross-compiler \
9
    bash

说明：/sysroot 以只读 :ro 方式挂载，防止编译过程意外修改树莓派系统文件。工作目录 /workspace 以读写方式挂载当前目录，用于存放源码和编译输出。

1. 修复 merged-usr 目录结构#

Debian 从 Buster 开始采用了 merged-usr 方案（即 /bin、/sbin、/lib 统一迁移到 /usr/bin、/usr/sbin、/usr/lib 下，原路径保留为符号链接）。树莓派的 Raspberry Pi OS 基于 Debian，自然也遵循此布局。

但 rsync 在复制符号链接时，如果目标路径的解析出现问题（例如 --copy-unsafe-links 的处理时机），可能导致 sysroot 根目录下的 /include 或 /lib 符号链接变成空目录或指向错误位置。编译器查找头文件时，会期望 /sysroot/usr/include 是真实目录。如果 rsync 产物的结构不对，预处理脚本会将其修正为：

1
/sysroot/
2
├── include -> usr/include      # 符号链接
3
├── lib -> usr/lib              # 符号链接
4
└── usr/
5
    ├── include/                # 真实头文件目录
6
    └── lib/
7
        └── aarch64-linux-gnu/  # multiarch 库目录

2. 修复 C++ 标准库的多架构符号链接#

GCC 的 C++ 标准库头文件按架构组织，结构如下：

1
/usr/include/c++/14/
2
├── <平台无关头文件>
3
└── aarch64-linux-gnu/    # 平台相关头文件 → 链接到 ../../aarch64-linux-gnu/c++/14

在树莓派上，/usr/include/c++/14/aarch64-linux-gnu/ 应该是一个符号链接，指向 /usr/include/aarch64-linux-gnu/c++/14/，即 Debian multiarch 的 C++ 头文件存放位置。

这个符号链接使用的是绝对路径。当你用 rsync 拉取 sysroot 时，如果链接目标没有被完整保留，或者链接断掉了，编译 C++ 代码时就会找不到 <bits/c++config.h> 等平台相关头文件，报错：

1
fatal error: bits/c++config.h: No such file or directory

预处理会检查这个链接，如果断裂就重新创建。

我就是在这一步踩了坑。如果树莓派上没有 /usr/include/c++/14/aarch64-linux-gnu 也没关系，预处理会自动创建链接的。

3. 修复 alternatives 机制的断裂符号链接#

Debian 使用 update-alternatives 系统来管理同一软件的多个实现。BLAS 和 LAPACK（线性代数库，OpenCV 的核心依赖）就是典型例子：

1
/usr/lib/aarch64-linux-gnu/
2
├── libblas.so.3 -> blas/libblas.so.3.12.1   # alternatives 管理的链接
3
├── libblas.so -> blas/libblas.so             # 开发用的 .so 链接
4
├── liblapack.so.3 -> lapack/liblapack.so.3.12.1
5
└── liblapack.so -> lapack/liblapack.so

这些符号链接指向 blas/ 和 lapack/ 子目录下的实际库文件。但 rsync 同步时，这些相对路径链接可能因为 rsync 的 --copy-unsafe-links 选项或者文件系统差异而断裂或变成悬空链接。

后果就是链接阶段 CMake 找不到 -lblas 和 -llapack，链接器直接报 cannot find -lblas。

预处理脚本遍历 sysroot 中的库目录，检查这些关键的 libblas.* 和 liblapack.* 链接，如果断裂就手动修复，重新指向正确的目标文件。虽然逻辑看起来是重复的 case 分支，但每个链接的目标版本号可能不同（liblapack.so.3.12.1、libblas.so.3.12.1），必须逐一处理。

项目的 CMakeLists.txt#

跨平台编译的第一步是把 CMakeLists.txt 写对。下面是一个典型的 OpenCV 项目配置：

1
cmake_minimum_required(VERSION 3.16)
2
project(MyCVProject LANGUAGES CXX)
3

4
set(CMAKE_CXX_STANDARD 17)
5
set(CMAKE_CXX_STANDARD_REQUIRED ON)
6

7
find_package(OpenCV REQUIRED)
8

9
add_executable(my_app main.cpp)
10
target_link_libraries(my_app PRIVATE ${OpenCV_LIBS})

find_package(OpenCV REQUIRED) 会去 sysroot 里搜索 OpenCV 的 CMake 配置文件（OpenCVConfig.cmake），找到后自动设置好 include 路径和链接库。

交叉编译工具链文件#

CMake 靠工具链文件来知道你要交叉编译。创建一个 toolchain.cmake：

1
set(CMAKE_SYSTEM_NAME Linux)
2
set(CMAKE_SYSTEM_PROCESSOR aarch64)
3

4
set(CMAKE_SYSROOT /sysroot)
5

6
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
7
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
8

9
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
10
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
11
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
12
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

配置说明：

• CMAKE_SYSROOT：告诉 CMake 所有搜索都以此为根
• CMAKE_C_COMPILER / CMAKE_CXX_COMPILER：指定交叉编译器。由于容器的 ENV 已经设了 CC/CXX（带 --sysroot），如果你想省略这两个变量，CMake 会自动从环境变量中获取
• CMAKE_FIND_ROOT_PATH_MODE：控制 find_* 命令的查找策略。PROGRAM NEVER 表示不从 sysroot 中查找程序，而 LIBRARY ONLY、INCLUDE ONLY、PACKAGE ONLY 表示库、头文件、包都只从 sysroot 中查找，避免污染宿主机的头文件

编译#

1
# 在容器内执行
2
cd /workspace
3
mkdir build && cd build
4

5
cmake -GNinja \
6
    -DCMAKE_TOOLCHAIN_FILE=../toolchain.cmake \
7
    -DCMAKE_BUILD_TYPE=Release \
8
    ..
9

10
ninja -j$(nproc)

编译完成后，build/ 目录下就是可以在树莓派上直接运行的 ARM64 二进制文件。用 file 命令确认一下：

1
file my_app
2
# my_app: ELF 64-bit LSB executable, ARM aarch64, dynamically linked, ...