Nix `store submit-output` 命令详解:在内容寻址派生中通过 builder RPC 提交输出
Nix store submit-output 命令详解:在内容寻址派生中通过 builder RPC 提交输出
导读
nix store submit-output 是 Nix 包管理器中用于"构建内提交"(build-time submission)的专用命令:它把一个已经存在的 store object 注册为当前正在构建的派生(derivation)的某个命名输出。该命令只在启用了 builder-rpc-v0 系统特性的内容寻址(content-addressing)派生内部有效,任何其他环境下执行都会失败。阅读本文后,你将理解该命令的完整语法、运行前提、底层调用链(从 CLI 到 SubmitStore 抽象再到沙箱内 daemon socket),以及它与动态派生(dynamic derivations)和递归 Nix 特性的关系。
命令概览
nix store submit-output 的功能定义来自 store-submit-output.md:
nix store submit-outputregisters a store object as an output of the currently-running derivation.
即:将某个 store object 注册为"当前正在运行的派生"的一个输出。命令的完整实现位于 store-submit-output.cc,它通过 registerCommand2<CmdSubmitOutput>({"store", "submit-output"}) 注册为 nix store 子命令。
官方示例
原文档给出的唯一示例是将给定的 store object 提交为名为 out 的输出:
# nix store submit-output /nix/store/h6zs50y2662apmnbcnhnbxll76lv02yy-hello-2.12.3 out
其中:
- 第一个位置参数
path是要注册的 store object 的路径(示例中是hello-2.12.3的 store path); - 第二个位置参数
output是派生输出名(示例中为out,也可以是多输出派生的其他名称,如dev、man等)。
适用环境(关键前提)
原文档明确强调两点约束:
- 仅限内容寻址派生:命令只在"content-addressing derivation"内部运行;
- 要求
builder-rpc-v0系统特性:该特性为 builder 提供一个受限的 daemon socket("which provides a limited daemon socket to the builder"),命令通过这个 socket 与守护进程通信。
任何其他环境下的执行都会失败("Execution in any other environment will fail")。
为什么需要这个命令:RPC 输出机制
要理解该命令的存在意义,需要先了解 builder-rpc-v0 系统特性带来的输出传递机制变化。
在传统的派生构建中,输出路径通过环境变量传给 builder:initEnv() 会把输出名对应的 store path 写入 builder 的环境变量(如 out=/nix/store/...)。而在 derivations.cc 的 fillDerivation 逻辑中可以看到,当派生启用了 builder-rpc-v0 特性后,行为完全不同:
- 输出不再通过环境变量传递,而是"通过 RPC 传达给 builder"("outputs are communicated to the builder over RPC rather than via environment variables");
- 该特性只能用于内容寻址派生:源码中直接抛错 "derivation uses the '%s' feature, which may only be used with content-addressing derivations"。
因此,在这种模式下,builder 无法从环境变量得知自己的输出路径应该是什么,而必须主动通过 RPC 告诉守护进程"我要把某个 store object 作为我的某个输出",这正是 nix store submit-output 的职责。
底层实现:命令如何解析与执行
store-submit-output.cc 中 CmdSubmitOutput 的完整流程:
- 构造函数注册两个位置参数:
expectArg("path", &path)与expectArg("output", &output),对应上面的path和output参数; - 声明实验特性:
experimentalFeature()返回Xp::DynamicDerivations,即使用该命令前必须启用dynamic-derivations实验特性(见下文"实验特性"小节); - 运行时类型检查:
require<SubmitStore>(*store)要求当前 store 支持SubmitStore接口,否则抛出错误; - 解析路径:
SingleDerivedPath::parse(*store, this->path)把字符串路径解析为 SingleDerivedPath 类型(见下文"SingleDerivedPath 解析"小节); - 提交输出:调用
submitStore.submitOutput(path, output)完成注册。
命令的 description() 为 "submit a store object as one of the outputs of the derivation currently being built",与官方文档语义一致。
SingleDerivedPath 解析
path 参数不是普通的 store path 字符串,而是被解析为 SingleDerivedPath。根据 derived-path.hh 的定义,该类型有两种形态:
- Opaque(
DerivedPathOpaque):一个具体的、已求值的 store path; - Built(
SingleDerivedPathBuilt):"一个派生 + 一个输出名"的组合,求值方式是先构建该派生再取对应输出路径。
从当前实现看,submitOutput 实际上只接受 Opaque 形态的路径(详见下文"实现细节与限制")。
底层实现:SubmitStore 抽象接口
submitOutput 所在的接口定义在 submit-store.hh,其声明如下:
struct SubmitStore : public virtual Store
{
inline static std::string operationName = "Submit outputs for a currently running derivation";
virtual void submitOutput(const SingleDerivedPath & path, const OutputName & output) = 0;
virtual ref<const ValidPathInfo> addToStoreScanning(
Source & dump,
std::string_view name,
FileSerialisationMethod dumpMethod = FileSerialisationMethod::NixArchive,
ContentAddressMethod hashMethod = ContentAddressMethod::Raw::NixArchive,
HashAlgorithm hashAlgo = HashAlgorithm::SHA256) = 0;
static SubmitStore & require(Store & store);
};
值得注意的几点:
- 头文件注释明确指出该接口"只有在 recursive-nix 派生内部运行才有意义"("Only makes sense when running within a recursive-nix derivation"),因为只有在这种受限环境中才存在"已知的合法 store path 集合";
- 接口除了
submitOutput,还包含addToStoreScanning——后者在扫描引用的同时把 store object 加入存储,同样只允许在 recursive-nix/builder-rpc-v0 派生内调用(见下文"姊妹命令:add-to-store --scan")。
受限 store 与沙箱内 daemon socket
当派生启用 builder-rpc-v0 或 recursive-nix 系统特性时,构建过程会启动一个受限的 daemon 供 builder 调用。关键逻辑在 unix-derivation-builder.cc:
- 第 351-360 行:从派生的
requiredSystemFeatures中检测builder-rpc-v0,若启用则要求派生必须是内容寻址派生,否则抛错 "The builder-rpc-v0 feature may only be used with content-addressing derivations";随后调用startDaemon(); - 第 672-697 行:
startDaemon()在沙箱内的临时目录创建名为.nix-socket的 Unix domain socket,并把环境变量NIX_REMOTE=unix://...写入 builder 环境——builder 内部运行的nix命令(包括nix store submit-output)就会通过这个 socket 连回受限 daemon; - 根据特性不同,daemon 使用不同的递归标志:
builder-rpc-v0对应RecursiveFlag::RecursiveSubmitted,recursive-nix对应RecursiveFlag::Recursive。
受限 daemon 侧的 store 由 restricted-store.cc 中的 RestrictedStore 提供。它包装一个 LocalStore,仅允许访问"构建输入闭包中的路径或通过递归 Nix 调用新增的路径"(见 restricted-store.hh 的注释)。RestrictedStore::submitOutput 直接转发给 RestrictionContext::submitOutput(restricted-store.cc)。
daemon 侧的协议校验
在 worker 协议层,daemon 对 SubmitOutput 操作有严格的校验,见 daemon.cc:
case WorkerProto::Op::SubmitOutput: {
experimentalFeatureSettings.require(Xp::DynamicDerivations);
if (recursive != daemon::RecursiveFlag::RecursiveSubmitted)
throw Error("SubmitOutput only valid within derivation with `builder-rpc-v0` feature");
...
submitStore.submitOutput(path, output);
break;
}
两个硬性条件缺一不可:
- 必须启用
dynamic-derivations实验特性(否则直接拒绝); - 连接必须来自
builder-rpc-v0派生(RecursiveFlag::RecursiveSubmitted),而不是普通recursive-nix派生,否则报错 "SubmitOutput only valid within derivation withbuilder-rpc-v0feature"。
类似地,AddToStoreScanning 操作在 daemon 侧要求递归标志为 Recursive 或 RecursiveSubmitted(daemon.cc)。这从协议层面印证了官方文档"在任何其他环境执行都会失败"的说法。
实现细节与限制:Opaque 路径与重复输出检查
最终落地到 UnixDerivationBuilderImpl::submitOutput(unix-derivation-builder.cc),该实现有两个值得注意的限制:
1. 仅支持 Opaque 路径
auto * opaque = std::get_if<SingleDerivedPath::Opaque>(&path.raw());
if (!opaque)
throw Error(
"Attempted to submit Built path '%s' for output '%s'.\n"
" Only Opaque paths are supported, ...",
...);
如果传入的是 Built 形态("派生^输出名")的路径,会直接报错:目前只支持 Opaque(具体 store path)形态。
2. 拒绝重复提交
if (submittedOutputs->contains(output))
throw Error(
"Attempted to submit duplicate output '%s' (old '%s', new '%s')",
...);
submittedOutputs->insert_or_assign(output, opaque->path);
每个输出名只能提交一次,重复提交同一输出名会报错并同时显示旧值和新值。
实验特性:dynamic-derivations
如前所述,使用该命令需要启用 dynamic-derivations 实验特性。其官方描述位于 experimental-features.cc:
Allow the use of a few things related to dynamic derivations:
- "text hashing" derivation outputs, so we can build .drv files.
- dependencies in derivations on the outputs of derivations that are themselves derivations outputs.
启用方式(nix.conf 或命令行):
# nix --extra-experimental-features 'nix-command dynamic-derivations' store submit-output ...
注意 nix store 系列命令本身也属于 nix-command 实验特性。由于 builder-rpc-v0 用于动态派生场景(输出 .drv 文件以便后续派生依赖它们),因此该命令与动态派生紧密绑定。
姊妹命令:add-to-store --scan
SubmitStore 接口中还定义了 addToStoreScanning,它同样只能在受限的构建环境中调用。其 CLI 入口在 add-to-store.cc:当使用 nix store add --scan 时,会调用 require<SubmitStore>(*store) 获取受限 store,并通过 submitStore.addToStoreScanning(...) 在扫描引用的同时把内容加入存储。
从 daemon 侧看(daemon.cc),AddToStoreScanning 会把当前受限环境下已知的合法路径集合作为引用候选集(RestrictedStore::addToStoreScanning 中调用 next->addToStoreFromDump(..., queryAllValidPaths(), ...),见 restricted-store.cc),这正是"存在已知合法路径集合"才有意义的体现。二者共同构成了 builder 在构建内"造出内容 → 提交为输出"的完整能力。
相关概念:store object
文档中链接的 store object 概念 指出:Nix store 是 store object 的集合,一个 store object 由"文件系统对象(数据)+ 一组引用(store path 集合)"组成,且引用图(排除自引用后)必须是无环有向图。nix store submit-output 提交的正是这样一个 store object——把它的 store path 与当前派生的某个输出名绑定。
常见失败场景与排查
根据文档与源码,以下情况必然失败:
| 场景 | 失败原因(源码依据) |
|---|---|
| 在普通 shell 中直接运行 | 没有受限 daemon socket,require<SubmitStore> 或协议校验不通过 |
在非内容寻址派生中声明 builder-rpc-v0 |
unix-derivation-builder.cc 与 derivations.cc 双重拦截 |
在普通 recursive-nix 派生中调用 |
daemon.cc:要求 RecursiveSubmitted 标志 |
未启用 dynamic-derivations 实验特性 |
命令本身与 daemon 协议双重校验 |
提交 Built 形态路径 |
unix-derivation-builder.cc |
| 同一输出名重复提交 | unix-derivation-builder.cc |
总结
nix store submit-output 是 Nix 动态派生(dynamic derivations)机制中的关键一环:在 builder-rpc-v0 系统特性开启时,派生的输出不再由环境变量传递,而是由 builder 在沙箱内通过受限 daemon socket 主动提交。其完整链路为:CLI 解析(store-submit-output.cc)→ SubmitStore 抽象(submit-store.hh)→ 受限 store 转发(restricted-store.cc)→ daemon 协议校验(daemon.cc)→ 构建器落地(unix-derivation-builder.cc)。理解这条链路,有助于正确使用动态派生特性,也能在调试构建错误时快速定位是环境、协议还是参数形态导致的问题。