Unverified Commit 01df068c authored by Philip Taron's avatar Philip Taron Committed by GitHub
Browse files

lib, mkDerivation: Document overriding functions (#428563)

parents e601df36 b3255718

lib/customisation.nix

+20 −1
Original line number Diff line number Diff line
@@ -166,7 +166,16 @@ rec { 
        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));

        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
@@ -176,6 +185,16 @@ rec { 
          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

pkgs/stdenv/generic/make-derivation.nix

+4 −0
Original line number Diff line number Diff line
@@ -84,6 +84,10 @@ 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