diff options
| -rw-r--r-- | doc/module-system/module-system.chapter.md | 9 | ||||
| -rw-r--r-- | flake.nix | 2 | ||||
| -rw-r--r-- | lib/default.nix | 31 |
3 files changed, 40 insertions, 2 deletions
diff --git a/doc/module-system/module-system.chapter.md b/doc/module-system/module-system.chapter.md index d24faa255259..0c91012eebb4 100644 --- a/doc/module-system/module-system.chapter.md +++ b/doc/module-system/module-system.chapter.md @@ -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. diff --git a/flake.nix b/flake.nix index 8510ce7e69bd..83ae9decf803 100644 --- a/flake.nix +++ b/flake.nix @@ -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: { /** diff --git a/lib/default.nix b/lib/default.nix index 849d6ce8f9d6..e77d053b8cc0 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -5,9 +5,36 @@ */ 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 + 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 { |