Zephyr 教学工作区 · 课程 0001 · 约 25 分钟 · 前置:无 · 2026-09-24

环境体检与 west 就位

为什么是这一步

使命里判断这条线的第一个理由是"纯 Python / Markdown,Windows 上就能跑"。 但"能跑"的前提是环境认得这个仓库。实测你的克隆是部分克隆 + 稀疏检出 (blob:none + sparseCheckout=true),只检出了文档相关的少数文件 —— 所以 west 连 manifest 都读不了(会报 submanifests: file not found)。 这一节先把这条路打通。

最小知识:三条

1. west 不是编译器,是"元工具"。它读 west.yml 这份 manifest, 决定"这个项目由哪些 git 仓库组成、各自该在哪个版本",然后替你批量 clone/更新/构建。Zephyr 有几十个配套仓库,靠手工 clone 是管不过来的。
2. manifest 还能 import 别的 manifest。Zephyr 的 west.yml 末尾有一行 import: submanifests —— 它把 HAL、模块等清单拆到 submanifests/ 目录里。少了这个目录,manifest 就是坏的。
3. 稀疏检出 ≠ 克隆坏了。它是"只把部分文件放到工作区"的技术(大仓库省时间)。特征很好认: git ls-files 数出来的文件远多于磁盘上真实存在的文件。

动手:先体检,再修复

在 Git Bash 里执行(输出是实测值):

cd /f/0-code/20-active/oss-zephyr

# ① 体检:仓库里有多少文件 vs 磁盘上真实有多少
git ls-files | wc -l                              # 67454  ← 仓库里的
find . -type f -not -path "./.git/*" | wc -l      # 260    ← 磁盘上的
git config --get core.sparseCheckout              # true
git config --get remote.origin.partialclonefilter # blob:none

# ② 找出 west 为什么读不了 manifest
ls submanifests 2>/dev/null || echo "submanifests 缺失"   # 缺失 ✗

# ③ 最小修复:只把 manifest 需要的那一个目录加回工作区(不会拉整仓)
git sparse-checkout add submanifests
ls submanifests | head -3                         # README.txt / optional.yaml …

# ④ 装 west 并确认版本
pip install west
west --version                                    # West version: v1.5.0

然后回到工作区根初始化(注意:west init -l 要在工作区目录里执行,把已有克隆指定为 manifest 仓库):

cd /f/0-code/20-active
west init -l oss-zephyr
# === Initializing from existing manifest repository oss-zephyr
# --- Creating …/20-active/.west and local configuration file

west topdir          # 应指向 F:/0-code/20-active
west list | head     # 列出 manifest 里的项目:名字 / 路径 / 版本 / 仓库地址

你应该看到 manifest zephyr HEAD N/A 打头,后面跟着 acpica、cmsis、hal_adi 等一长串项目 —— 这就是 Zephyr 的"全家福"。注意:现在只是"列出来",这些仓库还没下载(那一步是 west update,几百 MB,放到下一节)。

顺手记一笔:把"克隆是稀疏检出、submanifests 缺失、用 sparse-checkout add 修复"写进 开源贡献/00-环境与流程.md —— 这是你环境里的真实坑,下次换机器还会遇到。

自测(选项一样长,别从长度上猜)