NixOS · fricklerhandwerk · Nov 7, 2023 · Oct 31, 2023 · Oct 31, 2023 · Oct 31, 2023
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -61,7 +61,7 @@
 /pkgs/build-support/writers @lassulus @Profpatsch
 
 # Nixpkgs make-disk-image
-/doc/builders/images/makediskimage.section.md  @raitobezarius
+/doc/build-helpers/images/makediskimage.section.md  @raitobezarius
 /nixos/lib/make-disk-image.nix                 @raitobezarius
 
 # Nixpkgs documentation
@@ -219,7 +219,7 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
 /nixos/tests/knot.nix @mweinelt
 
 # Web servers
-/doc/builders/packages/nginx.section.md @raitobezarius
+/doc/packages/nginx.section.md @raitobezarius
 /pkgs/servers/http/nginx/ @raitobezarius
 /nixos/modules/services/web-servers/nginx/ @raitobezarius
 
@@ -272,7 +272,7 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
 # Docker tools
 /pkgs/build-support/docker                   @roberth
 /nixos/tests/docker-tools*                   @roberth
-/doc/builders/images/dockertools.section.md  @roberth
+/doc/build-helpers/images/dockertools.section.md  @roberth
 
 # Blockchains
 /pkgs/applications/blockchains  @mmahut @RaghavSood

diff --git a/doc/build-helpers.md 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 → doc/build-helpers/fetchers.chapter.md b/doc/builders/fetchers.chapter.md → doc/build-helpers/fetchers.chapter.md
diff --git a/doc/builders/images.md → doc/build-helpers/images.md b/doc/builders/images.md → doc/build-helpers/images.md
diff --git a/doc/builders/images/appimagetools.section.md → ...d-helpers/images/appimagetools.section.md b/doc/builders/images/appimagetools.section.md → ...d-helpers/images/appimagetools.section.md
diff --git a/doc/builders/images/binarycache.section.md → ...ild-helpers/images/binarycache.section.md b/doc/builders/images/binarycache.section.md → ...ild-helpers/images/binarycache.section.md
diff --git a/doc/builders/images/dockertools.section.md → ...ild-helpers/images/dockertools.section.md b/doc/builders/images/dockertools.section.md → ...ild-helpers/images/dockertools.section.md
diff --git a/doc/builders/images/makediskimage.section.md → ...d-helpers/images/makediskimage.section.md b/doc/builders/images/makediskimage.section.md → ...d-helpers/images/makediskimage.section.md
diff --git a/doc/builders/images/ocitools.section.md → doc/build-helpers/images/ocitools.section.md b/doc/builders/images/ocitools.section.md → doc/build-helpers/images/ocitools.section.md
diff --git a/...uilders/images/portableservice.section.md → ...helpers/images/portableservice.section.md b/...uilders/images/portableservice.section.md → ...helpers/images/portableservice.section.md
diff --git a/doc/builders/images/snaptools.section.md → ...build-helpers/images/snaptools.section.md b/doc/builders/images/snaptools.section.md → ...build-helpers/images/snaptools.section.md
diff --git a/doc/builders/special.md → doc/build-helpers/special.md b/doc/builders/special.md → 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/...lders/special/fhs-environments.section.md → ...lpers/special/fhs-environments.section.md b/...lders/special/fhs-environments.section.md → ...lpers/special/fhs-environments.section.md
diff --git a/...builders/special/makesetuphook.section.md → ...-helpers/special/makesetuphook.section.md b/...builders/special/makesetuphook.section.md → ...-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 → doc/build-helpers/special/mkshell.section.md b/doc/builders/special/mkshell.section.md → doc/build-helpers/special/mkshell.section.md
diff --git a/doc/builders/special/vm-tools.section.md → ...build-helpers/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md → ...build-helpers/special/vm-tools.section.md
diff --git a/doc/builders/testers.chapter.md → doc/build-helpers/testers.chapter.md b/doc/builders/testers.chapter.md → doc/build-helpers/testers.chapter.md
diff --git a/doc/builders/trivial-builders.chapter.md → ...-helpers/trivial-build-helpers.chapter.md b/doc/builders/trivial-builders.chapter.md → ...-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
diff --git 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/...uilders/packages/cataclysm-dda.section.md → doc/packages/cataclysm-dda.section.md b/...uilders/packages/cataclysm-dda.section.md → doc/packages/cataclysm-dda.section.md
diff --git a/doc/builders/packages/citrix.section.md → doc/packages/citrix.section.md b/doc/builders/packages/citrix.section.md → doc/packages/citrix.section.md
diff --git a/...uilders/special/darwin-builder.section.md → doc/packages/darwin-builder.section.md b/...uilders/special/darwin-builder.section.md → 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 → doc/packages/dlib.section.md b/doc/builders/packages/dlib.section.md → doc/packages/dlib.section.md
diff --git a/doc/builders/packages/eclipse.section.md → doc/packages/eclipse.section.md b/doc/builders/packages/eclipse.section.md → doc/packages/eclipse.section.md
diff --git a/doc/builders/packages/elm.section.md → doc/packages/elm.section.md b/doc/builders/packages/elm.section.md → doc/packages/elm.section.md
diff --git a/doc/builders/packages/emacs.section.md → doc/packages/emacs.section.md b/doc/builders/packages/emacs.section.md → doc/packages/emacs.section.md
diff --git a/doc/builders/packages/etc-files.section.md → doc/packages/etc-files.section.md b/doc/builders/packages/etc-files.section.md → doc/packages/etc-files.section.md
diff --git a/doc/builders/packages/firefox.section.md → doc/packages/firefox.section.md b/doc/builders/packages/firefox.section.md → doc/packages/firefox.section.md
diff --git a/doc/builders/packages/fish.section.md → doc/packages/fish.section.md b/doc/builders/packages/fish.section.md → doc/packages/fish.section.md
diff --git a/doc/builders/packages/fuse.section.md → doc/packages/fuse.section.md b/doc/builders/packages/fuse.section.md → doc/packages/fuse.section.md
diff --git a/doc/builders/packages/ibus.section.md → doc/packages/ibus.section.md b/doc/builders/packages/ibus.section.md → doc/packages/ibus.section.md
diff --git a/doc/builders/packages/index.md → doc/packages/index.md b/doc/builders/packages/index.md → 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 → doc/packages/kakoune.section.md b/doc/builders/packages/kakoune.section.md → doc/packages/kakoune.section.md
diff --git a/doc/builders/packages/linux.section.md → doc/packages/linux.section.md b/doc/builders/packages/linux.section.md → doc/packages/linux.section.md
diff --git a/doc/builders/packages/locales.section.md → doc/packages/locales.section.md b/doc/builders/packages/locales.section.md → doc/packages/locales.section.md
diff --git a/doc/builders/packages/nginx.section.md → doc/packages/nginx.section.md b/doc/builders/packages/nginx.section.md → doc/packages/nginx.section.md
diff --git a/doc/builders/packages/opengl.section.md → doc/packages/opengl.section.md b/doc/builders/packages/opengl.section.md → doc/packages/opengl.section.md
diff --git a/...uilders/packages/shell-helpers.section.md → doc/packages/shell-helpers.section.md b/...uilders/packages/shell-helpers.section.md → doc/packages/shell-helpers.section.md
diff --git a/doc/builders/packages/steam.section.md → doc/packages/steam.section.md b/doc/builders/packages/steam.section.md → doc/packages/steam.section.md
diff --git a/doc/builders/packages/urxvt.section.md → doc/packages/urxvt.section.md b/doc/builders/packages/urxvt.section.md → doc/packages/urxvt.section.md
diff --git a/doc/builders/packages/weechat.section.md → doc/packages/weechat.section.md b/doc/builders/packages/weechat.section.md → doc/packages/weechat.section.md
diff --git a/doc/builders/packages/xorg.section.md → doc/packages/xorg.section.md b/doc/builders/packages/xorg.section.md → doc/packages/xorg.section.md
diff --git 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:
-Original file line number
+Diff line change
@@ Expand Up @@
     ```
     :::
-    ### 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:
@@ Expand Down @@