昇腾CANN manifest：仓库清单与版本管理实战

55 个独立仓库每个仓库独立迭代——CANN 8.0 里的 ops-transformer 是哪个 commithccl 是 v2.1.3 还是 v2.2.0runtime 和 driver 的版本是否兼容manifest 仓库用一份 XML 格式的清单文件回答了所有这些问题。它是 CANN 发行版的「物料清单」——定义一次发行包含哪些仓库、每个仓库用哪个 commit、仓库之间的依赖关系。Manifest 文件结构每个 CANN 发行版有一个 manifest XML 文件!-- manifest/releases/CANN_8.0.0.xml --?xml version1.0 encodingUTF-8?manifestremotenameatomgitfetchhttps://atomgit.com/cann//!-- 核心算子库 --projectnameopbasepathsrc/opbaserevisione3f2a1b/projectnameops-mathpathsrc/ops-mathrevision7c8d9e0/projectnameops-nnpathsrc/ops-nnrevisiona1b2c3d/projectnameops-transformerpathsrc/ops-transformerrevisionf4e5d6c/projectnameops-cvpathsrc/ops-cvrevisionb7a8c9d/projectnameops-blaspathsrc/ops-blasrevision1a2b3c4/projectnameops-fftpathsrc/ops-fftrevisiond5e6f7a/projectnameops-randpathsrc/ops-randrevision8b9c0d1/projectnameops-tensorpathsrc/ops-tensorrevisione2f3a4b/!-- 编译与运行时 --projectnamegepathsrc/gerevision5c6d7e8/projectnameruntimepathsrc/runtimerevisionf9a0b1c/projectnamedriverpathsrc/driverrevision2d3e4f5/projectnamemetadefpathsrc/metadefrevision6a7b8c9/!-- 加速库 --projectnamecatlasspathsrc/catlassrevision0d1e2f3/projectnameascend-transformer-boostpathsrc/atbrevisiona4b5c6d/projectnamegraph-autofusionpathsrc/graph-autofusionrevisione7f8a9b/projectnameasnumpypathsrc/asnumpyrevision0c1d2e3/projectnametorchtitan-npupathsrc/torchtitan-npurevision4f5a6b7/!-- 通信库 --projectnamehcclpathsrc/hcclrevision8c9d0e1/projectnamehcommpathsrc/hcommrevisionf2a3b4c/projectnamehixlpathsrc/hixlrevision5d6e7f8/projectnameascend-boost-commpathsrc/ascend-boost-commrevision9a0b1c2/projectnameshmempathsrc/shmemrevision3d4e5f6//manifest每个project元素的核心三个字段nameAtomGit 仓库名path在源码树中的相对路径revisionGit commit hash短格式7 位有了这份 manifest可以一键拉取整个 CANN 发行版的全部源码# 用 repo 工具拉取 CANN 8.0.0 完整源码repo init-uhttps://atomgit.com/cann/manifest\-brefs/tags/CANN_8.0.0-mreleases/CANN_8.0.0.xml reposync-j16# 拉取后的目录结构# src/# ├── opbase/ → opbasee3f2a1b# ├── ops-math/ → ops-math7c8d9e0# ├── ops-nn/ → ops-nna1b2c3d# ├── ops-transformer/ → ops-transformerf4e5d6c# ├── ge/ → ge5c6d7e8# ├── runtime/ → runtimef9a0b1c# ├── driver/ → driver2d5e4f5# ...共 55 个仓库精确到 commitrepo sync自动执行 git clone git checkout 到 manifest 指定的 commit——不需要手动挨个 clone 55 个仓库。Manifest 的版本管理CANN 有两个 release 轨道stable 和 RCRelease Candidate。Manifest 用 Git 分支区分manifest 仓库分支结构 ├── main开发分支跟着各仓库的 HEAD 走 ├── releases/8.0.x8.0 stable 线 │ ├── CANN_8.0.0.xml → 各仓库 commit 指向 8.0.0 发布时的 │ ├── CANN_8.0.1.xml → bugfix 发布仅变化了出 bug 的仓库 │ └── CANN_8.0.2.xml ├── releases/8.5.x8.5 stable 线 │ └── CANN_8.5.0.xml └── releases/rcRC 线 ├── CANN_8.5.0-rc1.xml ├── CANN_8.5.0-rc2.xml └── CANN_8.5.0-rc3.xml关键原则bugfix 发布只修改出 bug 的仓库的 revision其余仓库不变。# CANN_8.0.1.xml 相对于 CANN_8.0.0.xml 的 diff # 只有一个仓库的 revision 变了 --- releases/CANN_8.0.0.xml releases/CANN_8.0.1.xml -5,7 5,7 - project nameops-nn pathsrc/ops-nn revisiona1b2c3d / project nameops-nn pathsrc/ops-nn revisionx9y8z7w /只有 ops-nn 仓库在 8.0.1 中更新了修复了 MatMul 的一个 bug其余 54 个仓库不变。CI 自动生成 ManifestManifest 不该手动编辑——55 个仓库的 commit hash 手动写容易出错。CI 自动生成# .github/workflows/generate-manifest.ymlmanifest 仓库自身的 CIname:Generate Release Manifeston:workflow_dispatch:inputs:version:description:CANN version (e.g. 8.0.0, 8.0.1)required:truepre_release:type:booleandefault:falsejobs:generate:runs-on:ubuntu-lateststeps:-name:Checkout manifest repouses:actions/checkoutv3-name:Resolve revisionsrun:|python3 tools/resolve_manifest.py \ --version${{ inputs.version }} \ --outputreleases/CANN_${{ inputs.version }}.xml-name:Validate manifestrun:|python3 tools/validate_manifest.py \ --manifestreleases/CANN_${{ inputs.version }}.xml # 验证 # 1. 所有 55 个仓库的 commit 都存在没有 rebase 丢掉的 # 2. 仓库之间的依赖关系正确 # 3. 没有循环依赖-name:Tag and commitrun:|git tag CANN_${{ inputs.version }} git push --tagstools/resolve_manifest.py的逻辑# manifest/tools/resolve_manifest.pyimportsubprocessimportxml.etree.ElementTreeasET# 55 个仓库的清单REPOS[(opbase,src/opbase),(ops-math,src/ops-math),# ... 全部 55 个仓库]defresolve_manifest(version_tag_prefix):docET.Element(manifest)ET.SubElement(doc,remote,nameatomgit,fetchhttps://atomgit.com/cann/)forname,pathinREPOS:# 获取仓库在 version_tag 下的 commit hashurlfhttps://atomgit.com/cann/{name}tagfv{version_tag_prefix}# git ls-remote 获取 tag 对应的 commitcommitsubprocess.check_output([git,ls-remote,url,frefs/tags/{tag}],textTrue).split()[0][:7]# 取短 hashET.SubElement(doc,project,namename,pathpath,revisioncommit)returnET.tostring(doc,encodingunicode)每个仓库的 release tag如v8.0.0指向该仓库在 CANN 8.0.0 时的 commit。Manifest 把所有这些 commit 汇成一份清单。跨仓库兼容性检查55 个仓库各自独立迭代——但 CANN 是一个整体。ops-transformer 依赖 ops-nn 的一个特定 API——如果 ops-nn 的 API 改了ops-transformer 也必须更新。Manifest 的兼容性检查确保所有仓库的 commit 之间是兼容的。# manifest/tools/validate_manifest.pydefvalidate_compatibility(manifest_xml):# 解析 manifesttreeET.parse(manifest_xml)repos{}forprojintree.findall(project):repos[proj.get(name)]proj.get(revision)# 已知的跨仓库依赖关系deps{ops-nn:[opbase],ops-transformer:[opbase,ops-nn],ascend-transformer-boost:[ops-transformer,ge],cann-recipes-infer:[ascend-transformer-boost,runtime],}forrepo,req_depsindeps.items():# 检查被依赖的仓库是否在 manifest 中fordepinreq_deps:ifdepnotinrepos:raiseValueError(f{repo}depends on{dep}, but{dep}not in manifest)# 从仓库的 API 版本文件中读取依赖的版本约束dep_versionsread_api_versions(repo,repos[repo])fordep_name,min_versionindep_versions.items():actual_versionread_api_version(dep_name,repos[dep_name])ifactual_versionmin_version:raiseValueError(f{repo}{repos[repo]}requires{dep_name}{min_version}, fbut manifest has{dep_name}{repos[dep_name]}(v{actual_version}))兼容性检查在 CI 中跑——Manifest 生成后自动验证验证失败则不允许发布。踩坑一仓库 rebase 后 Manifest 中的 commit hash 失效开发者对ops-nn的 main 分支做了 rebase压缩 commit 历史。Manifest 中的ops-nncommita1b2c3d不再存在于远程仓库——repo sync 会报错。修复保护 release 分支的 commit 不被 rebase 删除。# 在每个仓库设置 GitHub 保护规则# main 分支禁止 force push保护 release tag 的 commit 不被重写# 每个 release tag如 v8.0.0创建后不可删除、不可移动# 如果确实需要修改 release 分支严重安全漏洞# 1. 更新 Manifest指向新的 commit# 2. 撤销旧 release tag打新 tag# 3. 发布 hotfix 版本CANN 8.0.0-hotfix1踩坑二Submodule vs Manifest 的选择Git submodule 也能管理多仓库——在父仓库里git submodule add每个子仓库submodule 的 commit hash 记录在父仓库中。为什么 CANN 不用 submodule 而用 Manifest repo 工具关键原因CANN 有 55 个仓库。git submodule update --recursive在 55 个仓库上是串行的逐个 clone——耗时长。repo sync -j16是并行的16 个仓库同时 clone——快得多。Manifest 的另一个优势是分支管理同一个 manifest 仓库可以维护多条 release 线的 manifest 文件8.0.x / 8.5.x / rc而 submodule 的 commit hash 直接绑在父仓库的 Git 历史上——更难做多线维护。踩坑三Release Tag 命名不一致不同的 CANN 仓库用不同的 release tag 格式ops-nnv8.0.0hcclv2.1.3版本号独立于 CANN 版本driver1.76.22.3.220固件版本号格式Manifest 的resolve_manifest.py假设所有仓库都用v{CANN_VERSION}格式的 tag——碰到 hccl 的v2.1.3和 driver 的1.76.22.3.220就找不到。修复每个仓库加manifest.tag配置文件。# hccl/manifest.tag # 在 hccl 仓库根目录存放 tag 映射 # CANN 版本 → hccl 的 release tag 8.0.0 v2.1.3 8.5.0 v2.2.0resolve_manifest.py读取各仓库的manifest.tag做映射——CANN 版本和仓库自身的 tag 之间通过这个文件桥接。Manifest 不是一个会写代码的仓库——它是 55 个仓库的「快照」。每一个 CANN 发行版的构建、测试、发布、部署、回滚——都从这份 manifest XML 文件开始。自动化是 manifest 的核心manifest 由 CI 自动生成、跨仓库兼容性自动检验、repo sync自动拉取全部源码。从 manifest 出发可以重建任意一个 CANN 版本的完整源码树——这是软件工程里的 reproducibility可重现性开源社区的基础设施。