Merge pull request #262648 from ShamrockLee/doc-builder

Documentation for the builders (renamed: build helpers)

.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

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
+```

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
 ```

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}
 

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.
 

doc/builders.md

@@ -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
-```

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
 ```

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.

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

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: