lib/derivations.nix

   1 { lib }:
   2
   3 let
   4   inherit (lib)
   5     genAttrs
   6     isString
   7     throwIfNot
   8     ;
   9
  10   showMaybeAttrPosPre = prefix: attrName: v:
  11     let pos = builtins.unsafeGetAttrPos attrName v;
  12     in if pos == null then "" else "${prefix}${pos.file}:${toString pos.line}:${toString pos.column}";
  13
  14   showMaybePackagePosPre = prefix: pkg:
  15     if pkg?meta.position && isString pkg.meta.position
  16     then "${prefix}${pkg.meta.position}"
  17     else "";
  18 in
  19 {
  20   /*
  21     Restrict a derivation to a predictable set of attribute names, so
  22     that the returned attrset is not strict in the actual derivation,
  23     saving a lot of computation when the derivation is non-trivial.
  24
  25     This is useful in situations where a derivation might only be used for its
  26     passthru attributes, improving evaluation performance.
  27
  28     The returned attribute set is lazy in `derivation`. Specifically, this
  29     means that the derivation will not be evaluated in at least the
  30     situations below.
  31
  32     For illustration and/or testing, we define derivation such that its
  33     evaluation is very noticeable.
  34
  35         let derivation = throw "This won't be evaluated.";
  36
  37     In the following expressions, `derivation` will _not_ be evaluated:
  38
  39         (lazyDerivation { inherit derivation; }).type
  40
  41         attrNames (lazyDerivation { inherit derivation; })
  42
  43         (lazyDerivation { inherit derivation; } // { foo = true; }).foo
  44
  45         (lazyDerivation { inherit derivation; meta.foo = true; }).meta
  46
  47     In these expressions, `derivation` _will_ be evaluated:
  48
  49         "${lazyDerivation { inherit derivation }}"
  50
  51         (lazyDerivation { inherit derivation }).outPath
  52
  53         (lazyDerivation { inherit derivation }).meta
  54
  55     And the following expressions are not valid, because the refer to
  56     implementation details and/or attributes that may not be present on
  57     some derivations:
  58
  59         (lazyDerivation { inherit derivation }).buildInputs
  60
  61         (lazyDerivation { inherit derivation }).passthru
  62
  63         (lazyDerivation { inherit derivation }).pythonPath
  64
  65   */
  66   lazyDerivation =
  67     args@{
  68       # The derivation to be wrapped.
  69       derivation
  70     , # Optional meta attribute.
  71       #
  72       # While this function is primarily about derivations, it can improve
  73       # the `meta` package attribute, which is usually specified through
  74       # `mkDerivation`.
  75       meta ? null
  76     , # Optional extra values to add to the returned attrset.
  77       #
  78       # This can be used for adding package attributes, such as `tests`.
  79       passthru ? { }
  80     , # Optional list of assumed outputs. Default: ["out"]
  81       #
  82       # This must match the set of outputs that the returned derivation has.
  83       # You must use this when the derivation has multiple outputs.
  84       outputs ? [ "out" ]
  85     }:
  86     let
  87       # These checks are strict in `drv` and some `drv` attributes, but the
  88       # attrset spine returned by lazyDerivation does not depend on it.
  89       # Instead, the individual derivation attributes do depend on it.
  90       checked =
  91         throwIfNot (derivation.type or null == "derivation")
  92           "lazyDerivation: input must be a derivation."
  93           throwIfNot
  94           # NOTE: Technically we could require our outputs to be a subset of the
  95           # actual ones, or even leave them unchecked and fail on a lazy basis.
  96           # However, consider the case where an output is added in the underlying
  97           # derivation, such as dev. lazyDerivation would remove it and cause it
  98           # to fail as a buildInputs item, without any indication as to what
  99           # happened. Hence the more stringent condition. We could consider
 100           # adding a flag to control this behavior if there's a valid case for it,
 101           # but the documentation must have a note like this.
 102           (derivation.outputs == outputs)
 103           ''
 104             lib.lazyDerivation: The derivation ${derivation.name or "<unknown>"} has outputs that don't match the assumed outputs.
 105
 106             Assumed outputs passed to lazyDerivation${showMaybeAttrPosPre ",\n    at " "outputs" args}:
 107                 ${lib.generators.toPretty { multiline = false; } outputs};
 108
 109             Actual outputs of the derivation${showMaybePackagePosPre ",\n    defined at " derivation}:
 110                 ${lib.generators.toPretty { multiline = false; } derivation.outputs}
 111
 112             If the outputs are known ahead of evaluating the derivation,
 113             then update the lazyDerivation call to match the actual outputs, in the same order.
 114             If lazyDerivation is passed a literal value, just change it to the actual outputs.
 115             As a result it will work as before / as intended.
 116
 117             Otherwise, when the outputs are dynamic and can't be known ahead of time, it won't
 118             be possible to add laziness, but lib.lazyDerivation may still be useful for trimming
 119             the attributes.
 120             If you want to keep trimming the attributes, make sure that the package is in a
 121             variable (don't evaluate it twice!) and pass the variable and its outputs attribute
 122             to lib.lazyDerivation. This largely defeats laziness, but keeps the trimming.
 123             If none of the above works for you, replace the lib.lazyDerivation call by the
 124             expression in the derivation argument.
 125           ''
 126           derivation;
 127     in
 128     {
 129       # Hardcoded `type`
 130       #
 131       # `lazyDerivation` requires its `derivation` argument to be a derivation,
 132       # so if it is not, that is a programming error by the caller and not
 133       # something that `lazyDerivation` consumers should be able to correct
 134       # for after the fact.
 135       # So, to improve laziness, we assume correctness here and check it only
 136       # when actual derivation values are accessed later.
 137       type = "derivation";
 138
 139       # A fixed set of derivation values, so that `lazyDerivation` can return
 140       # its attrset before evaluating `derivation`.
 141       # This must only list attributes that are available on _all_ derivations.
 142       inherit (checked) outPath outputName drvPath name system;
 143       inherit outputs;
 144
 145       # The meta attribute can either be taken from the derivation, or if the
 146       # `lazyDerivation` caller knew a shortcut, be taken from there.
 147       meta = args.meta or checked.meta;
 148     }
 149     // genAttrs outputs (outputName: checked.${outputName})
 150     // passthru;
 151
 152   /* Conditionally set a derivation attribute.
 153
 154      Because `mkDerivation` sets `__ignoreNulls = true`, a derivation
 155      attribute set to `null` will not impact the derivation output hash.
 156      Thus, this function passes through its `value` argument if the `cond`
 157      is `true`, but returns `null` if not.
 158
 159      Type: optionalDrvAttr :: Bool -> a -> a | Null
 160
 161      Example:
 162        (stdenv.mkDerivation {
 163          name = "foo";
 164          x = optionalDrvAttr true 1;
 165          y = optionalDrvAttr false 1;
 166        }).drvPath == (stdenv.mkDerivation {
 167          name = "foo";
 168          x = 1;
 169        }).drvPath
 170        => true
 171   */
 172   optionalDrvAttr =
 173     # Condition
 174     cond:
 175     # Attribute value
 176     value: if cond then value else null;
 177 }