pyrox.dev
1{ lib }:
2
3let
4 inherit (builtins)
5 intersectAttrs;
6 inherit (lib)
7 functionArgs isFunction mirrorFunctionArgs isAttrs setFunctionArgs
8 optionalAttrs attrNames filter elemAt concatStringsSep sortOn take length
9 filterAttrs optionalString flip pathIsDirectory head pipe isDerivation listToAttrs
10 mapAttrs seq flatten deepSeq warnIf isInOldestRelease extends
11 ;
12 inherit (lib.strings) levenshtein levenshteinAtMost;
13
14in
15rec {
16
17
18 /**
19 `overrideDerivation drv f` takes a derivation (i.e., the result
20 of a call to the builtin function `derivation`) and returns a new
21 derivation in which the attributes of the original are overridden
22 according to the function `f`. The function `f` is called with
23 the original derivation attributes.
24
25 `overrideDerivation` allows certain "ad-hoc" customisation
26 scenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance,
27 if you want to "patch" the derivation returned by a package
28 function in Nixpkgs to build another version than what the
29 function itself provides.
30
31 For another application, see build-support/vm, where this
32 function is used to build arbitrary derivations inside a QEMU
33 virtual machine.
34
35 Note that in order to preserve evaluation errors, the new derivation's
36 outPath depends on the old one's, which means that this function cannot
37 be used in circular situations when the old derivation also depends on the
38 new one.
39
40 You should in general prefer `drv.overrideAttrs` over this function;
41 see the nixpkgs manual for more information on overriding.
42
43
44 # Inputs
45
46 `drv`
47
48 : 1\. Function argument
49
50 `f`
51
52 : 2\. Function argument
53
54 # Type
55
56 ```
57 overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
58 ```
59
60 # Examples
61 :::{.example}
62 ## `lib.customisation.overrideDerivation` usage example
63
64 ```nix
65 mySed = overrideDerivation pkgs.gnused (oldAttrs: {
66 name = "sed-4.2.2-pre";
67 src = fetchurl {
68 url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
69 hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
70 };
71 patches = [];
72 });
73 ```
74
75 :::
76 */
77 overrideDerivation = drv: f:
78 let
79 newDrv = derivation (drv.drvAttrs // (f drv));
80 in flip (extendDerivation (seq drv.drvPath true)) newDrv (
81 { meta = drv.meta or {};
82 passthru = if drv ? passthru then drv.passthru else {};
83 }
84 //
85 (drv.passthru or {})
86 //
87 optionalAttrs (drv ? __spliced) {
88 __spliced = {} // (mapAttrs (_: sDrv: overrideDerivation sDrv f) drv.__spliced);
89 });
90
91
92 /**
93 `makeOverridable` takes a function from attribute set to attribute set and
94 injects `override` attribute which can be used to override arguments of
95 the function.
96
97 Please refer to documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats
98 related to its use.
99
100
101 # Inputs
102
103 `f`
104
105 : 1\. Function argument
106
107 # Type
108
109 ```
110 makeOverridable :: (AttrSet -> a) -> AttrSet -> a
111 ```
112
113 # Examples
114 :::{.example}
115 ## `lib.customisation.makeOverridable` usage example
116
117 ```nix
118 nix-repl> x = {a, b}: { result = a + b; }
119
120 nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }
121
122 nix-repl> y
123 { override = «lambda»; overrideDerivation = «lambda»; result = 3; }
124
125 nix-repl> y.override { a = 10; }
126 { override = «lambda»; overrideDerivation = «lambda»; result = 12; }
127 ```
128
129 :::
130 */
131 makeOverridable = f:
132 let
133 # Creates a functor with the same arguments as f
134 mirrorArgs = mirrorFunctionArgs f;
135 in
136 mirrorArgs (origArgs:
137 let
138 result = f origArgs;
139
140 # Changes the original arguments with (potentially a function that returns) a set of new attributes
141 overrideWith = newArgs: origArgs // (if isFunction newArgs then newArgs origArgs else newArgs);
142
143 # Re-call the function but with different arguments
144 overrideArgs = mirrorArgs (newArgs: makeOverridable f (overrideWith newArgs));
145 # Change the result of the function call by applying g to it
146 overrideResult = g: makeOverridable (mirrorArgs (args: g (f args))) origArgs;
147 in
148 if isAttrs result then
149 result // {
150 override = overrideArgs;
151 overrideDerivation = fdrv: overrideResult (x: overrideDerivation x fdrv);
152 ${if result ? overrideAttrs then "overrideAttrs" else null} = fdrv:
153 overrideResult (x: x.overrideAttrs fdrv);
154 }
155 else if isFunction result then
156 # Transform the result into a functor while propagating its arguments
157 setFunctionArgs result (functionArgs result) // {
158 override = overrideArgs;
159 }
160 else result);
161
162
163 /**
164 Call the package function in the file `fn` with the required
165 arguments automatically. The function is called with the
166 arguments `args`, but any missing arguments are obtained from
167 `autoArgs`. This function is intended to be partially
168 parameterised, e.g.,
169
170 ```nix
171 callPackage = callPackageWith pkgs;
172 pkgs = {
173 libfoo = callPackage ./foo.nix { };
174 libbar = callPackage ./bar.nix { };
175 };
176 ```
177
178 If the `libbar` function expects an argument named `libfoo`, it is
179 automatically passed as an argument. Overrides or missing
180 arguments can be supplied in `args`, e.g.
181
182 ```nix
183 libbar = callPackage ./bar.nix {
184 libfoo = null;
185 enableX11 = true;
186 };
187 ```
188
189 <!-- TODO: Apply "Example:" tag to the examples above -->
190
191
192 # Inputs
193
194 `autoArgs`
195
196 : 1\. Function argument
197
198 `fn`
199
200 : 2\. Function argument
201
202 `args`
203
204 : 3\. Function argument
205
206 # Type
207
208 ```
209 callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
210 ```
211 */
212 callPackageWith = autoArgs: fn: args:
213 let
214 f = if isFunction fn then fn else import fn;
215 fargs = functionArgs f;
216
217 # All arguments that will be passed to the function
218 # This includes automatic ones and ones passed explicitly
219 allArgs = intersectAttrs fargs autoArgs // args;
220
221 # a list of argument names that the function requires, but
222 # wouldn't be passed to it
223 missingArgs =
224 # Filter out arguments that have a default value
225 (filterAttrs (name: value: ! value)
226 # Filter out arguments that would be passed
227 (removeAttrs fargs (attrNames allArgs)));
228
229 # Get a list of suggested argument names for a given missing one
230 getSuggestions = arg: pipe (autoArgs // args) [
231 attrNames
232 # Only use ones that are at most 2 edits away. While mork would work,
233 # levenshteinAtMost is only fast for 2 or less.
234 (filter (levenshteinAtMost 2 arg))
235 # Put strings with shorter distance first
236 (sortOn (levenshtein arg))
237 # Only take the first couple results
238 (take 3)
239 # Quote all entries
240 (map (x: "\"" + x + "\""))
241 ];
242
243 prettySuggestions = suggestions:
244 if suggestions == [] then ""
245 else if length suggestions == 1 then ", did you mean ${elemAt suggestions 0}?"
246 else ", did you mean ${concatStringsSep ", " (lib.init suggestions)} or ${lib.last suggestions}?";
247
248 errorForArg = arg:
249 let
250 loc = builtins.unsafeGetAttrPos arg fargs;
251 # loc' can be removed once lib/minver.nix is >2.3.4, since that includes
252 # https://github.com/NixOS/nix/pull/3468 which makes loc be non-null
253 loc' = if loc != null then loc.file + ":" + toString loc.line
254 else if ! isFunction fn then
255 toString fn + optionalString (pathIsDirectory fn) "/default.nix"
256 else "<unknown location>";
257 in "Function called without required argument \"${arg}\" at "
258 + "${loc'}${prettySuggestions (getSuggestions arg)}";
259
260 # Only show the error for the first missing argument
261 error = errorForArg (head (attrNames missingArgs));
262
263 in if missingArgs == {}
264 then makeOverridable f allArgs
265 # This needs to be an abort so it can't be caught with `builtins.tryEval`,
266 # which is used by nix-env and ofborg to filter out packages that don't evaluate.
267 # This way we're forced to fix such errors in Nixpkgs,
268 # which is especially relevant with allowAliases = false
269 else abort "lib.customisation.callPackageWith: ${error}";
270
271
272 /**
273 Like callPackage, but for a function that returns an attribute
274 set of derivations. The override function is added to the
275 individual attributes.
276
277
278 # Inputs
279
280 `autoArgs`
281
282 : 1\. Function argument
283
284 `fn`
285
286 : 2\. Function argument
287
288 `args`
289
290 : 3\. Function argument
291
292 # Type
293
294 ```
295 callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet
296 ```
297 */
298 callPackagesWith = autoArgs: fn: args:
299 let
300 f = if isFunction fn then fn else import fn;
301 auto = intersectAttrs (functionArgs f) autoArgs;
302 mirrorArgs = mirrorFunctionArgs f;
303 origArgs = auto // args;
304 pkgs = f origArgs;
305 mkAttrOverridable = name: _: makeOverridable (mirrorArgs (newArgs: (f newArgs).${name})) origArgs;
306 in
307 if isDerivation pkgs then throw
308 ("function `callPackages` was called on a *single* derivation "
309 + ''"${pkgs.name or "<unknown-name>"}";''
310 + " did you mean to use `callPackage` instead?")
311 else mapAttrs mkAttrOverridable pkgs;
312
313
314 /**
315 Add attributes to each output of a derivation without changing
316 the derivation itself and check a given condition when evaluating.
317
318
319 # Inputs
320
321 `condition`
322
323 : 1\. Function argument
324
325 `passthru`
326
327 : 2\. Function argument
328
329 `drv`
330
331 : 3\. Function argument
332
333 # Type
334
335 ```
336 extendDerivation :: Bool -> Any -> Derivation -> Derivation
337 ```
338 */
339 extendDerivation = condition: passthru: drv:
340 let
341 outputs = drv.outputs or [ "out" ];
342
343 commonAttrs = drv // (listToAttrs outputsList) //
344 ({ all = map (x: x.value) outputsList; }) // passthru;
345
346 outputToAttrListElement = outputName:
347 { name = outputName;
348 value = commonAttrs // {
349 inherit (drv.${outputName}) type outputName;
350 outputSpecified = true;
351 drvPath = assert condition; drv.${outputName}.drvPath;
352 outPath = assert condition; drv.${outputName}.outPath;
353 } //
354 # TODO: give the derivation control over the outputs.
355 # `overrideAttrs` may not be the only attribute that needs
356 # updating when switching outputs.
357 optionalAttrs (passthru?overrideAttrs) {
358 # TODO: also add overrideAttrs when overrideAttrs is not custom, e.g. when not splicing.
359 overrideAttrs = f: (passthru.overrideAttrs f).${outputName};
360 };
361 };
362
363 outputsList = map outputToAttrListElement outputs;
364 in commonAttrs // {
365 drvPath = assert condition; drv.drvPath;
366 outPath = assert condition; drv.outPath;
367 };
368
369 /**
370 Strip a derivation of all non-essential attributes, returning
371 only those needed by hydra-eval-jobs. Also strictly evaluate the
372 result to ensure that there are no thunks kept alive to prevent
373 garbage collection.
374
375
376 # Inputs
377
378 `drv`
379
380 : 1\. Function argument
381
382 # Type
383
384 ```
385 hydraJob :: (Derivation | Null) -> (Derivation | Null)
386 ```
387 */
388 hydraJob = drv:
389 let
390 outputs = drv.outputs or ["out"];
391
392 commonAttrs =
393 { inherit (drv) name system meta; inherit outputs; }
394 // optionalAttrs (drv._hydraAggregate or false) {
395 _hydraAggregate = true;
396 constituents = map hydraJob (flatten drv.constituents);
397 }
398 // (listToAttrs outputsList);
399
400 makeOutput = outputName:
401 let output = drv.${outputName}; in
402 { name = outputName;
403 value = commonAttrs // {
404 outPath = output.outPath;
405 drvPath = output.drvPath;
406 type = "derivation";
407 inherit outputName;
408 };
409 };
410
411 outputsList = map makeOutput outputs;
412
413 drv' = (head outputsList).value;
414 in if drv == null then null else
415 deepSeq drv' drv';
416
417 /**
418 Make an attribute set (a "scope") from functions that take arguments from that same attribute set.
419 See [](#ex-makeScope) for how to use it.
420
421 # Inputs
422
423 1. `newScope` (`AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a`)
424
425 A function that takes an attribute set `attrs` and returns what ends up as `callPackage` in the output.
426
427 Typical values are `callPackageWith` or the output attribute `newScope`.
428
429 2. `f` (`AttrSet -> AttrSet`)
430
431 A function that takes an attribute set as returned by `makeScope newScope f` (a "scope") and returns any attribute set.
432
433 This function is used to compute the fixpoint of the resulting scope using `callPackage`.
434 Its argument is the lazily evaluated reference to the value of that fixpoint, and is typically called `self` or `final`.
435
436 See [](#ex-makeScope) for how to use it.
437 See [](#sec-functions-library-fixedPoints) for details on fixpoint computation.
438
439 # Output
440
441 `makeScope` returns an attribute set of a form called `scope`, which also contains the final attributes produced by `f`:
442
443 ```
444 scope :: {
445 callPackage :: ((AttrSet -> a) | Path) -> AttrSet -> a
446 newScope = AttrSet -> scope
447 overrideScope = (scope -> scope -> AttrSet) -> scope
448 packages :: AttrSet -> AttrSet
449 }
450 ```
451
452 - `callPackage` (`((AttrSet -> a) | Path) -> AttrSet -> a`)
453
454 A function that
455
456 1. Takes a function `p`, or a path to a Nix file that contains a function `p`, which takes an attribute set and returns value of arbitrary type `a`,
457 2. Takes an attribute set `args` with explicit attributes to pass to `p`,
458 3. Calls `f` with attributes from the original attribute set `attrs` passed to `newScope` updated with `args, i.e. `attrs // args`, if they match the attributes in the argument of `p`.
459
460 All such functions `p` will be called with the same value for `attrs`.
461
462 See [](#ex-makeScope-callPackage) for how to use it.
463
464 - `newScope` (`AttrSet -> scope`)
465
466 Takes an attribute set `attrs` and returns a scope that extends the original scope.
467
468 - `overrideScope` (`(scope -> scope -> AttrSet) -> scope`)
469
470 Takes a function `g` of the form `final: prev: { # attributes }` to act as an overlay on `f`, and returns a new scope with values determined by `extends g f`.
471 See [](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.fixedPoints.extends) for details.
472
473 This allows subsequent modification of the final attribute set in a consistent way, i.e. all functions `p` invoked with `callPackage` will be called with the modified values.
474
475 - `packages` (`AttrSet -> AttrSet`)
476
477 The value of the argument `f` to `makeScope`.
478
479 - final attributes
480
481 The final values returned by `f`.
482
483 # Examples
484
485 :::{#ex-makeScope .example}
486 # Create an interdependent package set on top of `pkgs`
487
488 The functions in `foo.nix` and `bar.nix` can depend on each other, in the sense that `foo.nix` can contain a function that expects `bar` as an attribute in its argument.
489
490 ```nix
491 let
492 pkgs = import <nixpkgs> { };
493 in
494 pkgs.lib.makeScope pkgs.newScope (self: {
495 foo = self.callPackage ./foo.nix { };
496 bar = self.callPackage ./bar.nix { };
497 })
498 ```
499
500 evaluates to
501
502 ```nix
503 {
504 callPackage = «lambda»;
505 newScope = «lambda»;
506 overrideScope = «lambda»;
507 packages = «lambda»;
508 foo = «derivation»;
509 bar = «derivation»;
510 }
511 ```
512 :::
513
514 :::{#ex-makeScope-callPackage .example}
515 # Using `callPackage` from a scope
516
517 ```nix
518 let
519 pkgs = import <nixpkgs> { };
520 inherit (pkgs) lib;
521 scope = lib.makeScope lib.callPackageWith (self: { a = 1; b = 2; });
522 three = scope.callPackage ({ a, b }: a + b) { };
523 four = scope.callPackage ({ a, b }: a + b) { a = 2; };
524 in
525 [ three four ]
526 ```
527
528 evaluates to
529
530 ```nix
531 [ 3 4 ]
532 ```
533 :::
534
535 # Type
536
537 ```
538 makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> scope
539 ```
540 */
541 makeScope = newScope: f:
542 let self = f self // {
543 newScope = scope: newScope (self // scope);
544 callPackage = self.newScope {};
545 overrideScope = g: makeScope newScope (extends g f);
546 # Remove after 24.11 is released.
547 overrideScope' = g: warnIf (isInOldestRelease 2311)
548 "`overrideScope'` (from `lib.makeScope`) has been renamed to `overrideScope`."
549 (makeScope newScope (extends g f));
550 packages = f;
551 };
552 in self;
553
554 /**
555 backward compatibility with old uncurried form; deprecated
556
557
558 # Inputs
559
560 `splicePackages`
561
562 : 1\. Function argument
563
564 `newScope`
565
566 : 2\. Function argument
567
568 `otherSplices`
569
570 : 3\. Function argument
571
572 `keep`
573
574 : 4\. Function argument
575
576 `extra`
577
578 : 5\. Function argument
579
580 `f`
581
582 : 6\. Function argument
583 */
584 makeScopeWithSplicing =
585 splicePackages: newScope: otherSplices: keep: extra: f:
586 makeScopeWithSplicing'
587 { inherit splicePackages newScope; }
588 { inherit otherSplices keep extra f; };
589
590 /**
591 Like makeScope, but aims to support cross compilation. It's still ugly, but
592 hopefully it helps a little bit.
593
594 # Type
595
596 ```
597 makeScopeWithSplicing' ::
598 { splicePackages :: Splice -> AttrSet
599 , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
600 }
601 -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }
602 -> AttrSet
603
604 Splice ::
605 { pkgsBuildBuild :: AttrSet
606 , pkgsBuildHost :: AttrSet
607 , pkgsBuildTarget :: AttrSet
608 , pkgsHostHost :: AttrSet
609 , pkgsHostTarget :: AttrSet
610 , pkgsTargetTarget :: AttrSet
611 }
612 ```
613 */
614 makeScopeWithSplicing' =
615 { splicePackages
616 , newScope
617 }:
618 { otherSplices
619 # Attrs from `self` which won't be spliced.
620 # Avoid using keep, it's only used for a python hook workaround, added in PR #104201.
621 # ex: `keep = (self: { inherit (self) aAttr; })`
622 , keep ? (_self: {})
623 # Additional attrs to add to the sets `callPackage`.
624 # When the package is from a subset (but not a subset within a package IS #211340)
625 # within `spliced0` it will be spliced.
626 # When using an package outside the set but it's available from `pkgs`, use the package from `pkgs.__splicedPackages`.
627 # If the package is not available within the set or in `pkgs`, such as a package in a let binding, it will not be spliced
628 # ex:
629 # ```
630 # nix-repl> darwin.apple_sdk.frameworks.CoreFoundation
631 # «derivation ...CoreFoundation-11.0.0.drv»
632 # nix-repl> darwin.CoreFoundation
633 # error: attribute 'CoreFoundation' missing
634 # nix-repl> darwin.callPackage ({ CoreFoundation }: CoreFoundation) { }
635 # «derivation ...CoreFoundation-11.0.0.drv»
636 # ```
637 , extra ? (_spliced0: {})
638 , f
639 }:
640 let
641 spliced0 = splicePackages {
642 pkgsBuildBuild = otherSplices.selfBuildBuild;
643 pkgsBuildHost = otherSplices.selfBuildHost;
644 pkgsBuildTarget = otherSplices.selfBuildTarget;
645 pkgsHostHost = otherSplices.selfHostHost;
646 pkgsHostTarget = self; # Not `otherSplices.selfHostTarget`;
647 pkgsTargetTarget = otherSplices.selfTargetTarget;
648 };
649 spliced = extra spliced0 // spliced0 // keep self;
650 self = f self // {
651 newScope = scope: newScope (spliced // scope);
652 callPackage = newScope spliced; # == self.newScope {};
653 # N.B. the other stages of the package set spliced in are *not*
654 # overridden.
655 overrideScope = g: (makeScopeWithSplicing'
656 { inherit splicePackages newScope; }
657 { inherit otherSplices keep extra;
658 f = extends g f;
659 });
660 packages = f;
661 };
662 in self;
663
664}