Documentation for the builders (renamed: build helpers)

[ShamrockLee]

Description of changes

In Nixpkgs, we have several functions that helps defining a derivation. Such function is currently called "builders", and are document in the Builders part in the Nixpkgs manual.

This PR aims to

1. Define and introduce the builders in the Nixpkgs manual.
2. Properly document the function-based attribute recursion (finalAttrs: { }) to distinguish it from the recursive attribute (rec { }).
3. Document the new approach to define a builder that supports function-based attribute recursion and add such support to existing builder implementations through lib.extendMkDerivation and lib.extendMkDerivationModified introduced in lib.extendMkDerivation: init #234651. (Split out of this PR)
4. Discuss if we wouldike to rename the term "builder" to something else. (Previous discussion: lib.extendMkDerivation: init #234651 (comment)) (candidate: build helper)

This PR also

• Moves Nixpkgs manual section darwin.linux-builder from chapter Special build helper to chapter Packages, and emphasize that it is about remote builder bootstrap instead of build helpers.
• Moves doc/build-helpers/packages/ -> doc/packages/ to make it parallel to doc/hooks/ and prepare for future migration. (The Packages chapter is mostly not about build helpers.)

Closes #235858

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/)
• 23.11 Release Notes (or backporting 23.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.

[fricklerhandwerk]

The new documentation is great and the names are terrible. Let the bikeshedfest begin.

[fricklerhandwerk]

This should use an :::{example} block, but I wouldn't... block on that.

[ShamrockLee]

Thank you for telling me that!

BTW, this part of documentation seems to be a duplication of the function reference of lib.extendMkDerivation. I originally write it here just because lib.customization was not included in the function reference then.

I think we should either:

1. Link from here to the function reference, or
2. Link form the function reference to here.

The first one sounds more sensible to me. It's a pity that we don't have a way to link against the documentation of each function.

[ShamrockLee]

This should use an :::{example} block, but I wouldn't... block on that.

Addressed.

The example block rendering seems a bit buggy. It randomly affects the style of the next few paragraphs (e.g. showing underline when moving the point er across the paragraphs).

[ShamrockLee]

It's a pity that we don't have a way to link against the documentation of each function.

Update:

We do have a way to link against it. The anchor would be finction-library-lib.customisation.extendMkDerivation. I really hope these automatic generation of anchors could be mentioned somewhere in the documentation.

[fricklerhandwerk]

@ShamrockLee if you don't have time I could take over the fixups. If there is no further feedback in the next 1-2 weeks we should merge this.

[ShamrockLee]

A big wind just blew:

• doc/builders/packages -> doc/packages (without document changes, just like "languages and frameworks" and "hooks")
• doc/builders/spacial/darwin-builder.md -> doc/packages/spacial/darwin-builder.md (with document changes)
• doc/builders -> doc/build-helpers (with document changes)

[ShamrockLee]

Rebase to resolve conflicts with master changes.

[fricklerhandwerk]

This has seen quite a bit of work now, and it's a very strong improvement over the previous state of affairs.

[ShamrockLee]

Two examples added to the "Build Helper" introduction chapter.

[ShamrockLee]

It is only the last commit that depends on #234651. It's possible to split that commit away if we hope to merge this earlier. (Nixpkgs release 23.11 seems on the way.)

[fricklerhandwerk]

Yes, let's split out that last one and merge soon.

[ShamrockLee]

Yes, let's split out that last one and merge soon.

Just dropped it from this feature branch.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-10-30-documentation-team-meeting-notes-90/34936/1

[ShamrockLee]

Rebase to resolve merge conflicts.

Addressed all comments

[fricklerhandwerk]

@infinisil @roberth @RaitoBezarius this needs another approval. I'd like to merge that as is, it's a very strong improvement.

[infinisil]

Needs another rebase, but otherwise looking good!

[ShamrockLee]

Do we need to add entries in the release note for these changes?

The file hierarchy inside the doc directory seems rather internal. Let's keep it as is.