Merge pull request #7382 from fricklerhandwerk/doc-automatic-uid

move documentation on `auto-allocate-uids` to options docs

doc/manual/src/release-notes/rl-next.md

@@ -12,43 +12,37 @@
   ([#7260](https://github.com/NixOS/nix/pull/7260)).
 
 * Nix can now automatically pick UIDs for builds, removing the need to
-  create `nixbld*` user accounts. These UIDs are allocated starting at
+  create `nixbld*` user accounts.
-  872415232 (0x34000000) on Linux and 56930 on macOS.
 
-  This is an experimental feature. To enable it, add the following to
+  See [`auto-allocate-uids`].
-  `nix.conf`:
 
-  ```
+  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
-  extra-experimental-features = auto-allocate-uids
-  auto-allocate-uids = true
-  ```
 
 * On Linux, Nix can now run builds in a user namespace where the build
-  runs as root (UID 0) and has 65,536 UIDs available. This is
+  runs as root (UID 0) and has 65,536 UIDs available.
-  primarily useful for running containers such as `systemd-nspawn`
-  inside a Nix build. For an example, see
-  https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
 
-  A build can enable this by requiring the `uid-range` system feature,
+  <!-- FIXME: move this to its own section about system features -->
-  i.e. by setting the derivation attribute
+
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+
+  A build can enable this by by setting the derivation attribute:
 
   ```
   requiredSystemFeatures = [ "uid-range" ];
   ```
 
-  The `uid-range` system feature requires the `auto-allocate-uids`
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
-  setting to be enabled (see above).
+  setting to be enabled.
+
+  [system feature]: (../command-ref/conf-file.md#conf-system-features),
 
 * On Linux, Nix has experimental support for running builds inside a
-  cgroup. It can be enabled by adding
+  cgroup.
 
-  ```
+  See [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
-  extra-experimental-features = cgroups
-  use-cgroups = true
-  ```
-
-  to `nix.conf`. Cgroups are required for derivations that require the
-  `uid-range` system feature.
 
 * `nix build --json` now prints some statistics about top-level
   derivations, such as CPU statistics when cgroups are enabled.

src/libstore/globals.hh

@@ -284,7 +284,22 @@ public:
         )"};
 
     Setting<bool> autoAllocateUids{this, false, "auto-allocate-uids",
-        "Whether to allocate UIDs for builders automatically."};
+        R"(
+          Whether to select UIDs for builds automatically, instead of using the
+          users in `build-users-group`.
+
+          UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS.
+
+          > **Warning**
+          > This is an experimental feature.
+
+          To enable it, add the following to [`nix.conf`](#):
+
+          ```
+          extra-experimental-features = auto-allocate-uids
+          auto-allocate-uids = true
+          ```
+        )"};
 
     Setting<uint32_t> startId{this,
         #if __linux__
@@ -308,11 +323,22 @@ public:
     Setting<bool> useCgroups{
         this, false, "use-cgroups",
         R"(
-          Whether to execute builds inside cgroups. Cgroups are
+          Whether to execute builds inside cgroups.
-          enabled automatically for derivations that require the
+          This is only supported on Linux.
-          `uid-range` system feature.
+
-        )"
+          Cgroups are required and enabled automatically for derivations 
-    };
+          that require the `uid-range` system feature.
+
+          > **Warning**
+          > This is an experimental feature.
+
+          To enable it, add the following to [`nix.conf`](#):
+
+          ```
+          extra-experimental-features = cgroups
+          use-cgroups = true
+          ```
+        )"};
     #endif
 
     Setting<bool> impersonateLinux26{this, false, "impersonate-linux-26",