工作区、清单与版本更新

本页依据文档基线与后续更新中记录的 Zephyr main 快照更新。

工作区结构

zephyrproject/
├── .west/config
├── .venv/
├── zephyr/
│   └── west.yml
├── modules/
├── bootloader/
└── app/

.west 的父目录是工作区顶层。.west/config 中的 manifest.path 指向清单仓库，官方布局中通常是 zephyr；manifest.file 默认是 west.yml。清单声明各项目的地址、路径和修订版，也可能导入其他清单。 app 是这里示意的应用目录，不会因为处于工作区中就自动成为 west 管理的项目。

初始化

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

west init 创建工作区并获取清单仓库；west update 按当前清单获取模块。 --mr 可以是分支、发布标签或提交号。main 会变化，需要复现时使用固定提交。

查看工作区

west topdir
west list
west status
west manifest --resolve
west manifest --freeze > manifest-frozen.yml

--resolve 展开清单导入；--freeze 输出冻结项目修订版的清单。还应单独记录应用和清单仓库的提交、未提交补丁及 SDK 版本，冻结模块清单不等于保存了整个开发环境。

更新已有工作区

west update 根据当前本地清单更新项目，不会替你把 Zephyr 清单仓库切换到最新版本。升级前查看 git status 和 west status，保存本地修改，再显式选择 Zephyr 修订版。下面以切换到本次核对提交为例：

cd ~/zephyrproject/zephyr
git status
git fetch origin
git switch --detach 02d743889396e724d53be61e4fe34c484c1d5a97
west update
west packages pip --install
west zephyr-export
west sdk install

Windows 使用 Windows 原生开发环境中的平台依赖安装命令。切换后清理或新建构建目录，按目标版本的迁移指南更新应用。如需在 Zephyr 源码上开发，可从选定提交创建自己的分支。

构建、烧录与调试

以下命令从 Zephyr 源码目录执行：

west build -p always -b qemu_cortex_m3 -d build/qemu samples/hello_world
west build -d build/qemu -t run
west build -d build/qemu -t menuconfig

对真实开发板使用其目标名和独立构建目录，再执行 west flash -d <构建目录>、west debug -d <构建目录>。 runner、连接方式和厂商工具要求以该开发板文档为准。

镜像与模块

不能通过只克隆 Zephyr 主仓库来代替完整工作区。若只下载部分模块，应理解应用依赖和清单的 group/filter 机制；任何镜像都必须能提供当前清单指定的修订版。版本错配时先检查清单与模块提交，再调整网络设置或镜像地址。