From a8d5d2f2075597f403c9d1af62ff7994fee49fc1 Mon Sep 17 00:00:00 2001 From: Yueh-Shun Li Date: Fri, 20 Oct 2023 19:43:24 +0800 Subject: [PATCH 1/3] doc: generate documentation for lib.customisation --- doc/default.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/default.nix b/doc/default.nix index 18e12c1a8aca..61bbd2ba8dc8 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -23,6 +23,7 @@ let { name = "sources"; description = "source filtering functions"; } { name = "cli"; description = "command-line serialization functions"; } { name = "gvariant"; description = "GVariant formatted string serialization functions"; } + { name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; } ]; }; From 93b8f14a2d36a17ebbd40f3f3907e43a01d44502 Mon Sep 17 00:00:00 2001 From: Yueh-Shun Li Date: Fri, 20 Oct 2023 20:57:10 +0800 Subject: [PATCH 2/3] doc: lib.customization: add Type and Example tags Add the "Type:" blocks. Move the examples below the descriptions whenever possibles Add "Example:" tags before the examples moved below the descriptions. --- lib/customisation.nix | 89 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 19 deletions(-) diff --git a/lib/customisation.nix b/lib/customisation.nix index 5ef4f29e6f6a..ed76699a23ee 100644 --- a/lib/customisation.nix +++ b/lib/customisation.nix @@ -13,16 +13,7 @@ rec { scenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance, if you want to "patch" the derivation returned by a package function in Nixpkgs to build another version than what the - function itself provides, you can do something like this: - - mySed = overrideDerivation pkgs.gnused (oldAttrs: { - name = "sed-4.2.2-pre"; - src = fetchurl { - url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; - hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY="; - }; - patches = []; - }); + function itself provides. For another application, see build-support/vm, where this function is used to build arbitrary derivations inside a QEMU @@ -35,6 +26,19 @@ rec { You should in general prefer `drv.overrideAttrs` over this function; see the nixpkgs manual for more information on overriding. + + Example: + mySed = overrideDerivation pkgs.gnused (oldAttrs: { + name = "sed-4.2.2-pre"; + src = fetchurl { + url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; + hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY="; + }; + patches = []; + }); + + Type: + overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation */ overrideDerivation = drv: f: let @@ -55,6 +59,11 @@ rec { injects `override` attribute which can be used to override arguments of the function. + Please refer to "Nixpkgs Contributors Guide" section + ".overrideDerivation" to learn about `overrideDerivation` and caveats + related to its use. + + Example: nix-repl> x = {a, b}: { result = a + b; } nix-repl> y = lib.makeOverridable x { a = 1; b = 2; } @@ -65,9 +74,8 @@ rec { nix-repl> y.override { a = 10; } { override = «lambda»; overrideDerivation = «lambda»; result = 12; } - Please refer to "Nixpkgs Contributors Guide" section - ".overrideDerivation" to learn about `overrideDerivation` and caveats - related to its use. + Type: + makeOverridable :: (AttrSet -> a) -> AttrSet -> a */ makeOverridable = f: lib.setFunctionArgs (origArgs: let @@ -105,20 +113,29 @@ rec { `autoArgs`. This function is intended to be partially parameterised, e.g., + ```nix callPackage = callPackageWith pkgs; pkgs = { libfoo = callPackage ./foo.nix { }; libbar = callPackage ./bar.nix { }; }; + ``` If the `libbar` function expects an argument named `libfoo`, it is automatically passed as an argument. Overrides or missing arguments can be supplied in `args`, e.g. + ```nix libbar = callPackage ./bar.nix { libfoo = null; enableX11 = true; }; + ``` + + + + Type: + callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a */ callPackageWith = autoArgs: fn: args: let @@ -129,7 +146,7 @@ rec { # This includes automatic ones and ones passed explicitly allArgs = builtins.intersectAttrs fargs autoArgs // args; - # A list of argument names that the function requires, but + # a list of argument names that the function requires, but # wouldn't be passed to it missingArgs = lib.attrNames # Filter out arguments that have a default value @@ -176,7 +193,11 @@ rec { /* Like callPackage, but for a function that returns an attribute set of derivations. The override function is added to the - individual attributes. */ + individual attributes. + + Type: + callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet + */ callPackagesWith = autoArgs: fn: args: let f = if lib.isFunction fn then fn else import fn; @@ -193,7 +214,11 @@ rec { /* 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: + extendDerivation :: Bool -> Any -> Derivation -> Derivation + */ extendDerivation = condition: passthru: drv: let outputs = drv.outputs or [ "out" ]; @@ -227,7 +252,11 @@ rec { /* 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. */ + garbage collection. + + Type: + hydraJob :: (Derivation | Null) -> (Derivation | Null) + */ hydraJob = drv: let outputs = drv.outputs or ["out"]; @@ -265,7 +294,11 @@ rec { called with the overridden packages. The package sets may be hierarchical: the packages in the set are called with the scope provided by `newScope` and the set provides a `newScope` attribute - which can form the parent scope for later package sets. */ + which can form the parent scope for later package sets. + + Type: + makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> AttrSet + */ makeScope = newScope: f: let self = f self // { newScope = scope: newScope (self // scope); @@ -287,7 +320,25 @@ rec { { inherit otherSplices keep extra f; }; /* 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: + makeScopeWithSplicing' :: + { splicePackages :: Splice -> AttrSet + , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a + } + -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet } + -> AttrSet + + Splice :: + { pkgsBuildBuild :: AttrSet + , pkgsBuildHost :: AttrSet + , pkgsBuildTarget :: AttrSet + , pkgsHostHost :: AttrSet + , pkgsHostTarget :: AttrSet + , pkgsTargetTarget :: AttrSet + } + */ makeScopeWithSplicing' = { splicePackages , newScope From 0695d3e8fe08dac78fc59354ae2f926915b0d6b6 Mon Sep 17 00:00:00 2001 From: Yueh-Shun Li Date: Sat, 21 Oct 2023 03:11:21 +0800 Subject: [PATCH 3/3] lib.overrideDerivation: inter-link the documentation Co-authored-by: Valentin Gagarin --- lib/customisation.nix | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/customisation.nix b/lib/customisation.nix index ed76699a23ee..61bb531d2f62 100644 --- a/lib/customisation.nix +++ b/lib/customisation.nix @@ -59,8 +59,7 @@ rec { injects `override` attribute which can be used to override arguments of the function. - Please refer to "Nixpkgs Contributors Guide" section - ".overrideDerivation" to learn about `overrideDerivation` and caveats + Please refer to documentation on [`.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats related to its use. Example: