lib/meta.nix

   1 /* Some functions for manipulating meta attributes, as well as the
   2    name attribute. */
   3
   4 { lib }:
   5
   6 let
   7   inherit (lib) matchAttrs any all;
   8   inherit (builtins) isString;
   9
  10 in
  11 rec {
  12
  13
  14   /* Add to or override the meta attributes of the given
  15      derivation.
  16
  17      Example:
  18        addMetaAttrs {description = "Bla blah";} somePkg
  19   */
  20   addMetaAttrs = newAttrs: drv:
  21     drv // { meta = (drv.meta or {}) // newAttrs; };
  22
  23
  24   /* Disable Hydra builds of given derivation.
  25   */
  26   dontDistribute = drv: addMetaAttrs { hydraPlatforms = []; } drv;
  27
  28
  29   /* Change the symbolic name of a package for presentation purposes
  30      (i.e., so that nix-env users can tell them apart).
  31   */
  32   setName = name: drv: drv // {inherit name;};
  33
  34
  35   /* Like `setName`, but takes the previous name as an argument.
  36
  37      Example:
  38        updateName (oldName: oldName + "-experimental") somePkg
  39   */
  40   updateName = updater: drv: drv // {name = updater (drv.name);};
  41
  42
  43   /* Append a suffix to the name of a package (before the version
  44      part). */
  45   appendToName = suffix: updateName (name:
  46     let x = builtins.parseDrvName name; in "${x.name}-${suffix}-${x.version}");
  47
  48
  49   /* Apply a function to each derivation and only to derivations in an attrset.
  50   */
  51   mapDerivationAttrset = f: set: lib.mapAttrs (name: pkg: if lib.isDerivation pkg then (f pkg) else pkg) set;
  52
  53   /* Set the nix-env priority of the package.
  54   */
  55   setPrio = priority: addMetaAttrs { inherit priority; };
  56
  57   /* Decrease the nix-env priority of the package, i.e., other
  58      versions/variants of the package will be preferred.
  59   */
  60   lowPrio = setPrio 10;
  61
  62   /* Apply lowPrio to an attrset with derivations
  63   */
  64   lowPrioSet = set: mapDerivationAttrset lowPrio set;
  65
  66
  67   /* Increase the nix-env priority of the package, i.e., this
  68      version/variant of the package will be preferred.
  69   */
  70   hiPrio = setPrio (-10);
  71
  72   /* Apply hiPrio to an attrset with derivations
  73   */
  74   hiPrioSet = set: mapDerivationAttrset hiPrio set;
  75
  76
  77   /* Check to see if a platform is matched by the given `meta.platforms`
  78      element.
  79
  80      A `meta.platform` pattern is either
  81
  82        1. (legacy) a system string.
  83
  84        2. (modern) a pattern for the entire platform structure (see `lib.systems.inspect.platformPatterns`).
  85
  86        3. (modern) a pattern for the platform `parsed` field (see `lib.systems.inspect.patterns`).
  87
  88      We can inject these into a pattern for the whole of a structured platform,
  89      and then match that.
  90   */
  91   platformMatch = platform: elem: (
  92     # Check with simple string comparison if elem was a string.
  93     #
  94     # The majority of comparisons done with this function will be against meta.platforms
  95     # which contains a simple platform string.
  96     #
  97     # Avoiding an attrset allocation results in significant  performance gains (~2-30) across the board in OfBorg
  98     # because this is a hot path for nixpkgs.
  99     if isString elem then platform ? system && elem == platform.system
 100     else matchAttrs (
 101       # Normalize platform attrset.
 102       if elem ? parsed then elem
 103       else { parsed = elem; }
 104     ) platform
 105   );
 106
 107   /* Check if a package is available on a given platform.
 108
 109      A package is available on a platform if both
 110
 111        1. One of `meta.platforms` pattern matches the given
 112           platform, or `meta.platforms` is not present.
 113
 114        2. None of `meta.badPlatforms` pattern matches the given platform.
 115   */
 116   availableOn = platform: pkg:
 117     ((!pkg?meta.platforms) || any (platformMatch platform) pkg.meta.platforms) &&
 118     all (elem: !platformMatch platform elem) (pkg.meta.badPlatforms or []);
 119
 120   /* Get the corresponding attribute in lib.licenses
 121      from the SPDX ID.
 122      For SPDX IDs, see
 123      https://spdx.org/licenses
 124
 125      Type:
 126        getLicenseFromSpdxId :: str -> AttrSet
 127
 128      Example:
 129        lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit
 130        => true
 131        lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit
 132        => true
 133        lib.getLicenseFromSpdxId "MY LICENSE"
 134        => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE
 135        => { shortName = "MY LICENSE"; }
 136   */
 137   getLicenseFromSpdxId =
 138     let
 139       spdxLicenses = lib.mapAttrs (id: ls: assert lib.length ls == 1; builtins.head ls)
 140         (lib.groupBy (l: lib.toLower l.spdxId) (lib.filter (l: l ? spdxId) (lib.attrValues lib.licenses)));
 141     in licstr:
 142       spdxLicenses.${ lib.toLower licstr } or (
 143         lib.warn "getLicenseFromSpdxId: No license matches the given SPDX ID: ${licstr}"
 144         { shortName = licstr; }
 145       );
 146
 147   /* Get the path to the main program of a package based on meta.mainProgram
 148
 149      Type: getExe :: package -> string
 150
 151      Example:
 152        getExe pkgs.hello
 153        => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
 154        getExe pkgs.mustache-go
 155        => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache"
 156   */
 157   getExe = x:
 158     let
 159       y = x.meta.mainProgram or (
 160         # This could be turned into an error when 23.05 is at end of life
 161         lib.warn "getExe: Package ${lib.strings.escapeNixIdentifier x.meta.name or x.pname or x.name} does not have the meta.mainProgram attribute. We'll assume that the main program has the same name for now, but this behavior is deprecated, because it leads to surprising errors when the assumption does not hold. If the package has a main program, please set `meta.mainProgram` in its definition to make this warning go away. Otherwise, if the package does not have a main program, or if you don't control its definition, use getExe' to specify the name to the program, such as lib.getExe' foo \"bar\"."
 162           lib.getName
 163           x
 164       );
 165     in
 166     getExe' x y;
 167
 168   /* Get the path of a program of a derivation.
 169
 170      Type: getExe' :: derivation -> string -> string
 171      Example:
 172        getExe' pkgs.hello "hello"
 173        => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
 174        getExe' pkgs.imagemagick "convert"
 175        => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert"
 176   */
 177   getExe' = x: y:
 178     assert lib.assertMsg (lib.isDerivation x)
 179       "lib.meta.getExe': The first argument is of type ${builtins.typeOf x}, but it should be a derivation instead.";
 180     assert lib.assertMsg (lib.isString y)
 181      "lib.meta.getExe': The second argument is of type ${builtins.typeOf y}, but it should be a string instead.";
 182     assert lib.assertMsg (builtins.length (lib.splitString "/" y) == 1)
 183      "lib.meta.getExe': The second argument \"${y}\" is a nested path with a \"/\" character, but it should just be the name of the executable instead.";
 184     "${lib.getBin x}/bin/${y}";
 185 }