📚 课程目录第2章使用west管理多仓库项目

2. 使用west管理多仓库项目

任务目标

使用 Zephyr 的 west 工具创建一个自定义工作区（workspace），在其中同时管理 Zephyr 主仓库与一个应用程序仓库，并通过 west update 完成多仓库的同步拉取与更新。

环境准备

本案例需要已安装 west 及其依赖（pyelftools、packaging 等）。若尚未安装，执行：

pip install west

实现步骤与代码

创建一个清单仓库（manifest repository），在其中定义 west.yml 描述工作区包含的仓库列表。随后初始化工作区并执行同步。

1. 创建清单仓库并定义仓库列表

在工作目录下创建清单仓库，并写入 west.yml：

mkdir ~/my-workspace && cd ~/my-workspace
git init manifest
mkdir manifest && cd manifest
cat > west.yml << 'EOF'
manifest:
  projects:
    - name: zephyr
      url: https://github.com/zephyrproject-rtos/zephyr
      revision: v3.7.0
      west-commands: scripts/west-commands.yml
    - name: my-app
      path: app
      url: https://github.com/your-org/my-app
      revision: main
  self:
    path: manifest
EOF
git add west.yml && git commit -m "Add manifest with zephyr and app repos"

将 your-org/my-app 替换为你实际可访问的应用程序仓库地址。若暂无远程仓库，可在本地创建裸仓库用于验证（见下文“本地验证”）。

2. 初始化工作区

cd ~/my-workspace
west init -m https://github.com/your-org/manifest manifest

若清单仓库已在本地，也可使用本地路径：west init -m ./manifest。

3. 同步并更新所有仓库

cd ~/my-workspace
west update

该命令会根据 west.yml 中的定义，拉取 Zephyr 与 my-app 仓库到工作区根目录下（Zephyr 默认位于 zephyr/，my-app 因指定 path: app 而位于 app/）。

4. 验证工作区结构

west list

预期输出类似：

manifest  (manifest)
zephyr    (zephyr)
my-app    (app)

本地验证（无远程仓库时）

若你暂时没有可用的远程仓库，可在本地创建两个裸仓库模拟远程源，完成全流程验证：

# 创建模拟远程仓库
mkdir -p ~/remote/zephyr.git ~/remote/my-app.git
git init --bare ~/remote/zephyr.git
git init --bare ~/remote/my-app.git

# 将 west.yml 中的 url 改为本地路径后重新执行上述步骤
# 例如：url: /home/<user>/remote/zephyr.git

修改 west.yml 中的 URL 为本地路径后，重新执行 west init 与 west update，同样可通过 west list 验证。

通过条件

west update 命令无报错退出；
工作区根目录下同时存在 zephyr/ 与 app/ 两个目录，且各自包含对应仓库的代码文件（如 zephyr/Kconfig、app/src/main.c）；
west list 输出包含上述三个项目且路径正确。

常见问题

west update 报错“unable to resolve”：检查 west.yml 中 URL 是否可访问，或 revision 分支/标签是否存在。
仓库被拉取到错误路径：确认 west.yml 中 path 字段是否按需设置；未设置时默认使用 name 作为目录名。
修改 west.yml 后不生效：执行 west update 前先运行 west manifest --resolve 检查语法，再执行 west update。