Advise against direct use of builtins in docs

[roberth]

Problem

Changing the behavior of builtins is risky to impossible, as we promise to evaluate reproducibly over time.
(that's without language versioning, which is hard to pull off in any kind of friendly, robust way EDIT: and which would be detrimental to the ecosystem due to opportunity cost)

Proposal

Nixpkgs lib and possibly alternative libraries extend and improve the builtins.

• Recommend to use those functions whenever possible.
  This also settles the question: should I use builtins or lib? Always lib. It's better.
• Highlight known differences between builtins and Nixpkgs lib. A worthwhile layering violation.

Checklist

• checked latest Nix manual (source)
• checked open documentation issues and pull requests for possible duplicates

Context

• lib.types.functionTo: preserve functionArgs nixpkgs#386208 (comment)

---

Add 👍 to issues you find important.

[philiptaron]

I really like "editions" to solve these problems, as the Rust folks are doing now every three years. This issue isn't the place to design "Nix editions" if we followed in their steps, obviously, but sometime and somehow we're going to do them, in some way, because ossification ends with being fossilized.

Other dynamic languages like Perl and JavaScript end up using sigils like 'use strict' or similar to indicate how things ought to evaluate.

Others like Python use from __future__ import ... to bring new semantics in.

Because Nix is expression-oriented, rather than having a prelude, this is trickier to do. One possible option is to use a combination of file extensions (.nix2, .nix2027, etc) and import2027 functions to indicate the evaluation domain.

lib also might involve NixOS/nixpkgs#381862 as well.

[roberth]

I believe it's too soon to introduce the complexity of multiple language versions, and its' not a silver bullet. For instance, changing the default language of CLI arguments is a breaking change. We should make breaking changes eventually, but my preference would be to build a new, compatible language based on all the insights we've gained.
Until then, there's a lot we can do without breaking the language or burdening users with that added complexity of language versions.
Extensive discussion has already taken place in NixOS/rfcs#137 if you're interested, although I believe it to be something between a nerd snipe, tar pit and infohazard, certainly for the time being.
Maybe it could be done after one or two "cycles" of solving higher impact issues and the growth that will result from that. In the coming two years at least it would be detrimental.

[roberth]

Discussed in meeting:

Approved with caveat that the point isn't that Nix can lean on mediation through lib for it to be compatible with the expression world.

Recommend to use lib if it is around.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2025-06-11-nix-team-meeting-minutes-231/65543/1

[fricklerhandwerk]

IMO in the Nix manual this should take the form of something like "wrap builtins in a library to abstract over possible interface changes", and then do the full elaboration in the Nixpkgs manual. For extra emphasis we can add a best practice entry to nix.dev.