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 isDerivation getBin assertMsg;
   8   inherit (builtins) isString match typeOf;
   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      Example:
  92       lib.meta.platformMatch { system = "aarch64-darwin"; } "aarch64-darwin"
  93       => true
  94   */
  95   platformMatch = platform: elem: (
  96     # Check with simple string comparison if elem was a string.
  97     #
  98     # The majority of comparisons done with this function will be against meta.platforms
  99     # which contains a simple platform string.
 100     #
 101     # Avoiding an attrset allocation results in significant  performance gains (~2-30) across the board in OfBorg
 102     # because this is a hot path for nixpkgs.
 103     if isString elem then platform ? system && elem == platform.system
 104     else matchAttrs (
 105       # Normalize platform attrset.
 106       if elem ? parsed then elem
 107       else { parsed = elem; }
 108     ) platform
 109   );
 110
 111   /* Check if a package is available on a given platform.
 112
 113      A package is available on a platform if both
 114
 115        1. One of `meta.platforms` pattern matches the given
 116           platform, or `meta.platforms` is not present.
 117
 118        2. None of `meta.badPlatforms` pattern matches the given platform.
 119
 120      Example:
 121        lib.meta.availableOn { system = "aarch64-darwin"; } pkg.zsh
 122        => true
 123   */
 124   availableOn = platform: pkg:
 125     ((!pkg?meta.platforms) || any (platformMatch platform) pkg.meta.platforms) &&
 126     all (elem: !platformMatch platform elem) (pkg.meta.badPlatforms or []);
 127
 128   /* Get the corresponding attribute in lib.licenses
 129      from the SPDX ID.
 130      For SPDX IDs, see
 131      https://spdx.org/licenses
 132
 133      Type:
 134        getLicenseFromSpdxId :: str -> AttrSet
 135
 136      Example:
 137        lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit
 138        => true
 139        lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit
 140        => true
 141        lib.getLicenseFromSpdxId "MY LICENSE"
 142        => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE
 143        => { shortName = "MY LICENSE"; }
 144   */
 145   getLicenseFromSpdxId =
 146     let
 147       spdxLicenses = lib.mapAttrs (id: ls: assert lib.length ls == 1; builtins.head ls)
 148         (lib.groupBy (l: lib.toLower l.spdxId) (lib.filter (l: l ? spdxId) (lib.attrValues lib.licenses)));
 149     in licstr:
 150       spdxLicenses.${ lib.toLower licstr } or (
 151         lib.warn "getLicenseFromSpdxId: No license matches the given SPDX ID: ${licstr}"
 152         { shortName = licstr; }
 153       );
 154
 155   /* Get the path to the main program of a package based on meta.mainProgram
 156
 157      Type: getExe :: package -> string
 158
 159      Example:
 160        getExe pkgs.hello
 161        => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
 162        getExe pkgs.mustache-go
 163        => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache"
 164   */
 165   getExe = x: getExe' x (x.meta.mainProgram or (
 166     # This could be turned into an error when 23.05 is at end of life
 167     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\"."
 168     lib.getName
 169     x
 170   ));
 171
 172   /* Get the path of a program of a derivation.
 173
 174      Type: getExe' :: derivation -> string -> string
 175      Example:
 176        getExe' pkgs.hello "hello"
 177        => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello"
 178        getExe' pkgs.imagemagick "convert"
 179        => "/nix/store/5rs48jamq7k6sal98ymj9l4k2bnwq515-imagemagick-7.1.1-15/bin/convert"
 180   */
 181   getExe' = x: y:
 182     assert assertMsg (isDerivation x)
 183       "lib.meta.getExe': The first argument is of type ${typeOf x}, but it should be a derivation instead.";
 184     assert assertMsg (isString y)
 185       "lib.meta.getExe': The second argument is of type ${typeOf y}, but it should be a string instead.";
 186     assert assertMsg (match ".*\/.*" y == null)
 187       "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.";
 188     "${getBin x}/bin/${y}";
 189 }