📚 课程目录第4章交叉编译Mosquitto broker与客户端

4. 交叉编译Mosquitto broker与客户端

在嵌入式 MQTT 项目中，Mosquitto 通常不会直接在目标板上编译，而是在 x86_64 开发主机上通过交叉编译工具链生成 ARM/MIPS/RISC-V 可执行文件，再部署到目标板。本节以常见的 arm-linux-gnueabihf 工具链为例，说明从源码到可运行 broker 与客户端的完整构建路径，并给出依赖库处理、产物验证和典型错误的排查方法。

一、构建对象与依赖关系

Mosquitto 源码树中与本节相关的核心产物有三类：mosquitto（broker 主程序）、mosquitto_pub 与 mosquitto_sub（命令行客户端），以及 libmosquitto.so（客户端库）。broker 依赖 libc、libpthread、libssl/libcrypto（启用 TLS 时）、libcjson（2.x 版本解析配置与动态安全时使用）；客户端除上述库外还依赖 libmosquitto。交叉编译的关键在于：所有依赖库必须使用同一套工具链、同一 sysroot 编译，否则会出现 ABI 不匹配或链接失败。

二、CMake 交叉编译流程

Mosquitto 2.x 默认使用 CMake。交叉编译的核心是编写工具链文件 arm-toolchain.cmake，明确编译器、sysroot 和查找根路径：

# arm-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)
set(CMAKE_SYSROOT /opt/arm-sysroot)
set(CMAKE_FIND_ROOT_PATH /opt/arm-sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

随后执行配置与构建。建议关闭不需要的组件以减小体积，并显式指定 OpenSSL 与 cJSON 的路径，避免 CMake 误用主机库：

cmake -B build-arm \
  -DCMAKE_TOOLCHAIN_FILE=arm-toolchain.cmake \
  -DCMAKE_INSTALL_PREFIX=/opt/arm-sysroot/usr \
  -DWITH_TLS=ON \
  -DWITH_CJSON=ON \
  -DDOCUMENTATION=OFF \
  -DWITH_APPS=ON
cmake --build build-arm -j$(nproc)
cmake --install build-arm

若依赖库未安装在 sysroot 中，可通过 -DOPENSSL_ROOT_DIR=/opt/arm-sysroot/usr 与 -DCJSON_INCLUDE_DIR、-DCJSON_LIBRARY 显式指定。配置阶段应重点观察输出中 Found OpenSSL、Found cJSON 的路径是否指向 sysroot，而不是 /usr/lib/x86_64-linux-gnu。

三、Makefile 构建流程

Mosquitto 1.x 及部分裁剪版本使用 Makefile。此时通过 CC、CFLAGS、LDFLAGS 传入交叉参数：

make CC=arm-linux-gnueabihf-gcc \
  CFLAGS="-I/opt/arm-sysroot/usr/include -O2" \
  LDFLAGS="-L/opt/arm-sysroot/usr/lib -Wl,-rpath-link,/opt/arm-sysroot/usr/lib" \
  WITH_TLS=yes WITH_CJSON=yes \
  prefix=/opt/arm-sysroot/usr \
  -j$(nproc)

Makefile 方式下，config.mk 中的 WITH_* 开关决定是否链接对应库。若出现 undefined reference to SSL_CTX_new，说明 TLS 已启用但未链接 libssl；若出现 cannot find -lcjson，则需检查 LDFLAGS 中的库路径是否正确。

四、依赖库处理要点

交叉编译依赖库时，推荐统一安装到 sysroot 的 /usr 下，形成自洽的根文件系统视图。OpenSSL 交叉编译示例：

./Configure linux-armv4 \
  --prefix=/opt/arm-sysroot/usr \
  --openssldir=/opt/arm-sysroot/usr/ssl \
  shared no-tests
make CC=arm-linux-gnueabihf-gcc -j$(nproc)
make install_sw

cJSON 则可用 CMake 交叉编译并安装到同一 sysroot。需要特别注意的是：libmosquitto.so 在目标板上运行时，动态链接器会按 DT_NEEDED 查找 libssl.so.3、libcrypto.so.3、libcjson.so.1 等，因此这些库必须一并部署到目标板的 /usr/lib 或通过 LD_LIBRARY_PATH 指定。

五、编译产物验证

构建完成后，先在主机侧验证 ELF 架构与依赖，再上板运行：

file build-arm/src/mosquitto
# 期望输出：ELF 32-bit LSB executable, ARM, EABI5 ...

arm-linux-gnueabihf-readelf -d build-arm/src/mosquitto | grep NEEDED
# 检查 libssl.so.3 / libcrypto.so.3 / libcjson.so.1 等

arm-linux-gnueabihf-readelf -h build-arm/src/mosquitto | grep Machine
# 期望：ARM

上板后执行 ./mosquitto -h 与 ./mosquitto_sub -h，确认程序可启动。随后启动 broker 并用客户端做一次本地回环测试：

./mosquitto -c mosquitto.conf -v &
./mosquitto_sub -h 127.0.0.1 -t test/topic -v &
./mosquitto_pub -h 127.0.0.1 -t test/topic -m "hello-arm"

若订阅端打印 test/topic hello-arm，说明 broker 与客户端均可在目标平台正常工作。

六、常见错误排查

错误现象	可能原因	排查方法
Exec format error	产物仍为主机 x86_64 架构	`file` 检查 ELF 架构，确认工具链文件生效
undefined reference to SSL_*	TLS 开启但未链接 libssl	检查 `WITH_TLS` 与 `OPENSSL_ROOT_DIR`
cannot find -lcjson	cJSON 未安装到 sysroot 或路径错误	确认 `LDFLAGS` 与 `CJSON_LIBRARY`
error while loading shared libraries	目标板缺少依赖 .so	用 `readelf -d` 列出 NEEDED 并逐一部署
CMake 找到主机库	FIND_ROOT_PATH_MODE 未设为 ONLY	检查工具链文件中查找模式设置

建议在 CI 或构建脚本中加入 file 与 readelf -d 的自动检查，一旦产物架构或依赖不符合预期立即失败，避免把错误产物烧录到目标板后才发现。

交叉编译 Mosquitto 的本质是保证“工具链—sysroot—依赖库—产物”四者一致。CMake 方式适合 2.x 及需要精细控制组件的场景，Makefile 方式适合 1.x 或轻量裁剪。无论哪种方式，构建后都应通过 file、readelf 和上板回环测试三步验证，才能确认 broker 与客户端真正可移植、可运行。