2、环境准备：安装 Zephyr SDK、West 工具、CMake、Ninja 及依赖，配置虚拟环境与 PATH

Zephyr RTOS 的构建系统并非传统的单一 Makefile 工程，而是基于 CMake 与 Ninja 的元构建体系，配合 West 这一多仓库管理工具完成模块化拉取与版本锁定。在开始编写任何应用代码之前，必须先搭建一套精确匹配的宿主工具链。环境准备的核心目标有三个：一是让 west 命令可用且能正确解析 manifest 文件；二是让 CMake 能找到 Zephyr 的构建脚本与 SDK 中的交叉编译器；三是确保 Ninja 作为底层构建器能够高效并行编译。本章将围绕工具链安装、虚拟环境隔离、PATH 配置与版本校验四个维度展开，帮助读者建立一套可复现、可迁移的 Zephyr 开发环境。

2.1 核心原理：构建系统的分层依赖模型

Zephyr 的构建系统设计遵循“分层解耦”原则。最底层是宿主机的原生工具链（gcc、make 等），但 Zephyr 并不直接调用它们，而是通过 CMake 生成 Ninja 构建文件，再由 Ninja 调度编译任务。这种间接层带来的好处是：开发者可以自由切换编译器（如 GCC、Clang）、构建器（Ninja、Make）而不影响应用代码。West 则处于最上层，它负责解析 west.yml manifest 文件，将 Zephyr 主仓库、hal 仓库、第三方模块按指定版本拉取到本地，并建立 zephyr 符号链接指向实际源码目录。

理解这一分层模型对排障至关重要。例如，当出现 CMake Error: The current CMakeCache.txt directory is different than the directory 时，往往是因为 CMake 缓存与当前构建目录不匹配，而非工具链本身的问题。另一个典型场景是：west build 成功但 cmake --build 失败，这通常意味着 West 的 manifest 解析正常，但 CMake 配置阶段未找到正确的 Zephyr 根目录或 SDK 路径。

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

以下流程以 Ubuntu 22.04 LTS 为例，macOS 与 WSL2 的差异会在注意事项中说明。整个流程分为五个阶段，每个阶段都有明确的验证点。

阶段一：安装系统级依赖

sudo apt update
sudo apt install -y 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

其中 device-tree-compiler（dtc）用于编译设备树源文件（.dts），libsdl2-dev 是 Zephyr 模拟器（如 QEMU 的图形输出）的可选依赖。若跳过 dtc，后续编译支持设备树的板卡时会报 dtc: command not found 错误。

阶段二：创建 Python 虚拟环境并安装 West

python3 -m venv ~/zephyr-venv
source ~/zephyr-venv/bin/activate
pip install --upgrade pip
pip install west

虚拟环境是强烈推荐的实践。Zephyr 的 West 工具及其依赖（如 pyelftools、packaging）可能与系统 Python 包冲突。使用虚拟环境后，west 命令被安装到 ~/zephyr-venv/bin/west，不会影响系统全局 Python。

阶段三：初始化 Zephyr 源码树

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

west init 会拉取 Zephyr 主仓库并生成 .west/config 配置文件。west update 则根据 west.yml 中的 manifest 拉取所有依赖模块（如 hal_stm32、cmsis 等）。首次执行 west update 可能需要 10-20 分钟，取决于网络状况。若网络不稳定，可配置 Git 代理或使用镜像仓库。

阶段四：安装 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

SDK 包含针对多种架构的交叉编译器（arm-zephyr-eabi-gcc、riscv64-zephyr-elf-gcc 等）、QEMU 模拟器以及主机端工具。setup.sh 的 -t all 表示安装所有工具链，-h 安装主机端工具，-c 创建符号链接到 /opt/zephyr-sdk。若磁盘空间有限，可只安装所需架构，例如 -t arm-zephyr-eabi。

阶段五：配置环境变量

将以下内容追加到 ~/.bashrc（或 ~/.zshrc）：

# Zephyr 环境配置
source ~/zephyr-venv/bin/activate
export ZEPHYR_BASE=~/zephyr-project/zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.16.8
export PATH="$HOME/.local/bin:$PATH"
export PATH="$ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin:$PATH"

其中 ZEPHYR_BASE 指向 Zephyr 源码根目录，CMake 通过它定位 zephyr/cmake 下的构建脚本。ZEPHYR_SDK_INSTALL_DIR 用于让 CMake 自动发现 SDK 中的工具链。最后一行 PATH 导出是为了让 qemu-system-arm 等模拟器命令可直接执行。

2.3 案例拆解：一次完整的版本兼容性排障

背景与约束：某团队在 CI 服务器上使用 Ubuntu 20.04，预装了 CMake 3.16.3 和 Python 3.8.10。他们尝试构建 Zephyr v3.5.0 的 hello_world 示例，但 west build 在 CMake 配置阶段失败。

初始现象：错误日志显示 CMake Error at CMakeLists.txt:30 (cmake_minimum_required): CMake 3.20.0 or higher is required. You are running version 3.16.3。

分析判断：Zephyr v3.5.0 的 CMake 最低版本要求为 3.20.0，而 CI 服务器的 CMake 版本过旧。团队最初尝试通过 pip install cmake 安装新版 CMake，但发现 pip 安装的 CMake 位于 ~/.local/bin，而系统 CMake 位于 /usr/bin，PATH 顺序导致系统旧版优先。

实际操作步骤：

1. 检查 PATH 顺序：echo $PATH，确认 ~/.local/bin 是否在 /usr/bin 之前。
2. 调整 PATH：在 ~/.bashrc 中显式添加 export PATH="$HOME/.local/bin:$PATH"，确保用户级工具优先。
3. 验证版本：cmake --version 应输出 3.20.0 或更高。
4. 清理旧缓存：删除 build/ 目录，重新执行 west build -b qemu_cortex_m3 hello_world。

结果对比：修复后构建成功，生成 build/zephyr/zephyr.elf。但团队发现 Ninja 版本仍为 1.10.1，低于 Zephyr 推荐的 1.10.2。虽然当前示例未触发问题，但后续编译大型项目时可能出现并行构建竞态条件。于是他们通过 pip install ninja 升级到 1.11.1，并验证 ninja --version。

风险与代价：升级 CMake 和 Ninja 后，CI 服务器上其他依赖旧版本 CMake 的项目可能受影响。团队最终决定在 CI 脚本中使用 Docker 容器固定工具链版本，避免相互干扰。

复盘经验：Zephyr 对工具链版本有硬性要求，建议在项目根目录维护 CMakeLists.txt 中的 cmake_minimum_required 与 CI 配置文件同步更新。同时，使用 west config 命令可以查看当前构建配置，辅助定位问题。

2.4 常见误区与总结复盘

总结复盘：环境准备阶段的核心产出物是三个可验证的路径：west 命令路径、ZEPHYR_BASE 路径、ZEPHYR_SDK_INSTALL_DIR 路径。建议在完成安装后执行以下验证脚本：

#!/bin/bash
# 环境验证脚本
echo "=== West 版本 ==="
west --version
echo "=== CMake 版本 ==="
cmake --version | head -n1
echo "=== Ninja 版本 ==="
ninja --version
echo "=== ZEPHYR_BASE ==="
echo $ZEPHYR_BASE
echo "=== SDK 目录 ==="
ls $ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin/arm-zephyr-eabi-gcc
echo "=== 测试构建 ==="
cd ~/zephyr-project
west build -b qemu_cortex_m3 samples/hello_world --pristine

若测试构建成功并输出 Hello World! qemu_cortex_m3，则说明环境完全就绪。后续章节中，所有构建命令都将基于这套已验证的环境执行。