Merge staging-next into staging

45 files changed, 85 insertions, 29 deletions

diff --git a/doc/build-helpers.md b/doc/build-helpers.md
new file mode 100644
index 00000000000..06737e16676
--- /dev/null
+++ b/doc/build-helpers.md
@@ -0,0 +1,28 @@
+# Build helpers {#part-builders}
+
+A build helper is a function that produces derivations.
+
+:::{.warning}
+This is not to be confused with the [`builder` argument of the Nix `derivation` primitive](https://nixos.org/manual/nix/unstable/language/derivations.html), which refers to the executable that produces the build result, or [remote builder](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds.html), which refers to a remote  machine that could run such an executable.
+:::
+
+Such a function is usually designed to abstract over a typical workflow for a given programming language or framework.
+This allows declaring a build recipe by setting a limited number of options relevant to the particular use case instead of using the `derivation` function directly.
+
+[`stdenv.mkDerivation`](#part-stdenv) is the most widely used build helper, and serves as a basis for many others.
+In addition, it offers various options to customize parts of the builds.
+
+There is no uniform interface for build helpers.
+[Trivial build helpers](#chap-trivial-builders) and [fetchers](#chap-pkgs-fetchers) have various input types for convenience.
+[Language- or framework-specific build helpers](#chap-language-support) usually follow the style of `stdenv.mkDerivation`, which accepts an attribute set or a fixed-point function taking an attribute set.
+
+```{=include=} chapters
+build-helpers/fetchers.chapter.md
+build-helpers/trivial-build-helpers.chapter.md
+build-helpers/testers.chapter.md
+build-helpers/special.md
+build-helpers/images.md
+hooks/index.md
+languages-frameworks/index.md
+packages/index.md
+```
diff --git a/doc/builders/fetchers.chapter.md b/doc/build-helpers/fetchers.chapter.md
index 7bd1bbd6de0..7bd1bbd6de0 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/build-helpers/fetchers.chapter.md
diff --git a/doc/builders/images.md b/doc/build-helpers/images.md
index 5596784bfa4..5596784bfa4 100644
--- a/doc/builders/images.md
+++ b/doc/build-helpers/images.md
diff --git a/doc/builders/images/appimagetools.section.md b/doc/build-helpers/images/appimagetools.section.md
index 0c72315a26e..0c72315a26e 100644
--- a/doc/builders/images/appimagetools.section.md
+++ b/doc/build-helpers/images/appimagetools.section.md
diff --git a/doc/builders/images/binarycache.section.md b/doc/build-helpers/images/binarycache.section.md
index 62e47dad7c6..62e47dad7c6 100644
--- a/doc/builders/images/binarycache.section.md
+++ b/doc/build-helpers/images/binarycache.section.md
diff --git a/doc/builders/images/dockertools.section.md b/doc/build-helpers/images/dockertools.section.md
index 42d6e297f52..42d6e297f52 100644
--- a/doc/builders/images/dockertools.section.md
+++ b/doc/build-helpers/images/dockertools.section.md
diff --git a/doc/builders/images/makediskimage.section.md b/doc/build-helpers/images/makediskimage.section.md
index e50479c4e83..e50479c4e83 100644
--- a/doc/builders/images/makediskimage.section.md
+++ b/doc/build-helpers/images/makediskimage.section.md
diff --git a/doc/builders/images/ocitools.section.md b/doc/build-helpers/images/ocitools.section.md
index c35f65bce00..c35f65bce00 100644
--- a/doc/builders/images/ocitools.section.md
+++ b/doc/build-helpers/images/ocitools.section.md
diff --git a/doc/builders/images/portableservice.section.md b/doc/build-helpers/images/portableservice.section.md
index 5400928b158..5400928b158 100644
--- a/doc/builders/images/portableservice.section.md
+++ b/doc/build-helpers/images/portableservice.section.md
diff --git a/doc/builders/images/snaptools.section.md b/doc/build-helpers/images/snaptools.section.md
index 259fa1b0618..259fa1b0618 100644
--- a/doc/builders/images/snaptools.section.md
+++ b/doc/build-helpers/images/snaptools.section.md
diff --git a/doc/builders/special.md b/doc/build-helpers/special.md
index 6d07fa87f3f..f88648207fd 100644
--- a/doc/builders/special.md
+++ b/doc/build-helpers/special.md
@@ -1,11 +1,10 @@
-# Special builders {#chap-special}
+# Special build helpers {#chap-special}
 
-This chapter describes several special builders.
+This chapter describes several special build helpers.
 
 ```{=include=} sections
 special/fhs-environments.section.md
 special/makesetuphook.section.md
 special/mkshell.section.md
-special/darwin-builder.section.md
 special/vm-tools.section.md
 ```
diff --git a/doc/builders/special/fhs-environments.section.md b/doc/build-helpers/special/fhs-environments.section.md
index 8145fbd730f..8145fbd730f 100644
--- a/doc/builders/special/fhs-environments.section.md
+++ b/doc/build-helpers/special/fhs-environments.section.md
diff --git a/doc/builders/special/makesetuphook.section.md b/doc/build-helpers/special/makesetuphook.section.md
index eb042412137..e83164b7eb7 100644
--- a/doc/builders/special/makesetuphook.section.md
+++ b/doc/build-helpers/special/makesetuphook.section.md
@@ -1,6 +1,6 @@
 # pkgs.makeSetupHook {#sec-pkgs.makeSetupHook}
 
-`pkgs.makeSetupHook` is a builder that produces hooks that go in to `nativeBuildInputs`
+`pkgs.makeSetupHook` is a build helper that produces hooks that go in to `nativeBuildInputs`
 
 ## Usage {#sec-pkgs.makeSetupHook-usage}
 
diff --git a/doc/builders/special/mkshell.section.md b/doc/build-helpers/special/mkshell.section.md
index 96d43535955..96d43535955 100644
--- a/doc/builders/special/mkshell.section.md
+++ b/doc/build-helpers/special/mkshell.section.md
diff --git a/doc/builders/special/vm-tools.section.md b/doc/build-helpers/special/vm-tools.section.md
index 8feab04902d..8feab04902d 100644
--- a/doc/builders/special/vm-tools.section.md
+++ b/doc/build-helpers/special/vm-tools.section.md
diff --git a/doc/builders/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index b2a581c3dd8..b2a581c3dd8 100644
--- a/doc/builders/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
diff --git a/doc/builders/trivial-builders.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md
index 2cb1f2debcb..a0cda86a660 100644
--- a/doc/builders/trivial-builders.chapter.md
+++ b/doc/build-helpers/trivial-build-helpers.chapter.md
@@ -1,4 +1,4 @@
-# Trivial builders {#chap-trivial-builders}
+# Trivial build helpers {#chap-trivial-builders}
 
 Nixpkgs provides a couple of functions that help with building derivations. The most important one, `stdenv.mkDerivation`, has already been documented above. The following functions wrap `stdenv.mkDerivation`, making it easier to use in certain cases.
 
diff --git a/doc/builders.md b/doc/builders.md
deleted file mode 100644
index 2e959422405..00000000000
--- a/doc/builders.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Builders {#part-builders}
-
-```{=include=} chapters
-builders/fetchers.chapter.md
-builders/trivial-builders.chapter.md
-builders/testers.chapter.md
-builders/special.md
-builders/images.md
-hooks/index.md
-languages-frameworks/index.md
-builders/packages/index.md
-```
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index cdd5c806912..69a95f482fb 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -142,7 +142,7 @@ buildPythonPackage rec {
 
 The `buildPythonPackage` mainly does four things:
 
-* In the [`buildPhase`](#build-phase), it calls `${python.pythonForBuild.interpreter} setup.py bdist_wheel` to
+* In the [`buildPhase`](#build-phase), it calls `${python.pythonOnBuildForHost.interpreter} setup.py bdist_wheel` to
   build a wheel binary zipfile.
 * In the [`installPhase`](#ssec-install-phase), it installs the wheel file using `pip install *.whl`.
 * In the [`postFixup`](#var-stdenv-postFixup) phase, the `wrapPythonPrograms` bash function is called to
@@ -1682,7 +1682,7 @@ of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
 As workaround install it as an extra `preInstall` step:
 
 ```shell
-${python.pythonForBuild.interpreter} setup.py install_data --install-dir=$out --root=$out
+${python.pythonOnBuildForHost.interpreter} setup.py install_data --install-dir=$out --root=$out
 sed -i '/ = data\_files/d' setup.py
 ```
 
diff --git a/doc/languages-frameworks/texlive.section.md b/doc/languages-frameworks/texlive.section.md
index 777e94c16f1..2ba846dc492 100644
--- a/doc/languages-frameworks/texlive.section.md
+++ b/doc/languages-frameworks/texlive.section.md
@@ -2,6 +2,46 @@
 
 Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute `texlive`.
 
+## User's guide (experimental new interface) {#sec-language-texlive-user-guide-experimental}
+
+Release 23.11 ships with a new interface that will eventually replace `texlive.combine`.
+
+- For basic usage, use some of the prebuilt environments available at the top level, such as `texliveBasic`, `texliveSmall`. For the full list of prebuilt environments, inspect `texlive.schemes`.
+
+- Packages cannot be used directly but must be assembled in an environment. To create or add packages to an environment, use
+  ```nix
+  texliveSmall.withPackages (ps: with ps; [ collection-langkorean algorithms cm-super ])
+  ```
+  The function `withPackages` can be called multiple times to add more packages.
+
+  - **Note.** Within Nixpkgs, packages should only use prebuilt environments as inputs, such as `texliveSmall` or `texliveInfraOnly`, and should not depend directly on `texlive`. Further dependencies should be added by calling `withPackages`. This is to ensure that there is a consistent and simple way to override the inputs.
+
+- `texlive.withPackages` uses the same logic as `buildEnv`. Only parts of a package are installed in an environment: its 'runtime' files (`tex` output), binaries (`out` output), and support files (`tlpkg` output). Moreover, man and info pages are assembled into separate `man` and `info` outputs. To add only the TeX files of a package, or its documentation (`texdoc` output), just specify the outputs:
+  ```nix
+  texlive.withPackages (ps: with ps; [
+    texdoc # recommended package to navigate the documentation
+    perlPackages.LaTeXML.tex # tex files of LaTeXML, omit binaries
+    cm-super
+    cm-super.texdoc # documentation of cm-super
+  ])
+  ```
+
+- All packages distributed by TeX Live, which contains most of CTAN, are available and can be found under `texlive.pkgs`:
+  ```ShellSession
+  $ nix repl
+  nix-repl> :l <nixpkgs>
+  nix-repl> texlive.pkgs.[TAB]
+  ```
+  Note that the packages in `texlive.pkgs` are only provided for search purposes and must not be used directly.
+
+- **Experimental and subject to change without notice:** to add the documentation for all packages in the environment, use
+  ```nix
+  texliveSmall.__overrideTeXConfig { withDocs = true; }
+  ```
+  This can be applied before or after calling `withPackages`.
+
+  The function currently support the parameters `withDocs`, `withSources`, and `requireTeXPackages`.
+
 ## User's guide {#sec-language-texlive-user-guide}
 
 - For basic usage just pull `texlive.combined.scheme-basic` for an environment with basic LaTeX support.
diff --git a/doc/manual.md.in b/doc/manual.md.in
index 6b8d351380f..52971ff526c 100644
--- a/doc/manual.md.in
+++ b/doc/manual.md.in
@@ -9,7 +9,7 @@ preface.chapter.md
 using-nixpkgs.md
 lib.md
 stdenv.md
-builders.md
+build-helpers.md
 development.md
 contributing.md
 ```
diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/packages/cataclysm-dda.section.md
index f401e9b9efa..f401e9b9efa 100644
--- a/doc/builders/packages/cataclysm-dda.section.md
+++ b/doc/packages/cataclysm-dda.section.md
diff --git a/doc/builders/packages/citrix.section.md b/doc/packages/citrix.section.md
index bcf0924249b..bcf0924249b 100644
--- a/doc/builders/packages/citrix.section.md
+++ b/doc/packages/citrix.section.md
diff --git a/doc/builders/special/darwin-builder.section.md b/doc/packages/darwin-builder.section.md
index e37fabe01a3..89c2445667d 100644
--- a/doc/builders/special/darwin-builder.section.md
+++ b/doc/packages/darwin-builder.section.md
@@ -1,10 +1,10 @@
 # darwin.linux-builder {#sec-darwin-builder}
 
-`darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine.
+`darwin.linux-builder` provides a way to bootstrap a Linux remote builder on a macOS machine.
 
 This requires macOS version 12.4 or later.
 
-The builder runs on host port 31022 by default.
+The remote builder runs on host port 31022 by default.
 You can change it by overriding `virtualisation.darwin-builder.hostPort`.
 See the [example](#sec-darwin-builder-example-flake).
 
@@ -15,7 +15,7 @@ words, your `/etc/nix/nix.conf` should have something like:
 extra-trusted-users = <your username goes here>
 ```
 
-To launch the builder, run the following flake:
+To launch the remote builder, run the following flake:
 
 ```ShellSession
 $ nix run nixpkgs#darwin.linux-builder
@@ -57,7 +57,7 @@ builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519
 builders-use-substitutes = true
 ```
 
-To allow Nix to connect to a builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`:
+To allow Nix to connect to a remote builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`:
 
 ```
 Host linux-builder
@@ -130,11 +130,11 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
 }
 ```
 
-## Reconfiguring the builder {#sec-darwin-builder-reconfiguring}
+## Reconfiguring the remote builder {#sec-darwin-builder-reconfiguring}
 
-Initially you should not change the builder configuration else you will not be
-able to use the binary cache. However, after you have the builder running locally
-you may use it to build a modified builder with additional storage or memory.
+Initially you should not change the remote builder configuration else you will not be
+able to use the binary cache. However, after you have the remote builder running locally
+you may use it to build a modified remote builder with additional storage or memory.
 
 To do this, you just need to set the `virtualisation.darwin-builder.*` parameters as
 in the example below and rebuild.
diff --git a/doc/builders/packages/dlib.section.md b/doc/packages/dlib.section.md
index bd5b1a20a4d..bd5b1a20a4d 100644
--- a/doc/builders/packages/dlib.section.md
+++ b/doc/packages/dlib.section.md
diff --git a/doc/builders/packages/eclipse.section.md b/doc/packages/eclipse.section.md
index e19510e131a..e19510e131a 100644
--- a/doc/builders/packages/eclipse.section.md
+++ b/doc/packages/eclipse.section.md
diff --git a/doc/builders/packages/elm.section.md b/doc/packages/elm.section.md
index 063dd73d9de..063dd73d9de 100644
--- a/doc/builders/packages/elm.section.md
+++ b/doc/packages/elm.section.md
diff --git a/doc/builders/packages/emacs.section.md b/doc/packages/emacs.section.md
index c50c7815537..c50c7815537 100644
--- a/doc/builders/packages/emacs.section.md
+++ b/doc/packages/emacs.section.md
diff --git a/doc/builders/packages/etc-files.section.md b/doc/packages/etc-files.section.md
index 94a769ed335..94a769ed335 100644
--- a/doc/builders/packages/etc-files.section.md
+++ b/doc/packages/etc-files.section.md
diff --git a/doc/builders/packages/firefox.section.md b/doc/packages/firefox.section.md
index 46bc0457a3d..46bc0457a3d 100644
--- a/doc/builders/packages/firefox.section.md
+++ b/doc/packages/firefox.section.md
diff --git a/doc/builders/packages/fish.section.md b/doc/packages/fish.section.md
index 85b57acd109..85b57acd109 100644
--- a/doc/builders/packages/fish.section.md
+++ b/doc/packages/fish.section.md
diff --git a/doc/builders/packages/fuse.section.md b/doc/packages/fuse.section.md
index 6deea6b5626..6deea6b5626 100644
--- a/doc/builders/packages/fuse.section.md
+++ b/doc/packages/fuse.section.md
diff --git a/doc/builders/packages/ibus.section.md b/doc/packages/ibus.section.md
index 817e55d56f1..817e55d56f1 100644
--- a/doc/builders/packages/ibus.section.md
+++ b/doc/packages/ibus.section.md
diff --git a/doc/builders/packages/index.md b/doc/packages/index.md
index 1f443570240..1f45018ffc4 100644
--- a/doc/builders/packages/index.md
+++ b/doc/packages/index.md
@@ -4,6 +4,7 @@ This chapter contains information about how to use and maintain the Nix expressi
 
 ```{=include=} sections
 citrix.section.md
+darwin-builder.section.md
 dlib.section.md
 eclipse.section.md
 elm.section.md
diff --git a/doc/builders/packages/kakoune.section.md b/doc/packages/kakoune.section.md
index 8e054777a75..8e054777a75 100644
--- a/doc/builders/packages/kakoune.section.md
+++ b/doc/packages/kakoune.section.md
diff --git a/doc/builders/packages/linux.section.md b/doc/packages/linux.section.md
index b64da85791a..b64da85791a 100644
--- a/doc/builders/packages/linux.section.md
+++ b/doc/packages/linux.section.md
diff --git a/doc/builders/packages/locales.section.md b/doc/packages/locales.section.md
index 3a983f13a39..3a983f13a39 100644
--- a/doc/builders/packages/locales.section.md
+++ b/doc/packages/locales.section.md
diff --git a/doc/builders/packages/nginx.section.md b/doc/packages/nginx.section.md
index 0704b534e5f..0704b534e5f 100644
--- a/doc/builders/packages/nginx.section.md
+++ b/doc/packages/nginx.section.md
diff --git a/doc/builders/packages/opengl.section.md b/doc/packages/opengl.section.md
index f4d282267a0..f4d282267a0 100644
--- a/doc/builders/packages/opengl.section.md
+++ b/doc/packages/opengl.section.md
diff --git a/doc/builders/packages/shell-helpers.section.md b/doc/packages/shell-helpers.section.md
index e7c2b0abebf..e7c2b0abebf 100644
--- a/doc/builders/packages/shell-helpers.section.md
+++ b/doc/packages/shell-helpers.section.md
diff --git a/doc/builders/packages/steam.section.md b/doc/packages/steam.section.md
index 25728aa52ae..25728aa52ae 100644
--- a/doc/builders/packages/steam.section.md
+++ b/doc/packages/steam.section.md
diff --git a/doc/builders/packages/urxvt.section.md b/doc/packages/urxvt.section.md
index 507feaa6fd8..507feaa6fd8 100644
--- a/doc/builders/packages/urxvt.section.md
+++ b/doc/packages/urxvt.section.md
diff --git a/doc/builders/packages/weechat.section.md b/doc/packages/weechat.section.md
index 755b6e6ad1e..755b6e6ad1e 100644
--- a/doc/builders/packages/weechat.section.md
+++ b/doc/packages/weechat.section.md
diff --git a/doc/builders/packages/xorg.section.md b/doc/packages/xorg.section.md
index ae885f92346..ae885f92346 100644
--- a/doc/builders/packages/xorg.section.md
+++ b/doc/packages/xorg.section.md
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index 1dfe25f0265..53243af5f23 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -528,7 +528,7 @@ If the returned array contains exactly one object (e.g. `[{}]`), all values are
 ```
 :::
 
-### Recursive attributes in `mkDerivation` {#mkderivation-recursive-attributes}
+### Fixed-point arguments of `mkDerivation` {#mkderivation-recursive-attributes}
 
 If you pass a function to `mkDerivation`, it will receive as its argument the final arguments, including the overrides when reinvoked via `overrideAttrs`. For example: