make separate section for builder execution

doc/manual/src/language/derivations.md

@@ -93,69 +93,71 @@ wrapper around `derivation` that adds a default value for `system` and
 always uses Bash as the builder, to which the supplied builder is passed
 as a command-line argument. See the Nixpkgs manual for details.
 
-The builder is executed as follows:
-
-  - A temporary directory is created under the directory specified by
-    `TMPDIR` (default `/tmp`) where the build will take place. The
-    current directory is changed to this directory.
-
-  - The environment is cleared and set to the derivation attributes, as
-    specified above.
-
-  - In addition, the following variables are set:
-    
-      - `NIX_BUILD_TOP` contains the path of the temporary directory for
-        this build.
-    
-      - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
-        temporary directory. This is to prevent the builder from
-        accidentally writing temporary files anywhere else. Doing so
-        might cause interference by other processes.
-    
-      - `PATH` is set to `/path-not-set` to prevent shells from
-        initialising it to their built-in default value.
-    
-      - `HOME` is set to `/homeless-shelter` to prevent programs from
-        using `/etc/passwd` or the like to find the user's home
-        directory, which could cause impurity. Usually, when `HOME` is
-        set, it is used as the location of the home directory, even if
-        it points to a non-existent path.
-    
-      - `NIX_STORE` is set to the path of the top-level Nix store
-        directory (typically, `/nix/store`).
-    
-      - For each output declared in `outputs`, the corresponding
-        environment variable is set to point to the intended path in the
-        Nix store for that output. Each output path is a concatenation
-        of the cryptographic hash of all build inputs, the `name`
-        attribute and the output name. (The output name is omitted if
-        it’s `out`.)
-
-  - If an output path already exists, it is removed. Also, locks are
-    acquired to prevent multiple Nix instances from performing the same
-    build at the same time.
-
-  - A log of the combined standard output and error is written to
-    `/nix/var/log/nix`.
-
-  - The builder is executed with the arguments specified by the
-    attribute `args`. If it exits with exit code 0, it is considered to
-    have succeeded.
-
-  - The temporary directory is removed (unless the `-K` option was
-    specified).
-
-  - If the build was successful, Nix scans each output path for
-    references to input paths by looking for the hash parts of the input
-    paths. Since these are potential runtime dependencies, Nix registers
-    them as dependencies of the output paths.
-
-  - After the build, Nix sets the last-modified timestamp on all files
-    in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
-    the default group, and sets the mode of the file to 0444 or 0555
-    (i.e., read-only, with execute permission enabled if the file was
-    originally executable). Note that possible `setuid` and `setgid`
-    bits are cleared. Setuid and setgid programs are not currently
-    supported by Nix. This is because the Nix archives used in
-    deployment have no concept of ownership information, and because it
-    makes the build result dependent on the user performing the build.
+## Builder execution
+
+The [`builder`](#attr-builder) is executed as follows:
+
+- A temporary directory is created under the directory specified by
+  `TMPDIR` (default `/tmp`) where the build will take place. The
+  current directory is changed to this directory.
+
+- The environment is cleared and set to the derivation attributes, as
+  specified above.
+
+- In addition, the following variables are set:
+
+  - `NIX_BUILD_TOP` contains the path of the temporary directory for
+    this build.
+
+  - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
+    temporary directory. This is to prevent the builder from
+    accidentally writing temporary files anywhere else. Doing so
+    might cause interference by other processes.
+
+  - `PATH` is set to `/path-not-set` to prevent shells from
+    initialising it to their built-in default value.
+
+  - `HOME` is set to `/homeless-shelter` to prevent programs from
+    using `/etc/passwd` or the like to find the user's home
+    directory, which could cause impurity. Usually, when `HOME` is
+    set, it is used as the location of the home directory, even if
+    it points to a non-existent path.
+
+  - `NIX_STORE` is set to the path of the top-level Nix store
+    directory (typically, `/nix/store`).
+
+  - For each output declared in `outputs`, the corresponding
+    environment variable is set to point to the intended path in the
+    Nix store for that output. Each output path is a concatenation
+    of the cryptographic hash of all build inputs, the `name`
+    attribute and the output name. (The output name is omitted if
+    it’s `out`.)
+
+- If an output path already exists, it is removed. Also, locks are
+  acquired to prevent multiple Nix instances from performing the same
+  build at the same time.
+
+- A log of the combined standard output and error is written to
+  `/nix/var/log/nix`.
+
+- The builder is executed with the arguments specified by the
+  attribute `args`. If it exits with exit code 0, it is considered to
+  have succeeded.
+
+- The temporary directory is removed (unless the `-K` option was
+  specified).
+
+- If the build was successful, Nix scans each output path for
+  references to input paths by looking for the hash parts of the input
+  paths. Since these are potential runtime dependencies, Nix registers
+  them as dependencies of the output paths.
+
+- After the build, Nix sets the last-modified timestamp on all files
+  in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
+  the default group, and sets the mode of the file to 0444 or 0555
+  (i.e., read-only, with execute permission enabled if the file was
+  originally executable). Note that possible `setuid` and `setgid`
+  bits are cleared. Setuid and setgid programs are not currently
+  supported by Nix. This is because the Nix archives used in
+  deployment have no concept of ownership information, and because it
+  makes the build result dependent on the user performing the build.