Nixpkgs 固定点参数(Fixed-point Arguments):从 `finalAttrs` 到 `lib.extendMkDerivation` 的构建辅助函数定制指南
Nixpkgs 固定点参数(Fixed-point Arguments):从 finalAttrs 到 lib.extendMkDerivation 的构建辅助函数定制指南
导读
本篇指南围绕 Nixpkgs 手册中 fixed-point-arguments.chapter.md 的核心内容展开,讲解 stdenv.mkDerivation 如何接受固定点函数(而非普通属性集)来定义包,以及如何借助 lib.extendMkDerivation 从既有构建辅助函数派生出支持固定点参数的新辅助函数。读完本文,你将理解 finalAttrs 与 overrideAttrs 的协作原理、rec 自引用为何无法响应覆盖,并掌握 extendDrvArgs、excludeDrvArgNames、transformDrv 等关键参数的实战用法——这些正是 Nixpkgs 中 fetchurl 等内置 fetcher 的实现基础。
一、固定点参数:让属性集自引用保持"活"的状态
stdenv.mkDerivation 除了接收普通的属性集外,还接收一个固定点函数:
{
stdenv,
fetchurl,
}:
stdenv.mkDerivation (finalAttrs: {
pname = "hello";
version = "2.12";
src = fetchurl {
url = "mirror://gnu/hello/hello-${finalAttrs.version}.tar.gz";
hash = "sha256-...";
};
})
这里的函数输入被约定命名为 finalAttrs,它代表属性集的最终状态(final state)。在上面的示例中,src 通过 finalAttrs.version 读取版本号,而不再把版本字符串重复写一遍。这种接受固定点参数的构建辅助函数(build helper),就被称为支持 fixed-point arguments。
1.1 底层机制:lib.fixedPoints.fix
固定点(fixed point)的本质在 lib/fixed-points.nix 中有精确定义:
fix =
f:
let
x = f x;
in
x;
即 fix f 返回 f 的不动点 x,其中 x 是通过自身调用 f 得到的。把这个思路套用到 stdenv.mkDerivation (finalAttrs: { ... }) 上,finalAttrs 就是那个"既是被构建的最终结果、又同时参与构造自身"的 x。属性集内部任何对 finalAttrs.<attr> 的引用,都是在引用整个计算的最终结果。
1.2 与 overrideAttrs 的协作:覆盖后依然自洽
固定点参数最关键的价值在于覆盖一致性。凡是经由 finalAttrs 相互引用的属性,在使用 overrideAttrs 修改其中任意一个时,其余属性都会自动读取到覆盖后的最终值,因此始终正确。
hello.overrideAttrs (finalAttrs: {
version = "2.13";
# src 内部引用 finalAttrs.version,会自动跟随新的版本号
})
这一点在 lib/customisation.nix 中 makeOverridable 的实现里得到了印证——overrideAttrs 正是通过 makeOverridable 挂到每个派生上的:
overrideAttrs =
fdrv: makeOverridable (mirrorArgs (args: (f args).overrideAttrs fdrv)) origArgs;
1.3 为什么 rec 做不到这件事
rec 的自我引用在属性集定义时就被固化了,后续的 overrideAttrs 覆盖不会改变这些引用:
rec {
version = "2.12";
src = fetchurl { url = ".../hello-${version}.tar.gz"; };
}
# 之后即使覆盖 version,src 里被固化的引用仍指向旧的 "2.12"
这正是 lib/fixed-points.nix 中 fix 与普通递归属性集(recursive set)的本质区别:rec 是一阶自引用,固定点则是经过 f x 迭代得到的最终值。因此,凡是可能在派生创建后被 overrideAttrs 修改、且又被其他属性引用的字段,都应通过 finalAttrs 来访问。
二、用 lib.extendMkDerivation 定义支持固定点的构建辅助函数
Nixpkgs 提供 lib.customisation.extendMkDerivation,让你可以从一个已有构建辅助函数(通常是 stdenv.mkDerivation)派生出新的、支持固定点参数的构建辅助函数。
其函数签名为(lib/customisation.nix):
extendMkDerivation ::
{
constructDrv :: (FixedPointArgs | AttrSet) -> Derivation;
excludeDrvArgNames :: [String];
excludeFunctionArgNames :: [String];
extendDrvArgs :: AttrSet -> AttrSet -> AttrSet;
inheritFunctionArgs :: Bool;
transformDrv :: Derivation -> Derivation;
}
-> ((FixedPointArgs | AttrSet) -> Derivation)
各参数含义如下:
| 参数 | 默认值 | 作用 |
|---|---|---|
constructDrv |
必填 | 底层基础构建辅助函数,如 stdenv.mkDerivation |
extendDrvArgs |
必填 | 一个属性叠加层(attribute overlay),形式与 <pkg>.overrideAttrs 类似,用于扩展传给 constructDrv 的参数 |
excludeDrvArgNames |
[] |
从输入固定点参数中排除的部分参数,不向下传给基础构建辅助函数 |
excludeFunctionArgNames |
[] |
从结果辅助函数的 __functionArgs 中排除的参数名 |
inheritFunctionArgs |
true |
是否从基础构建辅助函数继承 __functionArgs;当 extendDrvArgs 的 args 集合模式不含省略号(ellipsis)时应设为 false |
transformDrv |
lib.id |
对结果派生应用的变换函数 |
2.1 示例一:mkLocalDerivation——默认本地构建、不使用 substitutes
手册中的第一个完整示例(fixed-point-arguments.chapter.md)定义了一个名为 mkLocalDerivation 的构建辅助函数,它默认在本地构建、不使用二进制缓存替换(substitutes):
{
lib,
stdenv,
}:
lib.extendMkDerivation {
constructDrv = stdenv.mkDerivation;
excludeDrvArgNames = [
# Don't pass specialArg into mkDerivation.
"specialArg"
];
extendDrvArgs =
finalAttrs:
{
preferLocalBuild ? true,
allowSubstitute ? false,
specialArg ? (_: false),
...
}@args:
{
# Arguments to pass
inherit preferLocalBuild allowSubstitute;
# Some expressions involving specialArg
greeting = if specialArg "hi" then "hi" else "hello";
};
}
理解这个例子的关键在于两层参数结构:
- 外层函数
finalAttrs:接收派生属性集的最终状态,用于让派生内部引用彼此(固定点支持); - 内层参数集模式(带
@args与...)负责声明这个新辅助函数的"公开接口"——preferLocalBuild、allowSubstitute、specialArg都是调用者可以传入的新参数。
在返回的属性集中,inherit preferLocalBuild allowSubstitute; 把新参数转化为传给 stdenv.mkDerivation 的普通参数;而 specialArg 通过 excludeDrvArgNames 被明确排除,避免它被误传给底层 mkDerivation。这与 lib/customisation.nix 中 extendMkDerivation 的实现一一对应:
__functor =
self: fpargs:
transformDrv (
constructDrv (
final:
let
previous = if isFunction fpargs then fpargs final else fpargs;
in
removeAttrs previous excludeDrvArgNames // extendDrvArgs final previous
)
);
可以看到,输入 fpargs 既可以是普通属性集,也可以是固定点函数(isFunction fpargs 分支);随后先按 excludeDrvArgNames 移除参数,再用 extendDrvArgs final previous 把扩展参数叠加进去,最后交给 constructDrv 并经过 transformDrv 变换。
2.2 派生辅助函数的 __functionArgs 与示例验证
新派生的辅助函数会暴露一份正确的 __functionArgs,这正是 Nixpkgs 通过 callPackage 自动传参的基础。在 lib/customisation.nix 的 REPL 示例中:
mkLocalDerivation = lib.extendMkDerivation {
constructDrv = pkgs.stdenv.mkDerivation;
excludeDrvArgNames = [ "specialArg" ];
extendDrvArgs =
finalAttrs: args@{ preferLocalBuild ? true, allowSubstitute ? false, specialArg ? (_: false), ... }:
{ inherit preferLocalBuild allowSubstitute; passthru = { inherit specialArg; } // args.passthru or { }; };
}
mkLocalDerivation.__functionArgs
=> { allowSubstitute = true; preferLocalBuild = true; specialArg = true; }
注意 specialArg 虽然被 excludeDrvArgNames 排除、不会传给 mkDerivation,但它仍出现在 __functionArgs 中,作为该辅助函数的合法调用参数。此外,派生结果同时支持两种调用形式:
mkLocalDerivation { inherit (pkgs.hello) pname version src; specialArg = _: false; }
=> «derivation /nix/store/...-hello-2.12.1.drv»
mkLocalDerivation (finalAttrs: { inherit (pkgs.hello) pname version src; specialArg = _: false; })
=> «derivation /nix/store/...-hello-2.12.1.drv»
而且固定点自引用在派生后依然成立——passthru.bar 通过 finalAttrs.passthru.foo 引用前一个属性:
(mkLocalDerivation (finalAttrs: { inherit (pkgs.hello) pname version src; passthru = { foo = "a"; bar = "${finalAttrs.passthru.foo}b"; }; })).bar
=> "ab"
三、transformDrv:对结果派生做最终变换
除了向 constructDrv 传入扩展参数外,extendMkDerivation 还支持通过 transformDrv 对最终生成的派生再应用一次变换:
lib.customisation.extendMkDerivation { transformDrv = drv: /...; }
transformDrv 的默认值是 lib.id(即不做任何变换)。它的典型用途是在另一个派生周围构造包装派生(wrapper derivation),且包装器能够访问原始参数。
3.1 示例二:一个"下载并构建"的自定义构建辅助函数
手册中的第二个完整示例(fixed-point-arguments.chapter.md)定义了一个同时承担"下载"与"构建配置"任务的辅助函数:
{
lib,
stdenvNoCC,
cacert,
configure-example,
download-example,
}:
lib.extendMkDerivation {
constructDrv = stdenvNoCC.mkDerivation;
excludeDrvArgNames = [
"bar"
];
extendDrvArgs =
finalAttrs:
{
bar,
foo,
hash ? "",
...
}@args:
{
inherit hash;
nativeBuildInputs = args.nativeBuildInputs or [ ] ++ [
cacert
download-example
];
buildPhase = ''
runHook preBuild
download-example --foo="$foo" --out="$out"
runHook postBuild
'';
impureEnvVars = lib.fetchers.proxyImpureEnvVars;
outputHash = if finalAttrs.hash != "" then finalAttrs.hash else lib.fakeHash;
outputHashFormat = "recursive";
passthru = args.passthru or { } // {
inherit bar;
};
};
transformDrv =
unwrapped:
stdenvNoCC.mkDerivation (finalAttrs: {
name = finalAttrs.src.name + "-wrapped";
src = unwrapped;
nativeBuildInputs = [
configure-example
];
inherit (unwrapped) bar;
buildPhase = ''
runHook preBuild
configure-example --bar="$bar"
runHook postBuild
'';
});
}
逐段拆解这个例子:
-
extendDrvArgs部分(生成"未包装"的下载派生unwrapped):hash通过finalAttrs.hash参与固定点计算——当调用者传入hash时使用真实哈希,否则退回lib.fakeHash;outputHash/outputHashFormat = "recursive"使该派生具备固定输出(fixed-output derivation),供下载类场景使用;impureEnvVars = lib.fetchers.proxyImpureEnvVars允许代理环境变量透传,这正是 Nixpkgs 网络拉取类辅助函数的标准做法;bar通过excludeDrvArgNames排除而不下传,同时经passthru保留给后续包装层使用。
-
transformDrv部分(生成包装派生):unwrapped作为新派生的src;- 通过
inherit (unwrapped) bar;访问原始派生上的参数,证明包装层确实能拿到未包装派生的数据; name用finalAttrs.src.name + "-wrapped"派生自内层派生名,形成清晰的命名链。
这种"基础派生 + 包装派生"的两段式结构,是 transformDrv 最具代表性的应用模式。
3.2 使用 transformDrv 的注意事项
lib/customisation.nix 对 transformDrv 给出了明确告诫:如果指定了 transformDrv,它必须妥善处理那些负责"覆盖"的既有属性(例如 overrideAttrs),以保证结果派生的覆盖功能按预期工作。会破坏覆盖能力的两类典型操作包括:
- 对派生做直接的属性集更新(attribute set update,即
//运算); - 使用
lib.extendDerivation修改派生。
因此,在自定义 transformDrv 时,应尽量通过 stdenv.mkDerivation 这类保留 overrideAttrs 的机制来构造包装派生,而不是直接覆盖整个派生对象。
四、仓库中的真实应用:fetchurl 就是这么做的
固定点参数的用法并非纸面设计,Nixpkgs 的核心 fetcher fetchurl 就是通过 lib.extendMkDerivation 从 stdenvNoCC.mkDerivation 派生的(pkgs/build-support/fetchurl/default.nix):
lib.extendMkDerivation {
constructDrv = stdenvNoCC.mkDerivation;
excludeDrvArgNames = [
# Passed via passthru
"url"
# Additional stdenv.mkDerivation arguments from derived fetchers.
"derivationArgs"
# Hash attributes will be map to the corresponding outputHash*
"sha1"
"sha256"
"sha512"
];
...
}
从源码注释可以看到几个要点:
url、derivationArgs、sha1/sha256/sha512这些 fetcher 专用参数通过excludeDrvArgNames被排除,不会直接透传给stdenvNoCC.mkDerivation,而是由extendDrvArgs内部把它们映射为对应的outputHash*系列属性;extendDrvArgs为 fetcher 声明了一整套用户可见的参数接口:url/urls、curlOpts/curlOptsList、name/pname/version、hash(SRI)、旧式outputHash/outputHashAlgo/sha1/sha256/sha512、recursiveHash、netrcPhase等,并给出默认值(如url ? ""、hash ? "");- 该文件同样设置了
impureEnvVars = lib.fetchers.proxyImpureEnvVars ++ [ "NIX_CURL_FLAGS" "NIX_HASHED_MIRRORS" "NIX_CONNECT_TIMEOUT" ... ],与示例中的proxyImpureEnvVars用法互相印证。
从源码结构看,fetchurl 之外的派生 fetcher(如 fetchzip、fetchgit 等)也可以通过 derivationArgs 机制向 fetchurl 追加 stdenv.mkDerivation 参数——这正是 excludeDrvArgNames 中专门保留 derivationArgs 不被下传的原因。
五、实践要点小结
- 优先使用固定点函数而非
rec:凡是会被overrideAttrs修改、又被其他属性引用的值(典型如version与src),一律通过finalAttrs.<attr>引用,确保覆盖后全链路自洽; extendDrvArgs是"接口声明 + 参数转换"的合体:外层finalAttrs:提供固定点能力,内层带默认值的参数集模式定义公开接口,返回属性集负责把这些参数转译为constructDrv能理解的参数;excludeDrvArgNames用于隔离专用参数:不想透传给底层构建辅助函数的参数(如specialArg、bar、fetcher 的url/hash 族)要显式列出,必要时通过passthru保留给上层使用;transformDrv用于包装派生:做包装时请保留overrideAttrs等覆盖机制,避免直接对派生做//更新或用lib.extendDerivation破坏可覆盖性;- 调用形式兼容:
extendMkDerivation派生的辅助函数同时接受普通属性集和固定点函数两种调用方式(lib/customisation.nix 中isFunction fpargs分支保证),且__functionArgs会自动继承基础辅助函数并合并extendDrvArgs声明的参数,与callPackage无缝配合。
延伸阅读
- lib.customisation.extendMkDerivation 官方文档(含完整类型签名、REPL 示例与
transformDrv注意事项) - lib.fixedPoints.fix 与 fix' 实现(固定点的底层机制)
- fetchurl 的 extendMkDerivation 实例(生产级应用范例)
- doc/build-helpers 相关章节(其他构建辅助函数文档)