2、开发环境搭建：安装Zephyr SDK、west工具、依赖包，配置VS Code或命令行环境，验证Hello World

Zephyr RTOS 的开发和传统嵌入式开发（如 Keil、IAR + STM32CubeMX）有本质区别：它采用“源码树 + 构建系统 + 工具链”的模块化设计，所有构建动作通过 west 命令驱动，而编译链接则由 CMake 和 Ninja 在后台完成。搭建一套干净、可复现的开发环境，是后续所有实验和项目开发的基础。本章将带你从零开始，完成 Zephyr SDK、west 工具、系统依赖包的安装，并配置 VS Code 或纯命令行环境，最终编译并烧录 Hello World 示例到开发板上。

Zephyr 开发环境搭建链路 主机系统 Ubuntu 22.04 / macOS 系统依赖包 git cmake ninja gperf west 工具 pip install west Zephyr SDK 工具链 + 调试器 Zephyr 源码树（west init && west update） zephyr/ + modules/ + tools/ west build -b <board> app/ CMake + Ninja + 交叉编译 west flash → 串口监视 → Hello World! west build -t flash / 串口工具 minicom VS Code 扩展 C/C++ CMake Tools Cortex-Debug west 工作区

2.1 核心原理：west 与 Zephyr SDK 的分工

Zephyr 的构建体系可以概括为“一个调度器 + 一个编译器集合”。west（Zephyr’s meta-tool）是 Zephyr 项目的多仓库管理工具，它负责拉取 Zephyr 主仓库、模块仓库（如 HAL、加密库、文件系统）以及应用仓库，并统一调度构建命令。Zephyr SDK 则是一套预编译的交叉编译工具链，包含 GCC 编译器、GDB 调试器、Newlib 库以及 QEMU 模拟器，它针对 Zephyr 支持的多种架构（ARM、RISC-V、x86、Xtensa）提供了开箱即用的支持。

两者的关系可以类比为：west 是“项目经理”，负责协调所有代码仓库的版本和依赖；SDK 是“施工队”，提供具体的编译、链接和调试工具。在构建过程中，CMake 读取 CMakeLists.txt 和 prj.conf 配置，生成 Ninja 构建脚本，Ninja 再调用 SDK 中的交叉编译器生成目标固件。理解这一链路，有助于后续排查环境变量、工具链版本不匹配等问题。

组件 作用 典型安装位置 版本管理方式
west 多仓库管理、构建/烧录命令入口 ~/.local/bin/west pip 管理，随 Zephyr 版本更新
Zephyr SDK 交叉编译工具链、QEMU、调试器 ~/zephyr-sdk-0.16.x/ 独立压缩包，需手动配置环境变量
Zephyr 源码树 内核、驱动、子系统、HAL 源码 ~/zephyrproject/zephyr/ west init + west update 管理
系统依赖包 CMake、Ninja、gperf、dtc 等构建工具 /usr/bin/ apt/brew 管理

2.2 操作流程：从零搭建完整环境

以下流程以 Ubuntu 22.04 LTS 为例（macOS 用户只需将 apt 替换为 brew，路径略有差异）。请确保你的网络可以访问 GitHub 和 PyPI。

步骤 1：安装系统依赖包

sudo apt update
sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools python3-tk \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev

其中 dfu-util 用于后续通过 USB DFU 协议烧录固件，device-tree-compiler（dtc）用于编译设备树源文件，libsdl2-dev 是 QEMU 图形显示所需的库。

步骤 2：安装 west 工具

pip3 install --user west
export PATH=~/.local/bin:$PATH

验证安装：west --version，如果输出类似 West version: v1.2.0 则成功。建议将 export PATH=~/.local/bin:$PATH 写入 ~/.bashrc 以便持久生效。

步骤 3：获取 Zephyr 源码树

mkdir ~/zephyrproject && cd ~/zephyrproject
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.7.0
west update

west init 会创建一个 .west/config 配置文件并拉取主仓库；west update 则根据 manifest 文件拉取所有模块（如 modules/hal/stm32、modules/lib/cmsis 等）。这一步耗时较长，取决于网络状况。

步骤 4：安装 Zephyr SDK

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz
tar xf zephyr-sdk-0.16.8_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.8
./setup.sh -t all -h -c

setup.sh 脚本会自动将 SDK 路径写入 ~/.zephyrrc 文件，并安装 udev 规则（用于开发板 USB 识别）。安装完成后，执行 source ~/.zephyrrc 或重新登录终端使环境变量生效。

步骤 5：安装 Python 依赖

pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt

这一步会安装 pyelftools、pykwalify、canopen 等 Zephyr 构建和测试所需的 Python 包。

步骤 6：验证环境

cd ~/zephyrproject/zephyr
west build -b qemu_cortex_m3 samples/hello_world
west build -t run

如果一切正常，QEMU 模拟器会启动并输出 Hello World! qemu_cortex_m3。这是最快的验证方式，无需真实硬件。

经验提醒： 如果 west build 报错找不到 cmake 或 ninja，请检查 cmake --version 是否 ≥ 3.20。Zephyr 3.7 要求 CMake 3.20 以上，建议安装最新版：sudo pip3 install cmake --upgrade。

2.3 案例拆解：在真实开发板上运行 Hello World

下面以常见的 STM32F411CEU6 BlackPill 开发板为例，演示从编译到烧录的完整闭环。该板载 ST-Link 调试器，通过 USB 连接电脑。

背景与目标： 验证环境搭建正确性，并确认开发板可以正常烧录和串口输出。

操作步骤：

  1. 连接硬件： 使用 USB 线连接 BlackPill 的 USB 口到电脑，确认设备管理器中出现 STM32 STLink 设备。
  2. 编译固件： 
    cd ~/zephyrproject/zephyr
west build -b blackpill_f411ce samples/hello_world
  3. 烧录固件： 
    west flash
    该命令会自动调用 ST-Link 的烧录工具（OpenOCD 或 pyOCD），将生成的 build/zephyr/zephyr.bin 写入芯片 Flash。
  4. 查看串口输出： 
    minicom -D /dev/ttyACM0 -b 115200
    如果 minicom 未安装，使用 sudo apt install minicom。也可以使用 VS Code 的 Serial Monitor 插件。

结果与分析： 串口输出如下：

*** Booting Zephyr OS build v3.7.0 ***
Hello World! blackpill_f411ce

如果烧录失败，常见原因包括：

  • 权限问题： 执行 sudo usermod -aG dialout $USER 并重新登录，以获取串口访问权限。
  • ST-Link 驱动缺失： 在 Linux 下通常无需额外驱动，但需要安装 stlink-tools：sudo apt install stlink-tools。
  • 板型名称错误： 使用 west boards | grep blackpill 确认正确的 board 名称。
风险提示： 不要随意升级 Zephyr SDK 或 west 到最新版本，除非你确认与当前 Zephyr 源码版本兼容。SDK 与源码版本不匹配是导致编译错误的最常见原因之一。建议固定使用 west init -m ... --mr v3.7.0 指定的版本。

2.4 配置 VS Code 开发环境

虽然命令行完全够用，但 VS Code 可以提供代码补全、语法高亮、断点调试等增强体验。推荐安装以下扩展：

扩展名 用途 关键配置
C/C++（Microsoft） 代码补全、IntelliSense、调试 配置 compile_commands.json 路径
CMake Tools CMake 构建集成 设置 cmake.sourceDirectory 指向应用目录
Cortex-Debug ARM 芯片的调试支持 配置 OpenOCD 路径和接口
West Workspace 识别 west 工作区，提供快捷命令 自动检测 .west/config

关键配置步骤：

  1. 生成编译数据库： 在 west build 时添加 -d build 参数，Zephyr 会自动生成 build/compile_commands.json。然后在 VS Code 的 c_cpp_properties.json 中设置： 
    {
  "configurations": [
    {
      "name": "Zephyr",
      "compileCommands": "${workspaceFolder}/build/compile_commands.json",
      "intelliSenseMode": "linux-gcc-arm"
    }
  ]
}
  2. 配置调试器： 在 launch.json 中添加 Cortex-Debug 配置，指定 device 为 stm32f411ce，serverpath 指向 OpenOCD 可执行文件。
  3. 使用终端集成： 直接在 VS Code 终端中执行 west build 和 west flash，无需额外配置。
效率技巧： 在 ~/.bashrc 中添加以下别名，可以大幅提升操作效率： 
alias zb='cd ~/zephyrproject/zephyr && west build -b blackpill_f411ce'
alias zf='west flash'
alias zt='west build -t run'

2.5 常见误区与总结复盘

误区一：使用系统自带的 GCC 编译 Zephyr。 Zephyr 必须使用 SDK 中的交叉编译器，因为系统 GCC 不支持 Zephyr 的链接脚本和特定选项。如果 west build 报错 CMAKE_C_COMPILER 指向 /usr/bin/gcc，说明环境变量 ZEPHYR_SDK_INSTALL_DIR 未正确设置。

误区二：忽略 Python 依赖。 缺少 pyelftools 会导致构建时无法解析 ELF 文件，报错 ModuleNotFoundError。务必执行 pip3 install -r requirements.txt。

误区三：west update 后不重新构建。 如果更新了 Zephyr 源码或模块，旧的构建目录可能缓存了过时的配置。建议在 west update 后执行 rm -rf build 清理构建目录。

误区四：混淆 board 名称。 不同开发板的 board 名称差异很大，例如 blackpill_f411ce 和 nucleo_f411re 虽然都是 STM32F411，但引脚定义和外设配置不同。使用 west boards 命令可以列出所有支持的板型。

← 上一章 📖 返回目录 下一章 →