lib, mkDerivation: Document overriding functions (#428563)

Changed files
+24 -1
lib
pkgs
stdenv
+20 -1
lib/customisation.nix
···
overrideWith = newArgs: origArgs // (if isFunction newArgs then newArgs origArgs else newArgs);
# Re-call the function but with different arguments
-
overrideArgs = mirrorArgs (newArgs: makeOverridable f (overrideWith newArgs));
# Change the result of the function call by applying g to it
overrideResult = g: makeOverridable (mirrorArgs (args: g (f args))) origArgs;
in
···
override = overrideArgs;
overrideDerivation = fdrv: overrideResult (x: overrideDerivation x fdrv);
${if result ? overrideAttrs then "overrideAttrs" else null} =
fdrv: overrideResult (x: x.overrideAttrs fdrv);
}
else if isFunction result then
···
overrideWith = newArgs: origArgs // (if isFunction newArgs then newArgs origArgs else newArgs);
# Re-call the function but with different arguments
+
overrideArgs = mirrorArgs (
+
/**
+
Change the arguments with which a certain function is called.
+
+
In some cases, you may find a list of possible attributes to pass in this function's `__functionArgs` attribute, but it will not be complete for an original function like `args@{foo, ...}: ...`, which accepts arbitrary attributes.
+
+
This function was provided by `lib.makeOverridable`.
+
*/
+
newArgs: makeOverridable f (overrideWith newArgs)
+
);
# Change the result of the function call by applying g to it
overrideResult = g: makeOverridable (mirrorArgs (args: g (f args))) origArgs;
in
···
override = overrideArgs;
overrideDerivation = fdrv: overrideResult (x: overrideDerivation x fdrv);
${if result ? overrideAttrs then "overrideAttrs" else null} =
+
/**
+
Override the attributes that were passed to `mkDerivation` in order to generate this derivation.
+
+
This function is provided by `lib.makeOverridable`, and indirectly by `callPackage` among others, in order to make the combination of `override` and `overrideAttrs` work.
+
Specifically, it re-adds the `override` attribute to the result of `overrideAttrs`.
+
+
The real implementation of `overrideAttrs` is provided by `stdenv.mkDerivation`.
+
*/
+
# NOTE: part of the above documentation had to be duplicated in `mkDerivation`'s `overrideAttrs`.
+
# design/tech debt issue: https://github.com/NixOS/nixpkgs/issues/273815
fdrv: overrideResult (x: x.overrideAttrs fdrv);
}
else if isFunction result then
+4
pkgs/stdenv/generic/make-derivation.nix
···
args = rattrs (args // { inherit finalPackage overrideAttrs; });
# ^^^^
overrideAttrs =
f0:
let
···
args = rattrs (args // { inherit finalPackage overrideAttrs; });
# ^^^^
+
/**
+
Override the attributes that were passed to `mkDerivation` in order to generate this derivation.
+
*/
+
# NOTE: the above documentation had to be duplicated in `lib/customisation.nix`: `makeOverridable`.
overrideAttrs =
f0:
let