lib.customisation.makeOverridable

The following is the current implementation of this function.

makeOverridable =
    f:
    let
      # Creates a functor with the same arguments as f
      mirrorArgs = mirrorFunctionArgs f;
      # Recover overrider and additional attributes for f
      # When f is a callable attribute set,
      # it may contain its own `f.override` and additional attributes.
      # This helper function recovers those attributes and decorate the overrider.
      recoverMetadata =
        if isAttrs f then
          fDecorated:
          # Preserve additional attributes for f
          f
          // fDecorated
          # Decorate f.override if presented
          // lib.optionalAttrs (f ? override) {
            override = fdrv: makeOverridable (f.override fdrv);
          }
        else
          id;
      decorate = f': recoverMetadata (mirrorArgs f');
    in
    decorate (
      origArgs:
      let
        result = f origArgs;

        # Changes the original arguments with (potentially a function that returns) a set of new attributes
        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
      if isAttrs result then
        result
        // {
          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
        # Transform the result into a functor while propagating its arguments
        setFunctionArgs result (functionArgs result)
        // {
          override = overrideArgs;
        }
      else
        result
    );