Zephyr 高阶实践：彻底讲透 west 构建系统、模块管理与跨平台 CI/CD 配置

本文是 Zephyr 项目管理体系的高阶解构与实战指南，全面覆盖 west 构建系统原理、模块解耦与 west.yml 多模块维护机制，结合企业级多平台 CI/CD 落地流程，深入讲解如何构建可靠、可维护、跨芯片架构的一体化 Zephyr 工程。

一、为什么 Zephyr 需要 west 构建系统？

背景：Zephyr 是一个高度模块化、多平台适配的嵌入式操作系统

• 支持几十种芯片架构（ARM Cortex-M, RISC-V, x86, ARC...）

• 拥有多个模块（主仓库 + HAL + BLE + FS + 模拟器等）

• 模块分布在数十个 Git 仓库，版本组合复杂

• 项目构建需要严格依赖关系管理 + 工具链对齐 + 平台定制

west 的出现就是为了“模块调度 + 工具链封装 + 构建流程标准化”，将 Zephyr 从分散代码堆变成结构化工程体系。

二、west 的本质：一个多仓库构建调度与模块集成系统

🧱 west 工具包含三层能力：

它像 git + make + repo 的组合体，将分散的构建指令和模块依赖整合成一套工具集。

三、west 工作流结构梳理

一个完整的 west 工程流程图：

初始化阶段：
    git clone zephyr
    west init -l zephyr/
    west update

构建阶段：
    west build -b <board> <app_dir>
    west flash / debug / run

模块维护：
    west.yml → module1, module2...
    west update  → 自动拉取模块

CI/CD 自动化：
    west manifest --freeze
    构建多个平台，归档 firmware + .config

工程目录典型结构：

zephyrproject/
├── .west/                  ← 工程元数据
├── zephyr/                 ← 主仓库，含 kernel、build logic、west.yml
├── modules/hal/stm32/      ← HAL 子模块（通过 west.yml 管理）
├── modules/lib/lvgl/       ← 第三方 GUI 库
├── tools/                  ← 构建依赖工具如 dtc
├── app/                    ← 自己的业务代码与 CMakeLists.txt

四、west.yml：项目大脑

Zephyr 模块化依赖的核心就在于 manifest 文件 west.yml。这是整个项目的 模块清单 + 结构定义 + 依赖锁定点。

west.yml 最小示例：

manifest:
  projects:
    - name: hal_stm32
      path: modules/hal/stm32
      revision: v1.11.0
      url: https://github.com/zephyrproject-rtos/hal_stm32
  self:
    path: zephyr

核心字段解构：

模块继承（import）机制：

import:
  path-prefix: modules/lib
  name-allowlist:
    - lvgl

用于将其他仓库的 manifest 导入，并自动引入其模块。

五、构建机制详解（west build）

典型构建流程（示意图）：

west build
  ├──> cmake 配置
  │    └──> 生成 build.ninja
  ├──> Kconfig 阶段
  │    └──> .config + autoconf.h
  ├──> DTS 阶段
  │    └──> zephyr.dts + devicetree_unfixed.h
  └──> ninja 构建（最终生成 elf / hex / bin）

支持目标（-t）构建命令：

west build -t flash       # 编译+烧录
west build -t menuconfig  # 图形化配置界面
west build -t ram_report  # 显示 RAM 分布情况
west build -t size        # 显示镜像大小

构建多平台建议：

• 每个 board 使用不同构建输出目录：-d build/<board>

• 使用 prj.conf + overlay.conf 管理配置差异

• 可使用多个 app 源目录，对应不同项目

六、CI/CD 构建系统设计

构建目标：

• 每次 push / PR 自动完成构建验证

• 支持多个目标板（STM32、nRF、ESP）并行构建

• 构建产物包括：hex、elf、.config、map、版本信息

• 对于发布版本，执行签名 + OTA + Release 上传

推荐工具链组件：

七、CI 实战配置案例（GitHub Actions）

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        board: [nucleo_f401re, nrf52840dk_nrf52840]

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Install west & SDK
      run: |
        python3 -m venv venv
        source venv/bin/activate
        pip install west
        wget https://.../zephyr-sdk.run && chmod +x *.run && ./zephyr-sdk.run
        export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
        export ZEPHYR_SDK_INSTALL_DIR=$PWD/zephyr-sdk

    - name: Build
      run: |
        source venv/bin/activate
        west init -l .
        west update
        west build -b ${{ matrix.board }} app -p always

    - name: Archive firmware
      uses: actions/upload-artifact@v3
      with:
        name: firmware-${{ matrix.board }}
        path: build/zephyr/zephyr.hex

八、模块版本锁定与 freeze 策略

对于大型团队协作、多模块交错开发场景，保持模块版本一致性至关重要。

推荐做法：

1. 所有模块统一从 west.yml 获取版本

2. PR 中若需修改模块版本，必须更新 revision 字段

3. 发布版本前执行：

west manifest --freeze > manifest.lock.yml

1. CI 中使用冻结版本确保构建可复现

2. 上游模块变更触发主仓构建任务，通过 GitHub webhook 实现模块间集成

九、多平台协作与私有模块接入策略

推荐结构：

zephyrproject/
├── west.yml
├── modules/hal/
│   ├── hal_stm32
│   └── hal_esp32
├── modules/ble/
│   ├── my_ble_stack
├── modules/drivers/
│   ├── adc_ext
│   └── led_ctrl

私有模块接入技巧：

• 统一 remote 地址管理：

remotes:
  - name: mycorp
    url-base: https://gitee.com/mycorp

• 设置子模块专属路径：

projects:
  - name: my_drv
    remote: mycorp
    path: modules/drivers/my_drv
    revision: main

十、总结与建议

只有掌握了 west 的工作原理、模块机制与构建流程，你才真正拥有了构建大规模 Zephyr 系统的能力。

下一篇将进入 Zephyr DTS 设备树、板卡支持包（BSP）、驱动扩展框架的高级开发主题，敬请期待。