3、开发环境搭建：安装Zephyr SDK、west工具、配置VS Code、编译第一个Hello World

Zephyr RTOS 的开发体验高度依赖其命令行工具链与构建系统。与传统的嵌入式 IDE（如 Keil、IAR）不同，Zephyr 采用 west（Zephyr's meta-tool）作为多仓库管理与构建入口，配合 CMake 和 Ninja 完成编译。本章将带领你从零开始搭建一套可用的 Zephyr 开发环境，涵盖 SDK 安装、west 配置、VS Code 集成，并最终编译运行经典的 Hello World 示例。整个过程以 Ubuntu 22.04 LTS 为演示平台，但所有命令与思路同样适用于 macOS 和 WSL2 环境。

Zephyr 开发环境搭建与构建链路 1. 基础工具 CMake / Ninja / Python3 2. Zephyr SDK 工具链 / QEMU / 调试器 3. west 工具 多仓库管理 / 构建 4. VS Code CMake 插件 / 调试 west build -b qemu_cortex_m3 hello_world CMake 配置 → 编译链接 → 生成 zephyr.elf / zephyr.bin west build -t run（QEMU 模拟运行） 串口输出：Hello World! board: qemu_cortex_m3 验证：west flash（烧录到真实板卡）

上图展示了 Zephyr 开发环境的整体构建链路：从基础工具链到 SDK、west、IDE，再到编译与运行验证。下面我们将按照实际操作顺序，逐一深入每个环节。

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

理解 Zephyr 的构建体系，首先需要厘清 west 与 Zephyr SDK 的职责边界。Zephyr 项目本身不是一个单一代码仓库，而是由 zephyr 主仓库、hal（硬件抽象层）、modules（第三方模块）以及众多板级支持包组成的多仓库工程。west 正是为了解决多仓库的版本同步与协作而生的工具，它通过一个名为 west.yml 的清单文件，精确锁定每个仓库的 Git 提交 ID，确保所有开发者使用完全一致的代码版本。

而 Zephyr SDK 则是一个独立的工具链集合，它包含了针对不同 CPU 架构（ARM、RISC-V、x86 等）的交叉编译器（如 arm-zephyr-eabi-gcc）、GDB 调试器、QEMU 模拟器以及 Newlib 库。SDK 与 west 相互独立：west 负责“拉取代码和发起构建”，SDK 负责“实际编译和链接”。这种设计使得 Zephyr 可以灵活地支持不同的编译器版本，甚至可以使用系统自带的 GCC（针对原生 POSIX 架构）。

关键认知： 在 Zephyr 中，west build 命令会调用 CMake 读取 CMakeLists.txt，CMake 再根据 ZEPHYR_TOOLCHAIN_VARIANT 环境变量找到 SDK 中的编译器。因此，安装 SDK 后必须正确设置环境变量，否则构建系统会报“找不到工具链”的错误。

3.2 操作流程：从零安装与验证

以下步骤在 Ubuntu 22.04 上验证通过，请确保你的系统已安装 git、curl 和 cmake（版本不低于 3.20）。

3.2.1 安装基础依赖与 Zephyr SDK

  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 \
  python3-wheel xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev
  1. 下载并安装 Zephyr SDK： 推荐使用版本 0.16.5-1（与 Zephyr 3.5 LTS 兼容）。
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5-1/zephyr-sdk-0.16.5-1_linux-x86_64.tar.xz
tar xf zephyr-sdk-0.16.5-1_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.5-1
./setup.sh -t all -h

setup.sh 脚本会将 SDK 路径写入 ~/.zephyrrc 文件，并安装 udev 规则（用于 USB 设备访问）。安装完成后，将以下内容添加到 ~/.bashrc 中：

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.5-1
source ~/zephyr-sdk-0.16.5-1/zephyr-env.sh

执行 source ~/.bashrc 后，运行 arm-zephyr-eabi-gcc --version 验证编译器是否可用。

3.2.2 安装 west 并获取 Zephyr 源码

west 是一个 Python 包，建议使用虚拟环境隔离，避免污染系统 Python。

python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
pip install west

接下来，初始化 Zephyr 工作区（以 ~/zephyrproject 为例）：

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

west update 会根据 west.yml 拉取所有依赖仓库（约 1.5GB 数据），请耐心等待。完成后，安装 Python 依赖：

pip install -r zephyr/scripts/requirements.txt
常见陷阱： 如果 west update 过程中出现网络超时，可以设置 Git 代理或使用国内镜像源。另外，务必确保 west 命令在虚拟环境中执行，否则会提示找不到命令。

3.3 案例拆解：编译并运行 Hello World

环境就绪后，我们以 hello_world 示例为目标，演示完整的编译、运行与调试流程。该示例位于 zephyr/samples/hello_world 目录。

3.3.1 编译针对 QEMU 的版本

QEMU 是 Zephyr 内置的 CPU 模拟器，无需真实硬件即可验证程序逻辑。执行以下命令：

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

构建过程会输出大量日志，最终生成 build/zephyr/zephyr.elf 文件。关键输出信息如下：

-- Board: qemu_cortex_m3
-- Found toolchain: zephyr (Zephyr SDK)
-- Found DTC: /usr/bin/dtc
-- Generating done
-- Build files have been written to: /home/user/zephyrproject/zephyr/build

3.3.2 在 QEMU 中运行

使用 west build -t run 命令启动模拟执行：

west build -t run

此时终端会切换到 QEMU 窗口，并输出：

*** Booting Zephyr OS build v3.5.0 ***
Hello World! board: qemu_cortex_m3

按 Ctrl+A 然后按 X 退出 QEMU。这一过程验证了工具链、构建系统和模拟器的正确性。

3.3.3 针对真实板卡的编译与烧录

若你手头有 Nordic nRF52840DK 或 STM32F4 系列开发板，可指定对应的板卡名称。以 nrf52840dk_nrf52840 为例：

west build -b nrf52840dk_nrf52840 samples/hello_world
west flash

west flash 会自动调用板卡对应的烧录工具（如 pyOCD、JLink 或 openocd）。烧录成功后，打开串口终端（如 screen /dev/ttyACM0 115200），即可看到同样的 Hello World 输出。

构建目标命令适用场景产物
QEMU 模拟west build -b qemu_cortex_m3无硬件时的功能验证zephyr.elf
真实板卡west build -b <board_name>硬件调试与产品开发zephyr.hex / zephyr.bin
单元测试west build -b native_posix在 Linux 上运行测试可执行文件

3.4 配置 VS Code 实现高效开发

VS Code 并非 Zephyr 的必需组件，但通过合理配置可以大幅提升代码阅读与调试效率。推荐安装以下扩展：C/C++（微软官方）、CMake Tools、cortex-debug（用于嵌入式调试）。

3.4.1 生成 compile_commands.json

为了让 IntelliSense 正确解析 Zephyr 的头文件路径，需要在构建时导出编译数据库。在 zephyr 目录下创建 .vscode/settings.json：

{
  "cmake.sourceDirectory": "${workspaceFolder}/zephyr",
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "cmake.configureArgs": [
    "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"
  ],
  "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
}

重新运行 west build 后，会在 build/ 目录生成 compile_commands.json。CMake Tools 插件会自动读取该文件，从而提供准确的代码补全与跳转。

3.4.2 配置调试器（以 QEMU 为例）

在 .vscode/launch.json 中添加如下配置，即可在 VS Code 中打断点调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug QEMU",
      "type": "cortex-debug",
      "request": "launch",
      "servertype": "qemu",
      "executable": "${workspaceFolder}/build/zephyr/zephyr.elf",
      "device": "cortex-m3",
      "gdbTarget": "localhost:3333"
    }
  ]
}

启动调试前，需在终端运行 west build -t debugserver 启动 QEMU 的 GDB 服务端口。

经验之谈： 对于初学者，建议先在 QEMU 上完成所有实验，熟悉 Zephyr 的设备树（Device Tree）和驱动模型后，再切换到真实硬件。这能避免因硬件连接问题而干扰对 RTOS 机制的理解。

3.5 常见误区与总结复盘

在搭建环境的过程中，开发者常遇到以下几类问题，这里逐一剖析原因与对策。

  • 误区一：忘记激活 Python 虚拟环境。 现象是 west: command not found。解决：每次打开新终端，先执行 source ~/zephyrproject/.venv/bin/activate。
  • 误区二：SDK 版本与 Zephyr 版本不匹配。 现象是编译时出现 unsupported GNU C version 错误。解决：查阅 Zephyr 官方文档的 Supported Toolchains 章节，使用对应版本的 SDK。
  • 误区三：修改了 west.yml 后未执行 west update。 现象是编译时提示缺少某个模块。解决：每次拉取远程更新后，务必执行 west update 保持子仓库同步。
  • 误区四：在 Windows 上直接使用 CMD 而非 WSL。 Zephyr 官方不支持原生 Windows 构建，必须使用 WSL2 或虚拟机。
← 上一章 📖 返回目录 下一章 →