Rust 编译器仓库中 rustc_codegen_gcc 子树的同步机制：git-subtree 双向同步实战

rustc_codegen_gcc 是 Rust 官方编译器的 GCC 代码生成后端，它同时维护在独立的 rust-lang/rustc_codegen_gcc 仓库与 rustc 主仓库的 compiler/ 目录下，二者靠 git-subtree 机制保持双向同步。本文基于 subtree 同步指南，完整讲解如何安装打过补丁的 git-subtree 工具、如何把主仓库中的改动推送回上游独立仓库、又如何把上游的新功能拉回 rustc 主仓库，并结合当前仓库中的 workspace 配置与 bootstrap 构建步骤，说明这个 vendored 子树是如何融入 rustc 整体构建体系的。

一、什么是 subtree，为什么需要双向同步

子树同步文档开篇即说明了背景：rustc_codegen_gcc 是 rust 编译器仓库的一个 subtree（子树），因此需要定期同步，以保证一侧发生的变更也能体现在另一侧。这里存在两个方向的同步：

• push 方向（rust 仓库 → 独立仓库）：在 rustc 主仓库中直接修改了 compiler/rustc_codegen_gcc/ 下的代码时（例如修一个只能复现在完整构建流程中的回归），要把这些提交推送到独立的 rustc_codegen_gcc 仓库；
• pull 方向（独立仓库 → rust 仓库）：独立仓库中日常开发的新功能、bug 修复，需要通过 git-subtree pull 拉回主仓库，使 rustc 构建系统始终使用最新的后端代码。

当前仓库的多个文件可以印证这种"vendored 子树"的组织方式：

1. workspace 层面显式排除。根 Cargo.toml 的 exclude 列表中明确列出了 compiler/rustc_codegen_gcc，即它不参与 rustc 主 workspace 的编译，而是按独立 crate 处理。这与它自身 Cargo.toml 的声明一致：crate-type = ["dylib"]，产出可被 rustc 动态加载的代码生成后端；其核心依赖是 gccjit crate（启用 dlopen 特性，在运行时加载 libgccjit 动态库）。
2. bootstrap 构建系统按独立步骤处理它。rustc 的构建入口 x 会通过 bootstrap 步骤编译、检查、lint 和打包该后端，别名均为 rustc_codegen_gcc / cg_gcc：
   • 检查步骤：run.alias("rustc_codegen_gcc").alias("cg_gcc")，并指向 compiler/rustc_codegen_gcc/Cargo.toml 执行 cargo check；
   • 编译步骤：以同样方式构建后端；
   • clippy 步骤：对 compiler/rustc_codegen_gcc 单独跑 clippy，且会用 --no-default-features 再跑一次；
   • dist 步骤：将其纳入发布 tarball（包括把 LICENSE 等文件放入 share/doc/rustc_codegen_gcc），并会跳过不支持的目标。
3. 版本锚点。子树内自带两份"版本钉死"文件：rust-toolchain 将构建该后端的工具链钉在 nightly-2026-04-29（需要 rust-src、rustc-dev、llvm-tools-preview 组件）；libgccjit.version 钉住了所依赖的 GCC fork 的提交哈希（6f155cc3...）。这说明 subtree 同步的不只是 rustc 侧的代码——GCC 依赖侧也有自己的版本管理。

二、同步前提：安装打过补丁的 git-subtree

原始文档指出了一个关键前提：在 rustc 仓库上使用 git-subtree 需要打过补丁的 git，因为上游 git 的 subtree 实现存在与 rustc 仓库不兼容的行为（原文档指向 git 上游的一个 PR，此处不附外链）。安装步骤在 subtree.md 中给出，完整继承如下（按原文顺序执行）：

git clone [e-mail]:tqc/git.git
cd git
git checkout tqc/subtree
make
make install
cd contrib/subtree
make
cp git-subtree ~/bin

要点说明：

• 前四条命令构建并安装打了补丁的 git 本体；
• cd contrib/subtree && make 单独构建 git-subtree 命令，随后复制到 ~/bin。因为 git-subtree 是 git 的 contrib 工具而非主程序的一部分，所以必须单独编译安装；
• 后续所有同步命令都通过 PATH="$HOME/bin:$PATH" ~/bin/git-subtree ... 显式调用这个打过补丁的版本，避免误用系统自带的旧版。

注意：该文档中的 ../rustc_codegen_gcc 与 ../rust 表示两个仓库并排 checkout 在父目录下，例如 ~/work/rust 与 ~/work/rustc_codegen_gcc。这是整套流程的目录布局假设。

三、push 方向：把 rust 仓库的改动推送到独立仓库

当你在 rustc 主仓库中直接改动了 compiler/rustc_codegen_gcc/ 下的内容，需要执行原文档给出的推送流程：

PATH="$HOME/bin:$PATH" ~/bin/git-subtree push -P compiler/rustc_codegen_gcc/ ../rustc_codegen_gcc/ sync_branch_name
cd ../rustc_codegen_gcc
git checkout master
git pull
git checkout sync_branch_name
git merge master

逐行解析：

1. git-subtree push -P compiler/rustc_codegen_gcc/：-P 指定子树在主仓库中的前缀路径，把该前缀下的提交"抽取"出来推送到相邻的 ../rustc_codegen_gcc 仓库的 sync_branch_name 分支。
2. 接下来的四行处理一个常见冲突源：推送目标分支时，独立仓库的 master 可能已经前进（有独立仓库自身的提交）。因此先 git checkout master && git pull 拉取最新主分支，再切回 sync_branch_name 执行 git merge master，保证同步分支包含 master 的最新历史——后续发起 PR 时才能干净合入。

其中 master 是独立仓库 rustc_codegen_gcc 的默认分支名（原文档基于当时的分支布局）。

四、pull 方向：把独立仓库的改动拉回 rust 仓库

这是更敏感的方向，因为改的是 rustc 主仓库。原文档给出的完整流程：

cd ../rust
git pull origin master
git checkout -b subtree-update_cg_gcc_YYYY-MM-DD
PATH="$HOME/bin:$PATH" ~/bin/git-subtree pull --prefix=compiler/rustc_codegen_gcc/ https://github.com/rust-lang/rustc_codegen_gcc.git master
git push

# Immediately merge the merge commit into cg_gcc to prevent merge conflicts when syncing from rust-lang/rust later.
PATH="$HOME/bin:$PATH" ~/bin/git-subtree push -P compiler/rustc_codegen_gcc/ ../rustc_codegen_gcc/ sync_branch_name

逐步说明：

1. git pull origin master：先同步主仓库基线。需要注意分支名要按仓库实际默认分支调整——当前 checkout 的 stage0 文件 中记录的是 nightly_branch=main，说明 rust 主仓库当前以 main 为开发分支，实际操作时应替换为对应分支名。
2. git checkout -b subtree-update_cg_gcc_YYYY-MM-DD：用日期命名的专用分支承载本次子树更新，便于后续 PR 审阅与回溯（例如 subtree-update_cg_gcc_2026-09-05）。
3. git-subtree pull --prefix=compiler/rustc_codegen_gcc/ <上游URL> master：核心命令。它从独立仓库的 master 分支拉取全部提交，并以 compiler/rustc_codegen_gcc/ 为前缀重放进主仓库，生成一个 merge commit。--prefix 参数与 push 时的 -P 对应，两边必须一致，否则子树前缀会错位。
4. git push 之后，原文档有一条非常重要的注释："Immediately merge the merge commit into cg_gcc to prevent merge conflicts when syncing from rust-lang/rust later."（立即把 merge commit 推回 cg_gcc，防止以后从 rust-lang/rust 再同步时产生合并冲突。）这正是第五行 git-subtree push ... sync_branch_name 的用途——pull 在主仓库制造了一个 merge commit，若不同步回独立仓库，下次反向 push 时两边历史会分叉、反复产生冲突。这条注释是整个流程中最容易遗漏的一步。

原文档还留有一行 FIXME: write a script that does the above.，说明截至文档撰写时，上述手工步骤尚未脚本化；文档末尾还指向了项目团队在社区聊天中的相关讨论（外链从略）。因此执行时请以独立仓库当前文档为准，流程细节可能已演进。

五、同步对象侧：vendored 子树的构建配套

理解同步为什么值得维护，需要看 rustc 侧为这个子树配套了哪些构建设施——这些正是同步时需要保持一致的内容：

1. 独立构建系统入口。子树自带 y.sh：它先 cargo build --release 构建 build_system/ 下的构建器，再转发所有参数给编译出的 y 可执行文件。独立仓库中 ./y.sh prepare && ./y.sh build --sysroot --release 就是标准构建序列（见 Readme.md 的 Quick start），prepare 会下载并打补丁 sysroot 源码——补丁存放在 patches/ 目录（如 0028-core-Disable-long-running-tests.patch 用于禁用 std 中耗时过长的测试），配置模板为 config.example.toml。
2. sysroot 与后端的双 profile 机制。如 CONTRIBUTING.md 所述，rustup 预编译的标准库是 LLVM 产物，使用 GCC 后端时必须重编 sysroot；--sysroot、--release-sysroot、--release 等 flag 分别控制后端与 sysroot 的编译档位，其中 --release-sysroot 必须与 --sysroot 联用。这类构建语义一旦变化，通常同时涉及 rustc 构建侧与后端代码，正是 subtree 双向同步要解决的典型场景。
3. 与 rustc 主树的接口边界。后端通过 rustc-dev 组件的私有 API 编译（rust-toolchain 显式要求该组件），因此 rustc 侧的 HIR/MIR/traits 接口变动（如 rustc_hir、rustc_middle 等 crate）都可能要求后端跟着更新——这也是 subtree 定期 pull 的动因。

六、实操要点小结

场景	命令要点	依据
安装补丁版工具	构建 patched git 后单独 make contrib/subtree，安装到 ~/bin	subtree.md
rust → cg_gcc	git-subtree push -P compiler/rustc_codegen_gcc/ ../rustc_codegen_gcc/ <branch>，随后在独立仓库 merge master	同上
cg_gcc → rust	新分支上 git-subtree pull --prefix=compiler/rustc_codegen_gcc/ <upstream> master，push 后立即反向 push 回 cg_gcc	同上
分支名适配	按仓库实际默认分支调整（当前 stage0 记录 main，文档写作时为 master）	stage0
前缀一致性	--prefix 与 -P 都必须等于 compiler/rustc_codegen_gcc/	subtree.md

最后需要说明适用前提：本文所有命令与目录布局均以 subtree.md 记载的流程为准，依赖"两个仓库并排 checkout + 打过补丁的 git-subtree"这一环境假设；rustc 侧的集成事实（workspace 排除、bootstrap 步骤、工具链钉版）以当前仓库实际文件为准。若独立仓库的同步流程已有脚本化更新，应以独立仓库的最新文档为第一优先级。