可复现的依赖管理:coop 隔离虚拟机的 Nix 安装与跨平台交叉编译完全指南
可复现的依赖管理:coop 隔离虚拟机的 Nix 安装与跨平台交叉编译完全指南
coop 是一个用 Rust 编写的 CLI 工具,为 Claude Code、Codex 和 Grok Build 提供一次性、可销毁的隔离虚拟机环境。本文讲解如何用 Nix 可复现地安装 coop(nix build + nix profile add),并深入剖析 flake 依赖锁定机制与 musl 跨平台交叉编译的完整流程——无论是普通用户还是贡献者,读完都能做到"在任何机器上,构建出完全相同的二进制"。
为什么 coop 需要可复现的依赖管理
coop 的仓库是一个 Cargo workspace,包含两个二进制:
| 二进制 | 职责 |
|---|---|
coop |
主 CLI,管理 Firecracker(Linux)/ Lima(macOS)虚拟机 |
coop-proxy |
宿主机侧的凭证注入反向代理 |
其中 coop-proxy 依赖 aws-lc-sys 这个 C 库,构建时必须依赖 CMake + 原生 musl 编译器(见 coop-proxy/Cargo.toml)。这类"原生依赖"正是传统构建中最难复现的部分:不同机器上 cmake 版本、C 编译器版本稍有差异,产物就可能不同。
Nix 的方案是:把所有输入钉死。coop 的 flake 通过 flake.lock 锁定 nixpkgs 和 rust-overlay 的精确 rev + 哈希,Rust 工具链版本则由 rust-toolchain.toml 钉在 1.94.0,Cargo 侧再由 Cargo.lock + strictDeps 保证依赖树完全一致。
Nix 安装前提:版本要求与源码准备
📦 以下命令要求 Nix 2.30 或更新版本(nix profile add 是 2.30 引入的),并启用 nix-command 与 flakes 两个实验特性。用 nix --version 检查版本。
git clone https://gitcode.com/gh_mirrors/coop9/coop
cd coop
三步用 Nix 安装 coop
第一步:nix build 本地构建
在仓库目录中执行:
nix build
./result/bin/coop --version
result/bin 下同时包含 coop 和 coop-proxy 两个二进制——安装时必须让它们留在同一目录,因为代理模式会在 coop 旁边查找 coop-proxy。
第二步:nix run 免安装快速验证
不想先安装?直接运行:
nix run . -- --help
第三步:nix profile add 正式安装
nix profile add .#coop
显式的 .#coop 输出名会把 profile 条目命名为 coop,与目录名无关。如果你之前用 nix profile add . 装过,先用 nix profile list 确认旧条目名,再用旧名执行升级/移除。
macOS 与 Linux 的差异:
- 🍎 macOS:Nix 包已内置 Lima 及宿主命令行工具(
lima、coreutils、curl、git、gnutar、openssh、rsync,见 flake.nix),因此nix run . -- setup不需要额外安装 Homebrew。 - 🐧 Linux:Nix 包不包含 Firecracker 主机依赖,需按 平台前置要求 自行安装 KVM、
e2fsprogs等,并保持它们在PATH上。
完成后执行 coop setup 构建 VM 模板镜像即可开始使用。
Nix 安装的升级与卸载方法
Nix 安装的 coop 会自我标识为 dev build,因此 coop update 和后台版本通知是禁用的——升级由 Nix 管理:
# 1. 更新本地 checkout 后
nix profile upgrade coop
# 2. 有意更新被锁定的 Nix 输入(nixpkgs / rust-overlay)
nix flake update
卸载时不要使用 sudo coop uninstall 或直接删除 store 路径——coop uninstall 在任何数据被改动之前都会拒绝操作 Nix store 中的二进制(即使带 --yes/--purge)。正确的做法是:
nix profile remove coop
这不会触碰 VM 实例、镜像和配置数据,详见 docs/getting-started.md。
nix develop:一条命令进入开发环境
贡献者无需手动装工具链。nix develop 提供的开发 shell 包含:
- rust-toolchain.toml 中固定的 Rust 工具链(含 rustfmt、clippy)
- CMake、Git、OpenSSH、Python 3;macOS 上还会附带 Lima 及打包 CLI 所需的宿主工具
nix develop
./scripts/install-dev-tools.sh # 安装钉住版本的开发工具
cargo fmt -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
另外两个常用命令:nix flake check 会构建包并运行当前平台的单元测试 + 安装检查;nix fmt 负责格式化 flake 本身。完整说明见 CONTRIBUTING.md 的 Nix 章节。
flake.nix 依赖锁定原理拆解
flake.nix 的核心结构值得新手学习:
- 输入只有两个:
nixpkgs-unstable与rust-overlay(Rust 工具链来源),且 rust-overlay 的 nixpkgs 通过follows复用同一份,避免版本漂移(flake.nix)。 - 三平台覆盖:
aarch64-darwin、aarch64-linux、x86_64-linux,其中 macOS 目标专为 Apple Silicon + Lima 准备(flake.nix)。 - 工具链同源:
rust-bin.fromRustupToolchainFile直接从rust-toolchain.toml读取版本,Nix 与 rustup 永不失同步。 - 严格依赖:
strictDeps = true+cargoLock.lockFile = ./Cargo.lock,Nix 构建只允许使用锁文件声明的版本。
跨平台交叉编译:三个发布目标
官方发布的三个 target
coop 的 Linux 二进制采用 musl 静态链接,单文件即可运行、无 glibc 依赖:
| Target 三元组 | 平台 |
|---|---|
aarch64-apple-darwin |
macOS(Apple Silicon) |
x86_64-unknown-linux-musl |
Linux x86_64 |
aarch64-unknown-linux-musl |
Linux arm64 |
三元组检测逻辑见 install.sh。注意 aws-lc-sys 的 C 后端必须用 CMake + 与目标同架构的原生 musl 编译器构建,所以官方 release 流程是在匹配架构的原生 runner 上分别构建,而不是交叉编译(RELEASING.md)。
macOS 交叉编译到 Linux 的完整流程
项目已内置两个 musl 目标的 Cargo linker 配置:x86_64-unknown-linux-musl 使用 x86_64-linux-musl-gcc,aarch64-unknown-linux-musl 使用 aarch64-linux-musl-gcc。装好对应交叉编译器后,若命名与默认不一致,需显式设置目标级变量(见 docs/backends.md 与 RELEASING.md):
export CC_x86_64_unknown_linux_musl=x86_64-linux-musl-gcc
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=x86_64-linux-musl-gcc
export CC_aarch64_unknown_linux_musl=aarch64-linux-musl-gcc
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=aarch64-linux-musl-gcc
集成测试脚本把这个流程自动化了——交叉编译 release 构建、scp 到远端 Linux 主机、再在那边跑完整测试套件:
./tests/run-integration.sh --remote user@remote-host
用 Nix 为其他平台构建
由于 flake 为三个系统都声明了包,可以直接指定 --system 让 Nix 为目标平台构建(必要时借助 QEMU 模拟):
nix build .#coop --system x86_64-linux
nix build .#coop --system aarch64-darwin
只做编译检查(不产出二进制)
改了平台相关 #<a href="https://link.gitcode.com/i/500c85d55e3803e0d8b6a552937fc9cf" target="_blank">cfg] 分支时,可以用交叉目标做编译级验证(cargo check/clippy 加 --target),方法见 [docs/testing.md;macOS 用户还可用 tests/run-linux-unit.sh 在 Docker 容器中跑 Linux 单元测试。
关键文件清单
| 文件 | 作用 |
|---|---|
| flake.nix | flake 定义:包、checks、devShell、formatter |
| flake.lock | 锁定 Nix 输入的 rev 与哈希 |
| rust-toolchain.toml | 固定 Rust 1.94.0 工具链 |
| Cargo.toml | workspace 定义(coop + coop-proxy) |
| install.sh | 预编译二进制安装脚本(SHA-256 + Sigstore 验证) |
| scripts/preflight-release.sh | 发版前全量检查,含三 target 本地构建 |
| tests/run-integration.sh | 集成测试,支持 --remote 跨平台 |
| docs/getting-started.md | Nix 安装官方文档 |
| RELEASING.md | 发版流程与不可变 tag 规则 |
💡 小结:Nix 让 coop 的"依赖管理"从口号变成机制——输入锁定、工具链同源、严格依赖三件套,让 nix build 在任何机器上都产出可预期的二进制;而 musl 静态链接 + 原生编译策略,则保证了三个平台发布目标的一致性与可验证性。