kas源码剖析(二):repos.py仓库并发抓取与Ref缓存深度解析

原创2026-11-15 10:21:58132 阅读

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 创建,它做了三件重要的事:

  1. 参数校验:commit、tag、branch、refspec 至少要有一个(本地仓库除外),否则抛出 RepoRefError;
  2. 安全警告:只写 tag 或 branch 而不锁定 commit 时,会打印"unsafe"警告——因为 tag/branch 是可变的,上游可以随时移动指针;
  3. 类型分发: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 的逻辑可以拆成五步:

  1. 建 Ref 缓存(若有 KAS_REPO_REF_DIR):在 ref 目录下为该仓库建一个 bare 裸库;
  2. 克隆工作仓库:若本地目录不存在,以 ref 库为参考执行本地克隆;
  3. 校正 origin URL:git remote set-url origin ...,确保远程地址与 kas 配置文件一致,避免"仓库还在但 URL 改了"的坑;
  4. 提前短路:用 git cat-file -t(contains_refspec_cmd)检查目标 commit/tag/branch 是否已经存在——存在就跳过 fetch(--update 模式除外);
  5. 执行 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。

七、相关文件导读

总结:repos.py 用"工厂 + 策略"模式隔离了 git/hg 差异,用 asyncio 实现了多仓库并行抓取,再用"临时目录 + 原子重命名"解决了无锁并发建库,配合 git clone --reference 实现了磁盘空间的极致复用——这正是 kas 相比手动克隆脚本的核心工程价值。下一篇将讲解 kas 的配置解析与 include 机制。

登录后查看全文
kas