4、构建系统与west工作流：掌握west命令、CMake构建流程、多板卡支持、自定义应用工程创建与编译烧录

Zephyr RTOS 的构建体系与传统嵌入式 IDE（如 Keil、IAR）有本质区别：它采用 west 作为顶层工作流工具，以 CMake 为底层构建引擎，配合 设备树（Devicetree） 与 Kconfig 配置系统，实现高度可裁剪、多架构、多板卡适配的编译管理。本章将深入拆解 west 与 CMake 的协作机制，从工程结构、构建流程、多板卡支持到自定义应用创建与烧录，帮助学员建立完整的 Zephyr 构建知识体系。

上图展示了 Zephyr 构建系统的核心链路：west 作为用户入口，将配置输入（板卡定义、应用配置、SoC 定义）传递给 CMake，CMake 根据这些输入生成构建脚本，最终由 Ninja 调用交叉编译器生成可执行文件，并通过 west flash 烧录到目标板。整个流程中，west 负责多仓库管理和高层命令封装，CMake 负责底层构建逻辑，两者分工明确、协作紧密。

4.1 west 命令体系与工程管理

核心原理：west 的多层架构

west 是 Zephyr 的元工具（meta-tool），它不仅仅是一个构建命令，更是一个多仓库管理工具。Zephyr 项目本身由多个 Git 仓库组成（zephyr、hal_*、modules_* 等），west 通过 west.yml 清单文件统一管理这些仓库的版本与位置。其架构分为三层：

• 命令层：提供 west build、west flash、west debug 等高层命令，屏蔽底层细节。
• 项目层：通过 west init 和 west update 管理多个 Git 仓库的克隆、同步与切换。
• 扩展层：允许用户自定义 west 子命令，例如 west build -t menuconfig 调用 CMake 目标。

理解 west 的关键在于：它不是替代 CMake，而是对 CMake 的封装与增强。west 将常用的 CMake 参数（如 -DBOARD=xxx）转换为更简洁的 --board xxx 形式，同时增加了对多仓库版本一致性的控制。

操作流程：west 常用命令速查

使用 west build 时，系统会自动在 build/ 目录下生成 CMake 缓存文件。若需切换板卡，建议先执行 west build -p always 强制重新配置，避免旧缓存干扰。

4.2 CMake 构建流程深度解析

核心原理：CMake 的三阶段处理

Zephyr 的 CMake 构建流程分为三个阶段：配置（Configure）→ 生成（Generate）→ 编译（Build）。配置阶段读取 CMakeLists.txt、Kconfig 和 .dts 文件，生成 .config 和 zephyr.dts；生成阶段创建 Ninja 构建脚本；编译阶段调用 GCC/Clang 完成编译链接。关键点在于：

• 工具链加载：通过 ZEPHYR_TOOLCHAIN_VARIANT 环境变量指定（如 zephyr、gnuarmemb），CMake 会加载对应的 cmake/toolchain/*.cmake。
• 板卡抽象：BOARD 变量决定加载 boards/<arch>/<board>/board.cmake，该文件定义 SoC、DTS 源文件、Flash 配置等。
• 配置合并：应用目录下的 prj.conf 与板卡默认配置 board_defconfig 合并，生成最终 .config。

一个典型的 CMakeLists.txt 最小结构如下：

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)
target_sources(app PRIVATE src/main.c)

其中 find_package(Zephyr) 是核心，它会自动加载 Zephyr 的构建系统、工具链和板卡定义。

操作流程：手动 CMake 与 west 的等价关系

理解 west 与 CMake 的映射关系有助于排障。以下两条命令等价：

# 使用 west（推荐）
west build -b nrf52840dk_nrf52840 app/hello_world

# 等价的手动 CMake 命令
cmake -B build -DBOARD=nrf52840dk_nrf52840 -DZEPHYR_BASE=/path/to/zephyr app/hello_world
cmake --build build

手动执行 CMake 时，需确保 ZEPHYR_BASE 环境变量已设置，且 ZEPHYR_TOOLCHAIN_VARIANT 指向正确的工具链。west 会自动处理这些环境变量，因此日常开发推荐使用 west。

4.3 多板卡支持机制

核心原理：板卡定义的层级结构

Zephyr 支持超过 500 种开发板，其多板卡支持依赖于分层定义机制：

1. 架构层：arch/<arch>/ 定义 CPU 核心（如 ARM Cortex-M、RISC-V）。
2. SoC 层：soc/<arch>/<soc_family>/ 定义芯片外设（如 nRF52840、STM32F4）。
3. 板卡层：boards/<arch>/<board_name>/ 定义具体开发板（如 nrf52840dk_nrf52840）。

板卡目录下通常包含：board.cmake（构建配置）、<board>.dts（设备树）、<board>_defconfig（默认 Kconfig）、Kconfig.board（板卡选项）。当指定 -b <board> 时，CMake 会按上述层级自动查找并加载对应文件。

判断方法：如何选择正确的板卡名称

使用 west build -b 前，可通过以下命令查看可用板卡：

west boards | grep nrf52840
# 输出示例：
# nrf52840dk_nrf52840
# nrf52840dongle_nrf52840
# nrf52840_pca10056

板卡名称遵循 <board_name>_<soc_name> 的命名规则。例如 nrf52840dk_nrf52840 表示 nRF52840 DK 开发板，搭载 nRF52840 SoC。若使用 QEMU 模拟，则选择 qemu_cortex_m3 等虚拟板卡。

4.4 自定义应用工程创建与编译烧录实战

操作流程：从零创建自定义应用

假设我们要创建一个名为 my_sensor_app 的应用，目标板为 nrf52840dk_nrf52840。步骤如下：

1. 创建目录结构：

my_sensor_app/
├── CMakeLists.txt
├── prj.conf
└── src/
    └── main.c

2. 编写 CMakeLists.txt：

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_sensor_app)
target_sources(app PRIVATE src/main.c)

3. 配置 prj.conf（启用串口日志）：

CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

4. 编写 main.c：

#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/drivers/uart.h>

void main(void)
{
    printk("Hello from my_sensor_app!\n");
}

5. 编译：

cd my_sensor_app
west build -b nrf52840dk_nrf52840 .

6. 烧录：

west flash --runner jlink

案例拆解：一次完整的编译烧录排障

背景与约束：某团队使用 nRF52840 DK 开发一个 BLE 传感器节点，在 CI 服务器上执行 west build 时出现 CONFIG_SENSOR_XXX not found 错误。CI 环境为 Ubuntu 20.04，Zephyr SDK 已安装，但未设置 ZEPHYR_TOOLCHAIN_VARIANT。

初始现象：编译日志显示 error: "CONFIG_SENSOR_BME280" is not defined，但本地开发机编译正常。

分析过程：

• 检查 prj.conf 中确实定义了 CONFIG_SENSOR_BME280=y。
• 对比本地与 CI 的 west.yml 版本，发现 CI 的 zephyr 仓库落后两个版本，导致 Kconfig 选项名称变更。
• 进一步检查 CI 日志，发现 west update 未执行，使用了缓存的旧仓库。

解决步骤：

1. 在 CI 脚本中增加 west update 步骤。
2. 固定 west.yml 的 manifest 版本，使用 west manifest --pin 锁定。
3. 在 CI 环境变量中显式设置 ZEPHYR_TOOLCHAIN_VARIANT=zephyr。

结果对比：修复后 CI 编译通过，固件烧录后传感器数据正常上报。该问题暴露了多仓库版本漂移的风险，也验证了 west 清单管理的重要性。

常见误区与总结复盘

• 误区一：直接修改 build/ 目录下的文件。build 目录是生成产物，任何手动修改都会被下次构建覆盖。正确做法是修改应用源码或 prj.conf。
• 误区二：忽略 west update。Zephyr 模块更新频繁，不执行 update 会导致 Kconfig 选项、设备树绑定过时。
• 误区三：混淆 prj.conf 与 board_defconfig。应用配置应放在 prj.conf，板卡默认配置放在 board_defconfig，后者不应被应用修改。
• 误区四：烧录时盲目使用 --runner。应先查看 west flash --help 或板卡文档，确认支持的 runner（如 jlink、openocd、pyocd）。

总结：掌握 west 工作流的核心在于理解其“配置输入 → CMake 生成 → Ninja 编译”的流水线，以及 west 对多仓库版本的控制能力。建议学员在本地搭建一个自定义板卡工程，尝试修改 .dts 和 Kconfig，观察构建系统的响应，这是快速提升 Zephyr 构建技能的最佳路径。