kas源码剖析(二):repos.py仓库并发抓取与Ref缓存深度解析
kas源码剖析(二):repos.py仓库并发抓取与Ref缓存深度解析
kas 是 bitbake 系项目(OpenEmbedded / Yocto / ISAR)的源码配置工具,一行命令即可完成数十个 bitbake layer 仓库的下载、检出与补丁应用。本文深入 kas 核心模块 kas/repos.py,剖析它的两大亮点:仓库并发抓取(asyncio 并行 fetch)与 Ref 对象缓存(KAS_REPO_REF_DIR 裸库 + git clone --reference),帮助新手和普通用户理解 kas 为什么比手动 git clone 更快、更省磁盘。
一、Repo 类族:一个仓库对象的完整画像 💡
打开 kas/repos.py,你会发现一套清晰的类层次结构:
| 类 | 职责 |
|---|---|
| Repo | 抽象基类,保存 url/commit/tag/branch/layers 等配置字段 |
| RepoImpl | 通用实现:fetch_async、checkout、apply_patches_async |
| GitRepo | 把所有操作翻译成 git 子命令 |
| MercurialRepo | 同上,对应 hg 子命令 |
所有仓库对象都由工厂方法 Repo.factory 创建,它做了三件重要的事:
- 参数校验:
commit、tag、branch、refspec至少要有一个(本地仓库除外),否则抛出RepoRefError; - 安全警告:只写
tag或branch而不锁定commit时,会打印"unsafe"警告——因为 tag/branch 是可变的,上游可以随时移动指针; - 类型分发:
type: git返回GitRepo,type: hg返回MercurialRepo,未知类型直接报错。
配置层面,一个典型的 repos 段长这样(参见 examples/openembedded.yml):
repos:
poky:
url: https://git.yoctoproject.org/poky.git
tag: yocto-5.1.1
commit: 7e081bd98fdc5435e850d1df79a5e0f1e30293d0
新手建议:始终同时提供
tag+commit,这是 kas 推荐的"可复现"姿势。
二、fetch_async:并发抓取的完整流程 🚀
2.1 谁来驱动并发?
真正的"并发开关"不在 repos.py,而在 kas/libkas.py 的 repos_fetch 函数:
tasks = []
for repo in repos:
tasks.append(asyncio.ensure_future(repo.fetch_async()))
loop.run_until_complete(asyncio.gather(*tasks))
它为每个仓库创建一个 asyncio 任务,再用 asyncio.gather 同时跑完所有 fetch_async()。由于 git clone/fetch 是 I/O 密集型操作,10 个仓库并行下载的时间约等于最慢那一个,而不是它们的总和。
fetch_async 在 setup 流程中的调用点位于 kas/libcmds.py:SetupReposStep 会循环抓取 include 链上"缺仓库"的配置(支持跨仓库的 include),FinishSetupRepos 在配置完整后再做一次全量 fetch。
2.2 fetch_async 的五步走
RepoImpl.fetch_async 的逻辑可以拆成五步:
- 建 Ref 缓存(若有
KAS_REPO_REF_DIR):在 ref 目录下为该仓库建一个 bare 裸库; - 克隆工作仓库:若本地目录不存在,以 ref 库为参考执行本地克隆;
- 校正 origin URL:
git remote set-url origin ...,确保远程地址与 kas 配置文件一致,避免"仓库还在但 URL 改了"的坑; - 提前短路:用
git cat-file -t(contains_refspec_cmd)检查目标 commit/tag/branch 是否已经存在——存在就跳过 fetch(--update模式除外); - 执行 fetch:调用 fetch_cmd 拉取缺失对象,失败则抛出
RepoFetchError并附 stderr 原文。
第 4 步是 kas 增量执行的关键:第二次运行 kas build 时,没有任何网络开销。
三、Ref 缓存深度解析:磁盘省下来的秘密 💾
3.1 qualified_name:URL 到目录名的映射
ref 缓存目录的名字来自 Repo.qualified_name 属性——把 URL 的 netloc + path 中的 @、:、/、* 全部替换为 .:
https://git.yoctoproject.org/poky.git → git.yoctoproject.org.poky.git
这样一个字符串就能唯一标识远程仓库,且不含任何非法路径字符。
3.2 竞态安全的建库方式
并发抓取意味着多个任务可能同时创建同一个 ref 库。fetch_async 用了一个精巧的手法:
with TemporaryDirectory(prefix=self.qualified_name + '.', dir=refdir) as tmpdir:
(retc, _) = await run_cmd_async(self.clone_cmd(tmpdir, createref=True), ...)
os.rename(tmpdir, sdir) # 原子重命名
先克隆到临时目录,再用 os.rename 原子地"发布"。如果另一个实例抢先完成了重命名,本次 rename 抛 OSError,日志只打印一句 "repo ... already cloned by other instance" 就继续走。临时目录因为 TemporaryDirectory 上下文结束而自动清理——没有锁文件,没有残留垃圾。
3.3 git clone --reference
工作仓库的克隆命令在 GitRepo.clone_cmd:
git clone -q --reference <refdir> -- <refdir> <path>
--reference 让 git 把对象库"借用"自 ref 裸库,工作仓库只存储差异对象。当同一个 ref 库被 N 个工作目录共享时,磁盘占用近似于"1 份完整历史 + N 份增量",而不是 N 份完整历史——对 poky 这种数 GB 的仓库意义巨大。
⚠️ 细节:ref 裸库本身不做浅克隆(源码注释明确说明),否则参考库缺少完整历史会让
--reference失效;只有工作仓库可以浅克隆。
ℹ️ Mercurial 不支持 reference 机制,
MercurialRepo.clone_cmd对createref直接返回<a href="https://link.gitcode.com/i/189768b73319213e234b8816526e4761" target="_blank">'true']空操作(见 [kas/repos.py)。
清理时,kas clean 插件会检查 ref 目录(kas/plugins/clean.py),--preserve-repo-refs 可选择保留缓存。
四、浅克隆与 refspec:fetch_cmd 的分支逻辑 🔍
KAS_CLONE_DEPTH 环境变量控制 repo_clone_depth,贯穿 clone 和 fetch 两条路径:
| 场景 | 生成的命令 |
|---|---|
| 浅克隆 + branch | git clone --depth N --branch X |
| 浅克隆 + commit | git fetch --depth N origin <commit>(丢失分支信息) |
| 指定 tag | git fetch origin +<tag>:refs/tags/<tag> |
| 完整历史 + refs/ 前缀分支 | git fetch origin +<branch>:refs/remotes/origin/<branch> |
两个新手容易踩的坑:
- legacy
refspec字段已弃用:factory 里会打警告(kas/repos.py),且与 commit/tag/branch 互斥,浅克隆也不支持它; - commit 短哈希警告:
commit不是 40/64 位完整哈希时会提示"未来版本将报错"(kas/repos.py)。
五、checkout 与补丁:抓完之后做什么 🛠️
RepoImpl.checkout 在 fetch 之后同步执行(逐仓库串行),核心保障:
- dirty 检查:
git diff --stat非空则跳过 checkout 并警告,保护你的本地改动(--force-checkout可强制); - tag/branch 互斥:同时指定
tag和branch直接报RepoRefError; - 交叉验证:tag 解析出的 commit 与配置中的
commit不一致时报错中止;branch 则用git branch -r --contains验证分支确实包含该 commit(浅克隆时跳过此检查,因为分支信息不完整)。
apply_patches_async 同样在 asyncio 事件循环中并发运行(由 kas/libkas.py 的 repos_apply_patches 驱动):先把补丁切到 patched-<ref> 分支,再逐个 git apply 并自动提交,提交时间戳取自补丁文件头部的 Date: 行,保证可复现。
六、新人速查表:环境变量与命令行参数 ⚡
| 配置项 | 作用 | 定义位置 |
|---|---|---|
KAS_REPO_REF_DIR |
指定 ref 裸库缓存目录 | kas/context.py |
KAS_CLONE_DEPTH |
浅克隆深度(0 为完整) | kas/context.py |
KAS_PREMIRRORS |
正则改写仓库 URL 指向镜像 | kas/repos.py |
--update |
已检出也强制拉取上游新提交 | kas/libkas.py |
--force-checkout |
丢弃本地改动强制 checkout | kas/libkas.py |
环境变量清单详见官方文档 docs/userguide/environment-variables.inc。
七、相关文件导读
- 仓库对象与抓取核心:kas/repos.py
- 异步命令执行与并发调度:kas/libkas.py
- setup 流程编排(fetch → 验签 → checkout):kas/libcmds.py
- 上下文与环境变量:kas/context.py
- 配置示例:examples/openembedded.yml
- 单元测试(refspec/补丁):tests/test_refspec/、tests/test_patch.py
- 项目总览:README.rst
总结:repos.py 用"工厂 + 策略"模式隔离了 git/hg 差异,用 asyncio 实现了多仓库并行抓取,再用"临时目录 + 原子重命名"解决了无锁并发建库,配合 git clone --reference 实现了磁盘空间的极致复用——这正是 kas 相比手动克隆脚本的核心工程价值。下一篇将讲解 kas 的配置解析与 include 机制。