自动控制 target 大小的 Rust Cargo

为什么做这个项目

Rust 是 AI 时代非常有价值的编程语言，但 target 成了我最头疼的问题：买了 2T 的硬盘都不够。试过的工具都没有解决，所以我直接改造了 Cargo。阅读完整背景。

第 5 天，没有手动删过任何东西

它现在跑在我的四台电脑上：两台 Linux、一台 macOS、一台 Windows（Windows 试得比较少）。在 Linux 和 macOS 上已经连续用了 5 天，跑满 worktree 做自动化 AI 开发。我再也没有清理过 target 目录，磁盘也再没有占满过。

• worktree 不再累加磁盘。在 525 个 crate 的 workspace 里，每个新 worktree 只增加约 0.4 GB，而不是 6.7 GB。
• 磁盘自己管理自己。每个项目保持在最近一天最大构建的两倍以内。不需要定时任务，也不用记得 cargo clean。
• 不再从头编译。构建目录一直在，同一 commit 的新 worktree 只要 5 秒，而不是 106 秒。Agent 工作时电脑也不卡。

Rust 的编译速度还是比 Go 这类语言慢一些。这个取舍我接受：我们慢一点，用户用起来更快。

我也在 X 上聊过这件事。

每个新 worktree 的成本都更低

nsh 是一个 525 个 crate 的 workspace，每个 worktree 以 dev 配置构建一个二进制，8 核 Apple Silicon Mac，Rust 1.99 stable。同一 commit 的五个 worktree 跑一轮；编辑相关的数据取三次的中位数。关闭 sccache 等编译器缓存。

• Cargo
• 这个 fork

每个 worktree 都是全新检出，构建一个二进制。Cargo 给每个 worktree 单独的 target 目录，并重新编译所有依赖。这个 fork 只编译一次并复用，所以之后的 worktree 只构建 workspace 里的 crate。

不同项目也共享依赖

Cargo 1.99.0 和这个 fork 的 release 构建，在同一台机器上依次运行：nsh，然后 mado（独立仓库中 330 个 crate 的应用），再从空的构建目录构建一次 mado，相当于新 worktree 或 cargo clean 之后的情况。各跑一轮。

清理是什么样的

构建之后，最多每小时一次，Cargo 删除一天内没有构建用过的内容，再按最近最少使用删除构建单元，直到项目符合限制。释放了空间时只输出一行。

$ cargo build
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.89s
     Cleaned 680 stale build units, 10.1GiB freed (build.gc)

有哪些改动

你的项目、Cargo.toml 和 .cargo/config.toml 都不用改。

• 每个项目一个构建目录。中间文件放在 ~/.cargo/targets/<name>-<hash>/，hash 来自仓库的 .git 目录。无论 worktree 建在哪里，都落在这个目录，复用已编译的依赖，只构建自己的 crate。二进制仍然出现在 ./target。
• 目录固定。./target 和 ~/.cargo/targets 不能移动：--target-dir、CARGO_TARGET_DIR、build.target-dir 和 build.build-dir 会被忽略并给出警告，所以任何参数、环境变量或工具都无法把构建产物散落到别处。
• 所有项目共享依赖。registry 和 git 依赖在 ~/.cargo/targets/shared-deps/ 只构建一次，任何需要相同版本、feature 和 profile 的项目都能复用，类似 Go 的构建缓存。cargo check、clippy、rust-analyzer 和 cargo doc 使用同一批构建，所以构建之后的 check 只看你自己的 crate。
• worktree 之间也共享你自己的 crate。workspace crate 以文件内容而不是所在目录作为 key，所以同一 commit 的新 worktree 能复用其他 worktree 构建好的所有 crate，切回某个分支也能复用之前的构建。编辑测试或二进制时只重新构建那个 target。带 build script 的 crate，以及读取自身路径（env!("CARGO_MANIFEST_DIR")）的 crate，仍然按 worktree 构建。worktree 之间还共享 rustc 的增量缓存，所以新 worktree 的首次编辑也是增量的。为此 rustc 把 . 记录为编译目录（-Zremap-cwd-prefix=.；stable 上通过 RUSTC_BOOTSTRAP=1，且不允许 #![feature]），所以调试器要从 workspace 根目录启动。
• 大小限制。每个项目保持在最近一天最大构建的两倍以内，一天未使用的构建单元会被删除。共享依赖保留 7 天，上限 50 GiB；7 天没有构建用过的项目会被整个删除。编辑替换掉的构建单元会立即删除，除非其他 worktree 还在用。因新依赖而重新构建的共享依赖，其旧版本一天后删除；CARGO_TARGET_TMPDIR 中过期的测试目录，以及 ./target 中构建单元已不存在的二进制，也是一天后删除。正在运行的构建锁定的内容不会被删除。
• macOS 上没有重复的目标文件。调试器和 backtrace 读取 rlib 内部的目标文件，所以旁边的散落副本会被删除。
• worktree 可以同时构建。开启了细粒度锁，并行的 Agent 不会排队等同一把锁。两个构建同时需要同一个依赖时，一个编译，另一个复用结果。
• dev 构建的调试信息更少。你的 crate 保留行号表，依赖不带调试信息。backtrace 仍有文件和行号。profile 中的 debug 设置优先。
• nightly 上元数据只存一份。在 nightly rustc 上，rlib 不再带第二份 .rmeta，共享依赖可减少约 30%。
• 自动更新。最多每天一次，后台检查并安装最新版本，不用重新运行安装脚本。CARGO_FORK_AUTO_UPDATE=0 可以关闭。
• nightly 上使用 Cranelift。cargo build 用 Cranelift 编译你的 crate，编译器前端最多使用 8 个线程。测试和 release 构建仍用 LLVM。如果你有 nightly 工具链，安装脚本会添加 Cranelift 组件。

# ~/.cargo/config.toml
[build.gc]
max-size = "auto"      # or "15 GiB", "none"
shared-max-size = "50 GiB"
max-unused = "1 day"
shared-max-unused = "7 days"
frequency = "1 hour"   # or "always", "never"
enabled = true