From b4cffe178c94f0e2b6d293a2d3333f701144c27e Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 26 Jun 2024 22:12:18 +0200 Subject: lib.meta: refactor to use doc-comments (#313589) * doc: use doc-comments for lib.meta * adds missing argument to setPrio --- lib/meta.nix | 359 +++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 285 insertions(+), 74 deletions(-) (limited to 'lib') diff --git a/lib/meta.nix b/lib/meta.nix index 9a97afb1aa9b..8fa93d40d595 100644 --- a/lib/meta.nix +++ b/lib/meta.nix @@ -1,5 +1,7 @@ -/* Some functions for manipulating meta attributes, as well as the - name attribute. */ +/** + Some functions for manipulating meta attributes, as well as the + name attribute. +*/ { lib }: @@ -11,90 +13,225 @@ in rec { - /* Add to or override the meta attributes of the given - derivation. + /** + Add to or override the meta attributes of the given + derivation. - Example: - addMetaAttrs {description = "Bla blah";} somePkg + # Inputs + + `newAttrs` + + : 1\. Function argument + + `drv` + + : 2\. Function argument + + + # Examples + :::{.example} + ## `lib.meta.addMetaAttrs` usage example + + ```nix + addMetaAttrs {description = "Bla blah";} somePkg + ``` + + ::: */ addMetaAttrs = newAttrs: drv: drv // { meta = (drv.meta or {}) // newAttrs; }; - /* Disable Hydra builds of given derivation. + /** + Disable Hydra builds of given derivation. + + # Inputs + + `drv` + + : 1\. Function argument */ dontDistribute = drv: addMetaAttrs { hydraPlatforms = []; } drv; - /* - Change the [symbolic name of a derivation](https://nixos.org/manual/nix/stable/language/derivations.html#attr-name). + /** + Change the [symbolic name of a derivation](https://nixos.org/manual/nix/stable/language/derivations.html#attr-name). + + :::{.warning} + Dependent derivations will be rebuilt when the symbolic name is changed. + ::: - :::{.warning} - Dependent derivations will be rebuilt when the symbolic name is changed. - ::: + # Inputs + + `name` + + : 1\. Function argument + + `drv` + + : 2\. Function argument */ setName = name: drv: drv // {inherit name;}; - /* Like `setName`, but takes the previous name as an argument. + /** + Like `setName`, but takes the previous name as an argument. + + # Inputs + + `updater` + + : 1\. Function argument + + `drv` + + : 2\. Function argument + + + # Examples + :::{.example} + ## `lib.meta.updateName` usage example - Example: - updateName (oldName: oldName + "-experimental") somePkg + ```nix + updateName (oldName: oldName + "-experimental") somePkg + ``` + + ::: */ updateName = updater: drv: drv // {name = updater (drv.name);}; - /* Append a suffix to the name of a package (before the version - part). */ + /** + Append a suffix to the name of a package (before the version + part). + + # Inputs + + `suffix` + + : 1\. Function argument + */ appendToName = suffix: updateName (name: let x = builtins.parseDrvName name; in "${x.name}-${suffix}-${x.version}"); - /* Apply a function to each derivation and only to derivations in an attrset. + /** + Apply a function to each derivation and only to derivations in an attrset. + + + # Inputs + + `f` + + : 1\. Function argument + + `set` + + : 2\. Function argument */ mapDerivationAttrset = f: set: lib.mapAttrs (name: pkg: if lib.isDerivation pkg then (f pkg) else pkg) set; - /* Set the nix-env priority of the package. + /** + Set the nix-env priority of the package. + + # Inputs + + `priority` + : 1\. Function argument + + `drv` + : 2\. Function argument */ setPrio = priority: addMetaAttrs { inherit priority; }; - /* Decrease the nix-env priority of the package, i.e., other - versions/variants of the package will be preferred. + /** + Decrease the nix-env priority of the package, i.e., other + versions/variants of the package will be preferred. + + # Inputs + + `drv` + + : 1\. Function argument + */ lowPrio = setPrio 10; - /* Apply lowPrio to an attrset with derivations + /** + Apply lowPrio to an attrset with derivations + + + # Inputs + + `set` + + : 1\. Function argument */ lowPrioSet = set: mapDerivationAttrset lowPrio set; - /* Increase the nix-env priority of the package, i.e., this - version/variant of the package will be preferred. + /** + Increase the nix-env priority of the package, i.e., this + version/variant of the package will be preferred. + + # Inputs + + `drv` + + : 1\. Function argument */ hiPrio = setPrio (-10); - /* Apply hiPrio to an attrset with derivations + /** + Apply hiPrio to an attrset with derivations + + + # Inputs + + `set` + + : 1\. Function argument */ hiPrioSet = set: mapDerivationAttrset hiPrio set; - /* Check to see if a platform is matched by the given `meta.platforms` - element. + /** + Check to see if a platform is matched by the given `meta.platforms` + element. + + A `meta.platform` pattern is either + + 1. (legacy) a system string. + + 2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`). + + 3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`). - A `meta.platform` pattern is either + We can inject these into a pattern for the whole of a structured platform, + and then match that. - 1. (legacy) a system string. - 2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`). + # Inputs - 3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`). + `platform` - We can inject these into a pattern for the whole of a structured platform, - and then match that. + : 1\. Function argument - Example: - lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin" - => true + `elem` + + : 2\. Function argument + + + # Examples + :::{.example} + ## `lib.meta.platformMatch` usage example + + ```nix + lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin" + => true + ``` + + ::: */ platformMatch = platform: elem: ( # Check with simple string comparison if elem was a string. @@ -112,39 +249,70 @@ rec { ) platform ); - /* Check if a package is available on a given platform. + /** + Check if a package is available on a given platform. + + A package is available on a platform if both + + 1. One of `meta.platforms` pattern matches the given + platform, or `meta.platforms` is not present. + + 2. None of `meta.badPlatforms` pattern matches the given platform. + + + # Inputs + + `platform` - A package is available on a platform if both + : 1\. Function argument - 1. One of `meta.platforms` pattern matches the given - platform, or `meta.platforms` is not present. + `pkg` - 2. None of `meta.badPlatforms` pattern matches the given platform. + : 2\. Function argument - Example: - lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh - => true + + # Examples + :::{.example} + ## `lib.meta.availableOn` usage example + + ```nix + lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh + => true + ``` + + ::: */ availableOn = platform: pkg: ((!pkg?meta.platforms) || any (platformMatch platform) pkg.meta.platforms) && all (elem: !platformMatch platform elem) (pkg.meta.badPlatforms or []); - /* Get the corresponding attribute in lib.licenses - from the SPDX ID. - For SPDX IDs, see - https://spdx.org/licenses - - Type: - getLicenseFromSpdxId :: str -> AttrSet - - Example: - lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit - => true - lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit - => true - lib.getLicenseFromSpdxId "MY LICENSE" - => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE - => { shortName = "MY LICENSE"; } + /** + Get the corresponding attribute in lib.licenses + from the SPDX ID. + For SPDX IDs, see + https://spdx.org/licenses + + # Type + + ``` + getLicenseFromSpdxId :: str -> AttrSet + ``` + + # Examples + :::{.example} + ## `lib.meta.getLicenseFromSpdxId` usage example + + ```nix + lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit + => true + lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit + => true + lib.getLicenseFromSpdxId "MY LICENSE" + => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE + => { shortName = "MY LICENSE"; } + ``` + + ::: */ getLicenseFromSpdxId = let @@ -156,15 +324,34 @@ rec { { shortName = licstr; } ); - /* Get the path to the main program of a package based on meta.mainProgram + /** + Get the path to the main program of a package based on meta.mainProgram + + + # Inputs + + `x` + + : 1\. Function argument + + # Type + + ``` + getExe :: package -> string + ``` - Type: getExe :: package -> string + # Examples + :::{.example} + ## `lib.meta.getExe` usage example - Example: - getExe pkgs.hello - => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello" - getExe pkgs.mustache-go - => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache" + ```nix + getExe pkgs.hello + => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello" + getExe pkgs.mustache-go + => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache" + ``` + + ::: */ getExe = x: getExe' x (x.meta.mainProgram or ( # This could be turned into an error when 23.05 is at end of life @@ -173,14 +360,38 @@ rec { x )); - /* Get the path of a program of a derivation. + /** + Get the path of a program of a derivation. + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument + + # Type + + ``` + getExe' :: derivation -> string -> string + ``` + + # Examples + :::{.example} + ## `lib.meta.getExe'` usage example + + ```nix + getExe' pkgs.hello "hello" + => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello" + getExe' pkgs.imagemagick "convert" + => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert" + ``` - Type: getExe' :: derivation -> string -> string - Example: - getExe' pkgs.hello "hello" - => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello" - getExe' pkgs.imagemagick "convert" - => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert" + ::: */ getExe' = x: y: assert assertMsg (isDerivation x) -- cgit v1.2.3