📚 课程目录第2章开发环境搭建

2、开发环境搭建：在Linux/Windows上安装Zephyr SDK、west工具、依赖包，配置环境变量，验证hello world编译运行

Zephyr RTOS 的开发环境搭建是进入嵌入式实时系统世界的第一道门槛，也是后续所有实验、项目调试和产品化的基础。与传统的裸机开发（如直接使用 Keil 或 IAR）不同，Zephyr 采用了一套基于 Python 的 west 工作流和 CMake/Ninja 构建系统，同时依赖独立的交叉编译工具链（Zephyr SDK）。本章将围绕 Linux 与 Windows 双平台，系统讲解从零开始搭建完整开发环境的核心原理、具体操作流程、常见误区，并通过一个完整的 hello_world 编译运行案例，帮助读者建立一套可复现、可排障的环境搭建方法论。

上图展示了 Zephyr 开发环境的核心逻辑链路：主机操作系统提供基础运行环境，依赖包提供构建工具，Zephyr SDK 提供交叉编译能力，west 工作区组织源码与模块，最终通过 CMake/Ninja 生成可烧录的固件。理解这条链路，是后续所有操作的前提。

2.1 核心原理：west 工作流与 SDK 的角色

Zephyr 的构建系统并非传统的 Makefile 直接驱动，而是采用了一套分层设计。最底层是 CMake，负责描述构建目标、源文件、编译选项和链接脚本；Ninja 作为实际的构建执行器，负责并行编译和增量构建；而 west 则是 Zephyr 官方提供的多仓库管理工具，它基于 Python 实现，通过 manifest 文件（west.yml）统一管理 Zephyr 主仓库、可选模块（如 HAL 库、加密库）以及用户应用之间的依赖关系。这种设计使得 Zephyr 可以灵活地组合不同版本的模块，同时保持构建的可复现性。

Zephyr SDK 则是一个独立的工具链集合，它包含了针对不同架构（ARM、RISC-V、x86、Xtensa 等）的交叉编译器、GDB 调试器、QEMU 模拟器以及 OpenOCD 等调试工具。SDK 与 Zephyr 源码树是分离的，这意味着你可以同时维护多个版本的 SDK，并在不同项目间切换。SDK 的版本必须与 Zephyr 主仓库的版本兼容，通常 Zephyr 的发布说明中会明确标注推荐的 SDK 版本。例如，Zephyr 3.5 推荐使用 SDK 0.16.5-1，而 Zephyr 3.7 则推荐 SDK 0.17.0。

关键理解：west 管理的是“源码和模块”，SDK 提供的是“编译和调试工具”，而 CMake/Ninja 负责“构建编排”。三者缺一不可，且版本需要匹配。很多初学者只安装了 west 和 Zephyr 源码，却忘记安装 SDK，导致编译时找不到交叉编译器，这是最常见的错误之一。

2.2 操作流程：Linux 平台环境搭建（Ubuntu 22.04 为例）

Linux 是 Zephyr 开发的首选平台，其包管理器和 Shell 环境使得安装过程相对顺畅。以下是基于 Ubuntu 22.04 LTS 的完整安装步骤，适用于 x86_64 主机。

2.2.1 安装系统依赖包

首先更新软件源并安装基础工具。Zephyr 官方文档要求的最低 CMake 版本为 3.20，但 Ubuntu 22.04 自带的 CMake 为 3.22，满足要求。如果使用更旧的发行版，可能需要通过 pip 或源码安装新版 CMake。

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 \
  libsdl2-dev libmagic1

其中 device-tree-compiler（dtc）用于编译设备树源文件，dfu-util 用于 DFU 模式固件烧录，gperf 用于生成哈希查找表，这些都是 Zephyr 构建过程中可能调用的工具。如果计划使用 QEMU 运行模拟目标，还需要安装 libsdl2-dev 以支持图形显示。

2.2.2 安装 west 与 Python 依赖

west 通过 pip 安装，建议使用虚拟环境以避免污染系统 Python。但为了简化操作，也可以直接使用 pip3 install --user 安装到用户目录。

pip3 install --user west
# 验证安装
west --version

如果系统提示 west: command not found，通常是因为用户 bin 目录未加入 PATH。Ubuntu 的默认用户 bin 路径为 ~/.local/bin，需要将其添加到 ~/.bashrc 中：

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

2.2.3 获取 Zephyr 源码并初始化工作区

使用 west 初始化一个名为 zephyrproject 的工作区，该目录将包含所有相关仓库。

cd ~
west init zephyrproject
cd zephyrproject
west update

west init 会拉取 zephyr 仓库的默认 manifest，而 west update 会根据 manifest 拉取所有模块（如 modules/hal、modules/crypto 等）。这一步需要网络连接，且耗时较长，建议使用稳定的网络环境。如果网络受限，可以配置代理或使用镜像仓库。

2.2.4 安装 Zephyr SDK

SDK 以压缩包形式提供，需要手动下载并解压。以 SDK 0.16.5-1 为例：

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

setup.sh 脚本会安装 SDK 到默认路径 ~/.local/zephyr-sdk-0.16.5-1，并自动配置环境变量。如果希望自定义安装路径，可以在运行脚本前设置 ZEPHYR_SDK_INSTALL_DIR 环境变量。安装完成后，脚本会提示是否安装 udev 规则，建议选择“是”，以便后续使用 OpenOCD 调试时无需 root 权限。

2.2.5 配置环境变量

Zephyr 构建系统需要知道 SDK 的位置和 Zephyr 源码的路径。虽然 setup.sh 已经设置了部分变量，但为了持久化，建议在 ~/.bashrc 中显式添加：

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

zephyr-env.sh 脚本会设置 ZEPHYR_BASE 并更新 PATH，确保 west 和 cmake 能正确找到 Zephyr 的构建系统文件。完成上述配置后，重新打开终端或执行 source ~/.bashrc 使配置生效。

2.3 操作流程：Windows 平台环境搭建（WSL2 方式）

虽然 Zephyr 官方支持原生 Windows（通过 MSYS2 或 Chocolatey），但推荐使用 WSL2（Windows Subsystem for Linux 2）以获得最佳兼容性。WSL2 提供了一个完整的 Linux 内核，可以无缝运行 Ubuntu，且文件系统访问性能远优于 WSL1。

2.3.1 安装 WSL2 与 Ubuntu

在 Windows PowerShell（管理员模式）中执行：

wsl --install -d Ubuntu-22.04

安装完成后重启系统，首次启动 Ubuntu 时会要求创建用户名和密码。之后，所有 Linux 命令均在 WSL2 终端中执行，操作步骤与 2.2 节完全一致。唯一的区别是，WSL2 中的文件系统与 Windows 是隔离的，但可以通过 /mnt/c/ 访问 Windows 文件（如 /mnt/c/Users/你的用户名/）。

经验提醒：在 WSL2 中，建议将 Zephyr 工作区放在 Linux 原生文件系统（如 ~/zephyrproject）中，而不是放在 /mnt/c/ 下。因为跨文件系统访问（特别是编译时的大量小文件读写）会导致性能显著下降，甚至出现文件锁错误。

2.3.2 原生 Windows 的替代方案

如果必须使用原生 Windows，可以安装 MSYS2，然后通过 pacman 安装依赖：

pacman -S git cmake ninja gperf python3 dtc wget diffutils make

但原生 Windows 下，Zephyr SDK 的 setup.sh 无法直接运行，需要手动设置环境变量，且部分调试工具（如 OpenOCD）的 Windows 版本可能不完整。因此，除非有特殊需求，否则不推荐原生 Windows 开发。

2.4 案例拆解：hello_world 编译运行与验证

环境搭建完成后，最直接的验证方式就是编译并运行 Zephyr 自带的 hello_world 示例。本案例将使用 QEMU 模拟器运行，无需真实硬件，适合初学者快速验证环境正确性。

2.4.1 编译 hello_world

进入 Zephyr 源码目录下的示例程序位置，使用 west build 命令指定目标板卡。这里选择 qemu_cortex_m3 作为目标，它是一个模拟的 ARM Cortex-M3 开发板。

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

首次编译会触发 CMake 配置，并下载一些额外的依赖（如 modules/hal 中的固件库）。编译过程通常需要 1-3 分钟，取决于主机性能。如果编译成功，会在 build/zephyr/ 目录下生成 zephyr.elf 和 zephyr.hex 文件。

2.4.2 使用 QEMU 运行

编译完成后，使用 west build 的 -t run 目标直接启动 QEMU：

west build -t run

QEMU 窗口会弹出（或终端直接输出），并显示串口输出。预期输出如下：

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

看到 Hello World! 即表示环境搭建成功，交叉编译、链接、加载和模拟运行均正常。按 Ctrl+A 然后 X 可以退出 QEMU。

2.4.3 案例复盘与排障

如果编译或运行失败，请按以下顺序排查：

现象	可能原因	解决方案
`west: command not found`	pip 用户路径未加入 PATH	检查 `~/.local/bin` 是否在 PATH 中
`CMake Error: Could not find Zephyr`	`ZEPHYR_BASE` 未设置或错误	执行 `source ~/zephyrproject/zephyr/zephyr-env.sh`
`No such file or directory: 'arm-zephyr-eabi-gcc'`	SDK 未安装或路径错误	检查 `ZEPHYR_SDK_INSTALL_DIR` 指向的目录是否存在
`ninja: error: loading 'build.ninja': No such file`	CMake 配置失败	删除 `build` 目录，重新执行 `west build`
QEMU 无输出	串口配置错误或 QEMU 未正确启动	尝试 `west build -t run -- -serial mon:stdio`

风险提示：不要使用 sudo 运行 west build 或 west update。Zephyr 构建系统会创建大量缓存文件，使用 root 权限会导致文件所有权混乱，后续普通用户编译时会出现权限错误。如果已经误用 sudo，请执行 sudo chown -R 用户名:用户名 ~/zephyrproject 修复。

2.5 常见误区与总结复盘

在环境搭建过程中，初学者容易陷入以下几个误区，需要特别注意：

版本不匹配：Zephyr 主仓库、SDK、west 三者的版本必须兼容。例如，Zephyr 3.6 搭配 SDK 0.16.4 可能编译通过，但链接时出现未知符号。建议严格遵循官方发布说明中的版本组合。
忽略 udev 规则：在 Linux 下使用 OpenOCD 或 JLink 调试真实硬件时，如果未安装 udev 规则，会出现 Permission denied 错误。SDK 的 setup.sh 会询问是否安装，务必选择“是”。
环境变量未持久化：只在当前终端设置了 ZEPHYR_BASE，新开终端后失效。必须将 export 语句写入 ~/.bashrc 或 ~/.zshrc。
使用 Windows 路径操作 WSL 文件：在 WSL2 中，不要通过 /mnt/c/ 路径编译 Zephyr，否则会遇到符号链接和权限问题。
网络问题导致 west update 失败：如果 GitHub 访问不稳定，可以配置 git 代理，或使用 west update -f 强制重新拉取失败的仓库。