Better document build failure exit codes

- Improved API docs from comment

- Exit codes are for `nix-build`, not just `nix-store --release`

- Make note in tests so the magic numbers are not surprising

Picking up where #8387 left off.

doc/manual/src/command-ref/nix-build.md

@@ -70,6 +70,8 @@ except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](n
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 
+{{#include ./status-build-failure.md}}
+
 {{#include ./opt-common.md}}
 
 {{#include ./env-common.md}}

doc/manual/src/command-ref/nix-store/realise.md

@@ -54,36 +54,7 @@ The following flags are available:
     previous build, the new output path is left in
     `/nix/store/name.check.`
 
-Special exit codes:
-
-  - `100`\
-    Generic build failure, the builder process returned with a non-zero
-    exit code.
-
-  - `101`\
-    Build timeout, the build was aborted because it did not complete
-    within the specified `timeout`.
-
-  - `102`\
-    Hash mismatch, the build output was rejected because it does not
-    match the [`outputHash` attribute of the
-    derivation](@docroot@/language/advanced-attributes.md).
-
-  - `104`\
-    Not deterministic, the build succeeded in check mode but the
-    resulting output is not binary reproducible.
-
-With the `--keep-going` flag it's possible for multiple failures to
-occur, in this case the 1xx status codes are or combined using binary
-or.
-
-    1100100
-       ^^^^
-       |||`- timeout
-       ||`-- output hash mismatch
-       |`--- build failure
-       `---- not deterministic
-
+{{#include ../status-build-failure.md}}
 
 {{#include ./opt-common.md}}
 

doc/manual/src/command-ref/status-build-failure.md

@@ -0,0 +1,34 @@
+# Special exit codes for build failure
+
+1xx status codes are used when requested builds failed.
+The following codes are in use:
+
+- `100` Generic build failure
+
+  The builder process returned with a non-zero exit code.
+
+- `101` Build timeout
+
+  The build was aborted because it did not complete within the specified `timeout`.
+
+- `102` Hash mismatch
+
+  The build output was rejected because it does not match the
+  [`outputHash` attribute of the derivation](@docroot@/language/advanced-attributes.md).
+
+- `104` Not deterministic
+
+  The build succeeded in check mode but the resulting output is not binary reproducible.
+
+With the `--keep-going` flag it's possible for multiple failures to occur.
+In this case the 1xx status codes are or combined using
+[bitwise OR](https://en.wikipedia.org/wiki/Bitwise_operation#OR).
+
+```
+0b1100100
+     ^^^^
+     |||`- timeout
+     ||`-- output hash mismatch
+     |`--- build failure
+     `---- not deterministic
+```