Unverified Commit a7c20102 authored by Robert Hensing's avatar Robert Hensing Committed by GitHub
Browse files

lib: Discourage use of extend (#376033)

parents 41b9d91a 55a11de1

doc/module-system/module-system.chapter.md

+9 −0
Original line number Diff line number Diff line
@@ -31,6 +31,15 @@ An attribute set of module arguments that can be used in `imports`. 


This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved.



::: {.warning}

You may be tempted to use `specialArgs.lib` to provide extra library functions. Doing so limits the interoperability of modules, as well as the interoperability of Module System applications.



`lib` is reserved for the Nixpkgs library, and should not be used for custom functions.



Instead, you may create a new attribute in `specialArgs` to provide custom functions.

This clarifies their origin and avoids incompatibilities.

:::



#### `class` {#module-system-lib-evalModules-param-class}



If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.

flake.nix

+2 −0
Original line number Diff line number Diff line
@@ -24,6 +24,8 @@ 


        - `lib.nixos` for other NixOS-provided functionality, such as [`runTest`](https://nixos.org/manual/nixos/unstable/#sec-call-nixos-test-outside-nixos)

      */

      # DON'T USE lib.extend TO ADD NEW FUNCTIONALITY.

      # THIS WAS A MISTAKE. See the warning in lib/default.nix.

      lib = lib.extend (final: prev: {



        /**

lib/default.nix

+34 −2
Original line number Diff line number Diff line
@@ -5,9 +5,41 @@ 
 */

let



  inherit (import ./fixed-points.nix { inherit lib; }) makeExtensible;

  # A copy of `lib.makeExtensible'` in order to document `extend`.

  # It has been leading to some trouble, so we have to document it specially.

  makeExtensible' =

    rattrs:

    let self = rattrs self // {

          /**

            Patch the Nixpkgs library



  lib = makeExtensible (self: let

            A function that applies patches onto the nixpkgs library.

            Usage is discouraged for most scenarios.



            :::{.note}

            The name `extends` is a bit misleading, as it doesn't actually extend the library, but rather patches it.

            It is merely a consequence of being implemented by `makeExtensible`.

            :::



            # Inputs



            - An "extension function" `f` that returns attributes that will be updated in the returned Nixpkgs library.



            # Output



            A patched Nixpkgs library.



            :::{.warning}

            This functionality is intended as an escape hatch for when the provided version of the Nixpkgs library has a flaw.



            If you were to use it to add new functionality, you will run into compatibility and interoperability issues.

            :::

          */

          extend = f: lib.makeExtensible (lib.extends f rattrs);

        };

    in self;



  lib = makeExtensible' (self: let

    callLibs = file: import file { lib = self; };

  in {