工作区与工具链

本页统一使用 ~/Projects/zephyr-main-workspace。旧的 zephyr-workspace 是 v4.2.0 实验环境，不在两套目录之间交叉执行命令。

本页是安装与初始化操作流程。west 的工作区模型、manifest、构建和烧录命令详见 west 使用指南。

工作区结构

zephyr/ 是一个仓库，modules/ 下的库各自也可能是仓库。west 读取 manifest，决定每个仓库应放在哪里、检出什么版本。.west/config 指向 manifest 所在位置。

应用 Git 仓库负责保存自己的代码；west 工作区负责装配这些依赖。两者不是同一个概念。

初始化工作区

先完成主机依赖安装。以下只在尚未初始化的新目录执行：

mkdir -p ~/Projects/zephyr-main-workspace
python3.12 -m venv ~/Projects/zephyr-main-workspace/.venv-py312-main
source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
python -m pip install west
west init -m https://github.com/zephyrproject-rtos/zephyr \
  --mr 52b48529aecc3ad0ef9b159996bdb5d2b3e5b794 \
  ~/Projects/zephyr-main-workspace
cd ~/Projects/zephyr-main-workspace
west update
west packages pip --install
west zephyr-export

这里选择官方 main 上已经用于本机编译验证的提交，版本号显示为 4.4.99。它不是“今天最新提交”，固定提交是为了让读者能复现教程。要试新的 main，应另做版本升级并重新验证，不让教程依赖每天变化。

命令	做什么	不做什么
west init	初始化工作区并取得 manifest 仓库	不完成全部模块下载
west update	按清单取得启用模块的版本	不安装系统开发包
west packages pip --install	安装源码要求的 Python 依赖	不安装 SDK
west zephyr-export	向 CMake 注册这个 Zephyr 包	不编译固件

west update 失败时先解决下载问题。安装 Python 包失败时，查看首个实际错误，不要因此重新执行 west init。缺少 libusb、udev 或 gcc 的处理见 Fedora 历史排错与串口及构建排错。

SDK 与 ESP32 模块

cd ~/Projects/zephyr-main-workspace/zephyr
west sdk install --help
west sdk install --version 1.0.1 --install-base ~/.local/opt
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
west blobs fetch hal_espressif

本基线使用 SDK 1.0.1。SDK 很大，安装选项可限制目标工具链；第一次学习先保持上面一致，避免少装 ESP32-S3 所需工具链。ESP32 芯片 HAL 由 west 管理，部分功能需要上游二进制 blobs，本仓库不复制这些二进制。

工具与版本检查

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip check
west topdir
west --version
git -C ~/Projects/zephyr-main-workspace/zephyr rev-parse HEAD

west topdir 应指向 main 工作区。解释器路径应在该工作区的虚拟环境下。pip check 只检查已安装包的依赖关系，不能代替前面的安装成功记录。

多个工作区并存时，CMake 注册信息和 ZEPHYR_BASE 环境变量都可能影响源码选择。本站命令从目标工作区的 zephyr 目录运行，构建日志仍需确认 Zephyr version 和源码路径。

激活环境

只需要重新进入环境，不需要每天更新依赖：

source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
cd ~/Projects/zephyr-main-workspace/zephyr
west topdir

随后可运行 Hello World 快速体验，或直接开始自己的最小应用。

保存依赖状态

cd ~/Projects/zephyr-main-workspace/zephyr
git rev-parse HEAD
west manifest --freeze --active-only -o ../west-manifest-frozen.yml

使用 active-only 可跳过未启用、未克隆的可选模块。若启用模块也未克隆，应先完成其下载。-o 避免 shell 重定向在失败前截空文件。

冻结清单之外，还应记录主 Zephyr 提交、SDK 版本以及自己的应用提交。仅记录“main”无法说明几个月后要检出哪份代码。

来源：west 工作区、本机 zephyr/west.yml 与 scripts/west_commands/sdk.py。

工作区结构​

初始化工作区​

SDK 与 ESP32 模块​

工具与版本检查​

激活环境​

保存依赖状态​