lib: Discourage use of extend

[roberth]

It creates interoperability issues that can not be reconciled by lib or maintainers of projects that use the Nixpkgs library. Occasionally, end users may be able to solve the problems they run into, but most are not prepared to deal with this set of problems, nor should they be.

Typical conflict:

• User wants to propagate their own lib, because it has some function they like to use throughout their projects
• Project maintainer requires the project's lib to be used

No sane language uses a single namespace for combining all the things. (Arguably not even C with its extensive use of prefixing)

Meanwhile, in Nix, all symbols are first class variables. We don't even have the concept of a global top-level namespace to pour everything into. With lib you can try to approximate that, I get the appeal of its apparent simplicity, but since lib can't be global, we just don't even get that apparent simplicity.

I apologize for not offering concrete solutions to this in the text. The manuals are limited to reference documentation. Alternatives - of which we have multiple - are best provided in task-oriented documentation, e.g. nix.dev.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[hsjobeki]

lgtm.
I dont know how to display the doc-comment in the repl or on noogle for this yet.

[roberth]

how to display the doc-comment in the repl

Seems to work in the repl, Nix 2.25

nix-repl> :doc lib.extend
Function extend
    … defined at /home/user/h/nixpkgs/lib/default.nix:38:20

    Patch the Nixpkgs library
[...]

I guess for nixdoc we'd have to construct a fake sublibrary to represent the top level or something to make it work? We can't just do lib because that has a copy of a majority of functions.