cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

doc: migrate lib.customisation to use doc-comments

Browse source
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
1 changed files with 221 additions and 80 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

179
lib/customisation.nix
View file

@ -15,7 +15,8 @@ in
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
derivation in which the attributes of the original are overridden
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;
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: {
name = "sed-4.2.2-pre";
src = fetchurl {
@ -48,9 +70,9 @@ rec {
};
patches = [];
});
```
Type:
overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
:::
*/
overrideDerivation = drv: f:
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
the function.
Please refer to documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats
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> y = lib.makeOverridable x { a = 1; b = 2; }
@ -84,9 +124,9 @@ rec {
nix-repl> y.override { a = 10; }
{ override = «lambda»; overrideDerivation = «lambda»; result = 12; }
```
Type:
makeOverridable :: (AttrSet -> a) -> AttrSet -> a
:::
*/
makeOverridable = f:
let
@ -120,7 +160,8 @@ rec {
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 `args`, but any missing arguments are obtained from
`autoArgs`. This function is intended to be partially
@ -147,8 +188,26 @@ rec {
<!-- 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 = autoArgs: fn: args:
let
@ -210,12 +269,31 @@ rec {
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
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 = autoArgs: fn: args:
let
@ -233,11 +311,30 @@ rec {
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.
Type:
# Inputs
`condition`
: 1\. Function argument
`passthru`
: 2\. Function argument
`drv`
: 3\. Function argument
# Type
```
extendDerivation :: Bool -> Any -> Derivation -> Derivation
```
*/
extendDerivation = condition: passthru: drv:
let
@ -269,13 +366,24 @@ rec {
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
result to ensure that there are no thunks kept alive to prevent
garbage collection.
Type:
# Inputs
`drv`
: 1\. Function argument
# Type
```
hydraJob :: (Derivation | Null) -> (Derivation | Null)
```
*/
hydraJob = drv:
let
@ -443,17 +551,49 @@ rec {
};
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 =
splicePackages: newScope: otherSplices: keep: extra: f:
makeScopeWithSplicing'
{ inherit splicePackages newScope; }
{ 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.
Type:
# Type
```
makeScopeWithSplicing' ::
{ splicePackages :: Splice -> AttrSet
, newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
@ -469,6 +609,7 @@ rec {
, pkgsHostTarget :: AttrSet
, pkgsTargetTarget :: AttrSet
}
```
*/
makeScopeWithSplicing' =
{ splicePackages