3、开发环境搭建：安装Zephyr SDK、west工具、CMake/Ninja、VS Code配置

Zephyr RTOS 的工程构建体系与传统的 MCU 开发（如 Keil、IAR）有本质区别：它采用 CMake 构建系统 + Ninja 编译调度 + west 多仓库管理 + Zephyr SDK 工具链 的四层架构。理解这四层的关系是搭建环境的前提，否则在后续编译、调试、移植 BSP 时会频繁遇到“找不到工具链”“west 模块缺失”“CMake 缓存不一致”等环境类问题。本章将带你从零开始，在 Ubuntu 22.04 LTS 主机上完整搭建一套可投入实际项目开发的 Zephyr 环境，并完成 VS Code 的工程化配置。

上图展示了 Zephyr 开发环境的完整链路。在实际项目中，west 是最高层入口，它负责拉取和管理多个 Git 仓库（包括 Zephyr 内核、模块、第三方库）；CMake 读取各层的 CMakeLists.txt 生成构建规则；Ninja 负责高效并行编译；Zephyr SDK 提供针对特定架构的交叉编译器、调试器和 QEMU 模拟器。下面我们按步骤逐一搭建。

3.1 安装系统依赖与基础工具

在安装 Zephyr SDK 之前，需要先确保主机具备编译 Zephyr 所需的系统级依赖。Zephyr 官方支持 Ubuntu、Fedora、macOS 和 Windows（WSL2），本课程以 Ubuntu 22.04 LTS 为例。打开终端，执行以下命令安装基础包：

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

这里需要特别说明：cmake 和 ninja-build 是构建系统的核心，Ubuntu 22.04 自带的 CMake 版本为 3.22.1，满足 Zephyr 3.4+ 的最低要求（3.20.0）。如果你需要更新的 CMake 版本，可以通过 pip 安装：pip3 install --user cmake。另外，ccache 是编译缓存工具，在反复修改代码后重新编译时能显著提速，建议务必安装。

3.2 安装 west 工具与 Zephyr 源码

west 是 Zephyr 的元工具（meta-tool），它通过 manifest 文件管理多个 Git 仓库。首先使用 pip 安装 west：

pip3 install --user west

安装完成后，需要将 west 的可执行路径加入 PATH。通常 pip 安装到用户目录的 ~/.local/bin，执行：

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

接下来初始化 Zephyr 工作空间。建议创建一个专用目录（例如 ~/zephyrproject），然后执行：

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

west init 会拉取 Zephyr 主仓库并创建 .west/config 配置文件；west update 则根据 manifest 文件拉取所有模块（如 CMSIS、HAL 厂商库、LittleFS 等）。这一步需要网络状况良好，如果网络不稳定，可以配置代理或使用国内镜像源。初始化完成后，目录结构如下：

~/zephyrproject/
├── .west/
│   └── config          # west 配置文件
├── zephyr/             # Zephyr 内核主仓库
├── modules/            # 第三方模块（HAL、加密库等）
├── bootloader/         # MCUboot 等引导程序
└── tools/              # 调试工具（可选）

3.3 安装 Zephyr SDK

Zephyr SDK 是一套预编译的交叉编译工具链，包含 GCC、GDB、OpenOCD、QEMU 等。它针对不同 CPU 架构提供了独立的工具链。下载并安装 SDK：

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

参数说明：-t all 表示安装所有架构的工具链（包括 arm、riscv、x86、xtensa、sparc 等）；-h 安装主机端工具（如 QEMU、OpenOCD）；-c 安装 CMake 包配置文件。安装完成后，SDK 会被注册到 CMake 的包搜索路径中，Zephyr 构建系统会自动找到它。

安装完成后，需要设置环境变量 ZEPHYR_TOOLCHAIN_VARIANT 和 ZEPHYR_SDK_INSTALL_DIR。编辑 ~/.bashrc：

echo 'export ZEPHYR_TOOLCHAIN_VARIANT=zephyr' >> ~/.bashrc
echo 'export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.5' >> ~/.bashrc
source ~/.bashrc

验证 SDK 是否安装成功：

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

如果构建成功，会生成 build/zephyr/zephyr.elf 文件。接着运行：

west build -t run

如果终端输出 Hello World! qemu_cortex_m3，说明整个工具链已经打通。

3.4 配置 VS Code 开发环境

VS Code 是当前嵌入式开发的主流 IDE，配合 Zephyr 插件可以实现语法高亮、代码补全、编译调试一体化。首先安装 VS Code 扩展：

• ms-vscode.cpptools：C/C++ 语言支持
• marus25.cortex-debug：Cortex-M 调试插件
• zephyrproject-rtos.zephyr-ide：Zephyr 官方 IDE 扩展（提供工程管理、构建任务）
• ms-python.python：Python 支持（west 命令依赖）

安装完成后，需要配置 settings.json 和 c_cpp_properties.json。打开 VS Code 的命令面板（Ctrl+Shift+P），输入 Zephyr: Build 可以触发构建。为了获得完整的代码补全和语法检查，需要生成 compile_commands.json 文件。在 Zephyr 工程目录下执行：

west build -b qemu_cortex_m3 samples/hello_world -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

构建完成后，将生成的 build/compile_commands.json 软链接到工程根目录：

ln -s build/compile_commands.json compile_commands.json

然后在 .vscode/c_cpp_properties.json 中配置：

{
  "configurations": [
    {
      "name": "Zephyr",
      "compileCommands": "${workspaceFolder}/compile_commands.json",
      "intelliSenseMode": "linux-gcc-arm"
    }
  ],
  "version": 4
}

这样 VS Code 就能根据实际的编译参数提供精确的代码补全和跳转功能。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug STM32F4",
      "cwd": "${workspaceFolder}",
      "executable": "${workspaceFolder}/build/zephyr/zephyr.elf",
      "request": "launch",
      "type": "cortex-debug",
      "servertype": "openocd",
      "configFiles": ["board/st_nucleo_f4.cfg"],
      "searchDir": ["${workspaceFolder}/build/openocd"]
    }
  ]
}

3.5 实战案例：从零构建一个 Blinky 工程并烧录到开发板

下面我们通过一个完整的案例，将上述环境串联起来。假设你手上有一块 STM32F411 Nucleo-64 开发板（板载 ST-Link 调试器）。目标：编译 Zephyr 自带的 Blinky 示例，烧录到开发板并观察 LED 闪烁。

步骤 1：创建工程并编译

cd ~/zephyrproject
west build -b nucleo_f411re zephyr/samples/basic/blinky --pristine

这里 --pristine 表示清除之前的构建缓存，确保全新编译。构建过程会输出编译日志，最终生成 build/zephyr/zephyr.bin。

步骤 2：烧录到开发板

将 Nucleo 开发板通过 USB 连接到电脑，确认系统识别到 ST-Link 设备（lsusb 可以看到 STMicroelectronics ST-LINK）。然后执行：

west flash

west 会自动调用 OpenOCD 并烧录 zephyr.bin 到开发板 Flash。烧录成功后，开发板上的 LED（通常为 LD2，连接在 PA5 引脚）会以 100ms 间隔闪烁。

步骤 3：调试验证

如果 LED 没有闪烁，首先检查 prj.conf 中的 GPIO 配置是否正确。打开 zephyr/samples/basic/blinky/prj.conf，可以看到：

CONFIG_GPIO=y

然后检查 src/main.c 中的 LED 引脚定义：

#define LED0_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);

对于 nucleo_f411re 板，led0 在 boards/arm/nucleo_f411re/nucleo_f411re.dts 中定义为 PA5。如果硬件连接正确，问题通常出在设备树配置上。

步骤 4：使用 VS Code 调试

在 VS Code 中打开 ~/zephyrproject/zephyr 目录，按 F5 启动调试。Cortex-Debug 插件会连接 OpenOCD，并加载 zephyr.elf。你可以在 main.c 中设置断点，单步执行，观察 GPIO 寄存器的变化。

3.6 常见误区与总结复盘

在搭建环境的过程中，初学者最容易犯以下错误：

• 使用系统自带的 GCC 编译 Zephyr：Zephyr 必须使用 Zephyr SDK 中的交叉编译器，系统 GCC 无法生成正确的链接脚本和启动文件。
• 忽略 west 的 manifest 版本锁定：直接修改 zephyr 仓库的代码或分支，会导致与模块版本不匹配，出现莫名其妙的编译错误。
• CMake 缓存残留：更换开发板或修改 prj.conf 后，没有执行 --pristine 清理，导致旧配置残留。
• 环境变量未持久化：每次打开新终端都要重新设置 ZEPHYR_BASE 或 ZEPHYR_SDK_INSTALL_DIR，建议写入 ~/.bashrc。