1. 课程导入与开发环境搭建

Mosquitto 是 Eclipse 基金会下的开源 MQTT Broker 实现，用 C 语言编写，体积小、依赖少、可裁剪，是嵌入式 MQTT 系统中最常见的服务端组件之一。在典型的嵌入式 MQTT 系统中，它通常扮演“消息中枢”的角色：设备端（MCU 或嵌入式 Linux 板）作为 MQTT Client 发布/订阅主题，Mosquitto 负责会话管理、主题路由、QoS 消息投递与保留消息存储，上层应用再通过订阅获取数据。理解这一分工，是后续所有编译、配置与调试工作的前提。

本课程的学习路径可以概括为“先跑通、再裁剪、后集成”：先在宿主机上编译并运行 Mosquitto，验证发布/订阅链路；再学习交叉编译，把它移植到目标板 Linux；最后结合嵌入式客户端完成端到端联调。本章聚焦第一步的前置条件——工具链准备、目标板环境确认与源码获取。

交叉编译工具链准备

交叉编译的核心是“在 x86 宿主机上生成 ARM 可执行文件”。第一步是确认目标板架构。在目标板上执行：

uname -m
# 常见输出：armv7l、aarch64、mips
cat /proc/cpuinfo | grep -i "model name\|Hardware"

若输出为 armv7l，通常选择 arm-linux-gnueabihf- 前缀的工具链（hf 表示硬浮点）。安装后验证：

arm-linux-gnueabihf-gcc -v
# 查看 Target: arm-linux-gnueabihf
arm-linux-gnueabihf-gcc -print-sysroot

工具链的 sysroot 必须与目标板根文件系统一致，否则会出现“编译通过、运行报 GLIBC 版本不匹配”的问题。建议把目标板的 /lib、/usr/lib 通过 NFS 或 rsync 同步到宿主机，作为 --sysroot 参数使用。

目标板 Linux 环境确认

Mosquitto 运行依赖网络栈和文件系统。上板前应确认三点：一是内核已启用 CONFIG_NET、CONFIG_INET，可用 ifconfig 或 ip addr 看到网卡；二是根文件系统可写，touch /tmp/test 能成功；三是动态库路径正确，ldd 能解析 libc.so.6。若目标板使用只读 squashfs，需要把 Mosquitto 配置和持久化目录挂载到可写的 tmpfs 或数据分区。

源码获取与版本选择

Mosquitto 源码可从 GitHub 或 Eclipse 官方镜像获取。嵌入式场景建议选择稳定版本，例如 2.0.x 系列。获取方式：

wget https://github.com/eclipse/mosquitto/archive/refs/tags/v2.0.18.tar.gz
tar -xzf v2.0.18.tar.gz
cd mosquitto-2.0.18

编译前先阅读 CMakeLists.txt 或 config.mk，确认可裁剪项：WITH_TLS、WITH_WEBSOCKETS、WITH_SRV。嵌入式设备若不需要 TLS，可关闭以减小体积；若需要 TLS，则必须先交叉编译 OpenSSL 并指定其路径。

最小验证：宿主机先跑通

在交叉编译之前，建议先在宿主机本地编译并运行，确认源码完整、依赖齐全：

make
sudo make install
mosquitto -v
# 另开终端
mosquitto_sub -t "test/#" -v
mosquitto_pub -t "test/hello" -m "hello mqtt"

若订阅端能收到 test/hello hello mqtt，说明 Broker 与客户端链路正常。此时再切换到交叉编译，问题范围会小很多。

交叉编译 Mosquitto 的关键参数

Mosquitto 使用 Makefile 构建，交叉编译时通过 CC、CXX、CFLAGS、LDFLAGS 传入工具链。示例：

make CC=arm-linux-gnueabihf-gcc \
     CXX=arm-linux-gnueabihf-g++ \
     CFLAGS="-I$SYSROOT/usr/include" \
     LDFLAGS="-L$SYSROOT/usr/lib -Wl,-rpath-link,$SYSROOT/usr/lib" \
     WITH_TLS=no WITH_WEBSOCKETS=no

编译完成后，用 file mosquitto 检查架构，应显示 ARM；用 arm-linux-gnueabihf-readelf -d mosquitto 检查依赖库。把 mosquitto、mosquitto_pub、mosquitto_sub 和 mosquitto.conf 拷贝到目标板，运行 ./mosquitto -c mosquitto.conf -v，观察是否监听 1883 端口。

本章交付检查表