kernels 是一个用于构建计算内核（compute kernels）并从 Hub 动态加载的开源项目。它的构建工具kernel-builder没有选择 Docker 或 CMake 裸跑，而是全面押注了Nix——一个以"可复现构建"和"声明式沙箱"闻名的包管理器。本文将从原理层面拆解：为什么 Nix 是内核构建场景下的最优解，沙箱到底隔离了什么，以及构建缓存如何把 CI 时间压缩到可接受的范围。

一、先搞清楚痛点：内核构建为什么难？

和普通 Python 包不同，GPU/CPU 计算内核是原生 C++/CUDA 代码，它的构建链条又长又脆：

一个内核往往要为上述组合的笛卡尔积各编译一份产物（称为 build variant）。构建环境稍有差异——glibc 版本、系统头文件、环境变量——产物就不可复现，"在我机器上是好的"问题随之而来。这正是 Nix 的主场。

二、为什么选 Nix：六大核心理由

官方文档 docs/source/builder/why-nix.md 给出了六个理由，下面逐一展开。

1. 可复现的确定性构建（Reproducible Builds）

Nix 保证确定性求值：同一版本的 Nix builder，输入相同的build.toml和源码，就会生成完全一致的构建配方（derivation）和二进制产物。这意味着任何人、在任何机器上重新构建，得到的.so都是一字节不差的。

💡 这一点对 Hub 场景至关重要——内核最终会在成千上万台用户机器上运行，可复现性让第三方可以重新编译并比对哈希，以验证没有被注入恶意代码。

2. 显式的依赖管理

编译 PyTorch 内核涉及 CUDA 版本、PyTorch API、C++ 工具链等一堆易冲突的依赖。Nix 用声明式清单把它们全部显式列出，谁用了什么头文件、什么库版本，一目了然，彻底告别隐式依赖。

3. 声明式配置，协作友好

内核项目只需要一个极简的flake.nix就能接入完整构建体系。以官方 ReLU 示例为例，examples/kernels/relu/flake.nix 只有短短十几行：

outputs = { self, kernel-builder, }: kernel-builder.lib.genKernelFlakeOutputs { inherit self; path = ./.; };

它声明"我要用 kernel-builder 构建这个目录"，剩下的构建矩阵、沙箱、缓存全由 builder 接管。声明式配置让排查问题、文档化、团队协作都变得容易。

4. 完全隔离的沙箱构建

Nix 的每个构建任务都运行在完全隔离的 build sandbox中：看不到宿主机的系统库、环境变量和临时文件，只能使用 derivation 里显式声明的依赖。这从机制上杜绝了两类事故：

• 意外依赖：不小心链接了宿主机上的系统库，换台机器就炸；
• 构建污染：脏的工作区状态、本地缓存悄悄影响产物。

5. 高效缓存与 CI 集成

内核编译是 CPU 密集型操作，全量构建所有 variant 非常耗时。Nix 对构建产物做哈希寻址缓存：相同输入命中缓存就直接复用，秒级完成。项目还在 flake.nix 中预配置了 Hugging Face 的二进制缓存（huggingface.cachix.org作为extra-substituters），CI 首跑之后基本全是缓存命中。

6. 自由实验，随时回滚

想试新的 PyTorch 版本或 CUDA 工具链？改一行配置即可生成新的构建环境；出了问题回退 git commit，Nix 会按源码哈希自动重建，实验成本几乎为零。

三、沙箱原理：一次内核构建到底发生了什么？

docs/source/builder/design-nix-builder.md 描述了完整的构建流程。kernel-builder本身不直接编译代码——它的每个构建子命令本质都是执行nix build/nix run/nix develop。真正的编译在 Nix 沙箱内完成：

1. 生成 CMake 文件：kernel-builder create-pyproject根据build.toml生成构建脚本；
2. 生成 Ninja 构建文件：CMake 配置阶段；
3. Ninja 编译：在只含声明依赖的沙箱中产出.so；
4. 自动化检查：
   • 校验内核只使用 ABI3 /manylinux_2_28允许范围内的符号；
   • 校验产物确实能被kernelsPython 包加载；
5. Strip runpath：剥离 ELF 内嵌的库搜索路径，使产物与分发环境解耦。

关键细节——manylinux_2_28 兼容性：为了让内核兼容大量老系统，构建工具链并非随便找一套 gcc，而是把AlmaLinux 8 的 GCC 工具集（manylinux_2_28官方基线）重新打包成 Nix derivation（见 nix-builder/pkgs/manylinux/），甚至专门构建了自己的 glibc 2.28 包（nix-builder/pkgs/manylinux/stdenv.nix），因为 AlmaLinux 自带动态加载器硬编码了 Nix 中不存在的 FHS 路径。这就是"沙箱 + 声明式"的威力：把一整套异构工具链精确地复刻进隔离环境。

四、构建矩阵：一次配置，全硬件通吃

Nix builder 根据 nix-builder/versions.nix 中支持的配置和内核的build.toml生成构建矩阵——后端（CPU/CUDA/Metal/ROCm/XPU）× 后端版本 × 框架版本的笛卡尔积。例如当前支持矩阵中包含：

torch 2.10 × ( CPU | CUDA 12.6 | CUDA 12.8 | CUDA 13.0 | Metal | ROCm 7.0/7.1 | XPU )

每个组合都是一个独立的 Nix derivation，天然可并行、可缓存。ROCm / XPU / manylinux 这些厂商包集也都遵循同一套"包集模式"（components → overrides → 工具链合成 overlay），确保构建环境与用户最终安装的官方发行包一致，避免符号解析不一致的隐蔽 bug。

五、沙箱不只是隔离：安全实践指南

docs/source/builder/security.md 给出了面向内核作者的安全清单，核心两条与 Nix 直接相关：

⚠️永远不要关闭沙箱构建。Nix 可以sandbox = false运行以兼容不支持命名空间的系统，但这样会让宿主机系统依赖溜进产物，构建也将不可复现。用nix-info -m可以确认当前环境sandbox: yes。

⚠️不要在脏的 Git 工作区构建。未提交的改动会让构建无法从纯源码复现。kernel-builder upload会为 dirty variant 打印警告并注入警告横幅，kernels加载器在加载 dirty 构建的 variant 时也会告警。

加上可复现构建带来的"任何人可重编译验证哈希"的能力，Nix 沙箱实际上构成了内核分发的供应链安全底座。

六、Nix vs Docker：为什么容器不够？

这是官方 FAQ 里被问得最多的问题：

Docker 解决的是"运行环境一致"，Nix 解决的是"构建结果可复现"——对要分发给百万用户机器的内核二进制来说，后者才是刚需。

七、快速上手：三步体验 Nix 构建

# 1. 从模板初始化一个内核项目（自动生成 flake.nix） kernel-builder init --name owner/my-kernel # 2. 本地构建所有 variant（等价于 kernel-builder build） kernel-builder build # 3. 构建并上传到 Hub kernel-builder build-and-upload --repo-id owner/my-kernel

更完整的 CLI 参考见 docs/source/builder-cli.md，本地开发体验（devshell、IDE 集成）见 docs/source/builder/local-dev.md。

总结

kernels 选择 Nix，本质上是为"内核构建"这个依赖维度爆炸、安全要求极高的场景找到了正确抽象：

• 确定性求值 + 构建沙箱→ 产物可复现，供应链可审计；
• 声明式依赖 + 包集模式→ 任意 Torch/CUDA/ROCm 组合都是显式、精确的；
• 哈希缓存 + 二进制 substituter→ CI 从"小时级"降到"分钟级"；
• 构建矩阵自动生成→ 一次配置覆盖多硬件多版本。

对于正在构建复杂原生扩展的团队来说，这套 Nix 沙箱方案值得直接借鉴。