doc: migrate lib.customisation to use doc-comments

This commit is contained in:
Johannes Kirschbauer 2024-03-22 10:02:09 +01:00
parent 284dd64382
commit 3dfd61965e
No known key found for this signature in database

View file

@ -15,7 +15,8 @@ in
rec { rec {
/* `overrideDerivation drv f` takes a derivation (i.e., the result /**
`overrideDerivation drv f` takes a derivation (i.e., the result
of a call to the builtin function `derivation`) and returns a new of a call to the builtin function `derivation`) and returns a new
derivation in which the attributes of the original are overridden derivation in which the attributes of the original are overridden
according to the function `f`. The function `f` is called with according to the function `f`. The function `f` is called with
@ -39,7 +40,28 @@ rec {
You should in general prefer `drv.overrideAttrs` over this function; You should in general prefer `drv.overrideAttrs` over this function;
see the nixpkgs manual for more information on overriding. see the nixpkgs manual for more information on overriding.
Example:
# Inputs
`drv`
: 1\. Function argument
`f`
: 2\. Function argument
# Type
```
overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
```
# Examples
:::{.example}
## `lib.customisation.overrideDerivation` usage example
```nix
mySed = overrideDerivation pkgs.gnused (oldAttrs: { mySed = overrideDerivation pkgs.gnused (oldAttrs: {
name = "sed-4.2.2-pre"; name = "sed-4.2.2-pre";
src = fetchurl { src = fetchurl {
@ -48,9 +70,9 @@ rec {
}; };
patches = []; patches = [];
}); });
```
Type: :::
overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
*/ */
overrideDerivation = drv: f: overrideDerivation = drv: f:
let let
@ -67,14 +89,32 @@ rec {
}); });
/* `makeOverridable` takes a function from attribute set to attribute set and /**
`makeOverridable` takes a function from attribute set to attribute set and
injects `override` attribute which can be used to override arguments of injects `override` attribute which can be used to override arguments of
the function. the function.
Please refer to documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats Please refer to documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats
related to its use. related to its use.
Example:
# Inputs
`f`
: 1\. Function argument
# Type
```
makeOverridable :: (AttrSet -> a) -> AttrSet -> a
```
# Examples
:::{.example}
## `lib.customisation.makeOverridable` usage example
```nix
nix-repl> x = {a, b}: { result = a + b; } nix-repl> x = {a, b}: { result = a + b; }
nix-repl> y = lib.makeOverridable x { a = 1; b = 2; } nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }
@ -84,9 +124,9 @@ rec {
nix-repl> y.override { a = 10; } nix-repl> y.override { a = 10; }
{ override = «lambda»; overrideDerivation = «lambda»; result = 12; } { override = «lambda»; overrideDerivation = «lambda»; result = 12; }
```
Type: :::
makeOverridable :: (AttrSet -> a) -> AttrSet -> a
*/ */
makeOverridable = f: makeOverridable = f:
let let
@ -120,7 +160,8 @@ rec {
else result); else result);
/* Call the package function in the file `fn` with the required /**
Call the package function in the file `fn` with the required
arguments automatically. The function is called with the arguments automatically. The function is called with the
arguments `args`, but any missing arguments are obtained from arguments `args`, but any missing arguments are obtained from
`autoArgs`. This function is intended to be partially `autoArgs`. This function is intended to be partially
@ -147,8 +188,26 @@ rec {
<!-- TODO: Apply "Example:" tag to the examples above --> <!-- TODO: Apply "Example:" tag to the examples above -->
Type:
# Inputs
`autoArgs`
: 1\. Function argument
`fn`
: 2\. Function argument
`args`
: 3\. Function argument
# Type
```
callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
```
*/ */
callPackageWith = autoArgs: fn: args: callPackageWith = autoArgs: fn: args:
let let
@ -210,12 +269,31 @@ rec {
else abort "lib.customisation.callPackageWith: ${error}"; else abort "lib.customisation.callPackageWith: ${error}";
/* Like callPackage, but for a function that returns an attribute /**
Like callPackage, but for a function that returns an attribute
set of derivations. The override function is added to the set of derivations. The override function is added to the
individual attributes. individual attributes.
Type:
# Inputs
`autoArgs`
: 1\. Function argument
`fn`
: 2\. Function argument
`args`
: 3\. Function argument
# Type
```
callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet
```
*/ */
callPackagesWith = autoArgs: fn: args: callPackagesWith = autoArgs: fn: args:
let let
@ -233,11 +311,30 @@ rec {
else mapAttrs mkAttrOverridable pkgs; else mapAttrs mkAttrOverridable pkgs;
/* Add attributes to each output of a derivation without changing /**
Add attributes to each output of a derivation without changing
the derivation itself and check a given condition when evaluating. the derivation itself and check a given condition when evaluating.
Type:
# Inputs
`condition`
: 1\. Function argument
`passthru`
: 2\. Function argument
`drv`
: 3\. Function argument
# Type
```
extendDerivation :: Bool -> Any -> Derivation -> Derivation extendDerivation :: Bool -> Any -> Derivation -> Derivation
```
*/ */
extendDerivation = condition: passthru: drv: extendDerivation = condition: passthru: drv:
let let
@ -269,13 +366,24 @@ rec {
outPath = assert condition; drv.outPath; outPath = assert condition; drv.outPath;
}; };
/* Strip a derivation of all non-essential attributes, returning /**
Strip a derivation of all non-essential attributes, returning
only those needed by hydra-eval-jobs. Also strictly evaluate the only those needed by hydra-eval-jobs. Also strictly evaluate the
result to ensure that there are no thunks kept alive to prevent result to ensure that there are no thunks kept alive to prevent
garbage collection. garbage collection.
Type:
# Inputs
`drv`
: 1\. Function argument
# Type
```
hydraJob :: (Derivation | Null) -> (Derivation | Null) hydraJob :: (Derivation | Null) -> (Derivation | Null)
```
*/ */
hydraJob = drv: hydraJob = drv:
let let
@ -443,17 +551,49 @@ rec {
}; };
in self; in self;
/* backward compatibility with old uncurried form; deprecated */ /**
backward compatibility with old uncurried form; deprecated
# Inputs
`splicePackages`
: 1\. Function argument
`newScope`
: 2\. Function argument
`otherSplices`
: 3\. Function argument
`keep`
: 4\. Function argument
`extra`
: 5\. Function argument
`f`
: 6\. Function argument
*/
makeScopeWithSplicing = makeScopeWithSplicing =
splicePackages: newScope: otherSplices: keep: extra: f: splicePackages: newScope: otherSplices: keep: extra: f:
makeScopeWithSplicing' makeScopeWithSplicing'
{ inherit splicePackages newScope; } { inherit splicePackages newScope; }
{ inherit otherSplices keep extra f; }; { inherit otherSplices keep extra f; };
/* Like makeScope, but aims to support cross compilation. It's still ugly, but /**
Like makeScope, but aims to support cross compilation. It's still ugly, but
hopefully it helps a little bit. hopefully it helps a little bit.
Type: # Type
```
makeScopeWithSplicing' :: makeScopeWithSplicing' ::
{ splicePackages :: Splice -> AttrSet { splicePackages :: Splice -> AttrSet
, newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
@ -469,6 +609,7 @@ rec {
, pkgsHostTarget :: AttrSet , pkgsHostTarget :: AttrSet
, pkgsTargetTarget :: AttrSet , pkgsTargetTarget :: AttrSet
} }
```
*/ */
makeScopeWithSplicing' = makeScopeWithSplicing' =
{ splicePackages { splicePackages