Nix `store submit-output` 命令详解:在内容寻址派生中通过 builder RPC 提交输出

原创2026-09-21 22:48:531,938 阅读
文章标签:包管理器构建工具开发工具编程语言配置管理操作系统

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-output registers 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 等)。

适用环境(关键前提)

原文档明确强调两点约束:

  1. 仅限内容寻址派生:命令只在"content-addressing derivation"内部运行;
  2. 要求 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 的完整流程:

  1. 构造函数注册两个位置参数:expectArg("path", &path) 与 expectArg("output", &output),对应上面的 path 和 output 参数;
  2. 声明实验特性:experimentalFeature() 返回 Xp::DynamicDerivations,即使用该命令前必须启用 dynamic-derivations 实验特性(见下文"实验特性"小节);
  3. 运行时类型检查:require<SubmitStore>(*store) 要求当前 store 支持 SubmitStore 接口,否则抛出错误;
  4. 解析路径:SingleDerivedPath::parse(*store, this->path) 把字符串路径解析为 SingleDerivedPath 类型(见下文"SingleDerivedPath 解析"小节);
  5. 提交输出:调用 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;
}

两个硬性条件缺一不可:

  1. 必须启用 dynamic-derivations 实验特性(否则直接拒绝);
  2. 连接必须来自 builder-rpc-v0 派生(RecursiveFlag::RecursiveSubmitted),而不是普通 recursive-nix 派生,否则报错 "SubmitOutput only valid within derivation with builder-rpc-v0 feature"。

类似地,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)。理解这条链路,有助于正确使用动态派生特性,也能在调试构建错误时快速定位是环境、协议还是参数形态导致的问题。

登录后查看全文
nix