From 0b3464a107dab7aea00c3a9a0f91e240e6d8b851 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Na=C3=AFm=20Favier?= <n@monade.li>
Date: Mon, 30 Jan 2023 14:49:45 +0100
Subject: [PATCH] doc: add `__structuredAttrs`, `outputChecks`,
 `unsafeDiscardReferences`

---
 .../src/language/advanced-attributes.md       | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/doc/manual/src/language/advanced-attributes.md b/doc/manual/src/language/advanced-attributes.md
index f02425b134f..a164b39972b 100644
--- a/doc/manual/src/language/advanced-attributes.md
+++ b/doc/manual/src/language/advanced-attributes.md
@@ -255,3 +255,67 @@ Derivations can declare some infrequently used optional attributes.
     > substituted. Thus it is usually a good idea to align `system` with
     > `builtins.currentSystem` when setting `allowSubstitutes` to
     > `false`. For most trivial derivations this should be the case.
+
+  - [`__structuredAttrs`]{#adv-attr-structuredAttrs}\
+    If the special attribute `__structuredAttrs` is set to `true`, the other derivation
+    attributes are serialised in JSON format and made available to the
+    builder via the file `.attrs.json` in the builder’s temporary
+    directory. This obviates the need for `passAsFile` since JSON files
+    have no size restrictions, unlike process environments.
+
+    It also makes it possible to tweak derivation settings in a structured way; see
+    [`outputChecks`](#adv-attr-outputChecks) for example.
+
+    As a convenience to Bash builders,
+    Nix writes a script named `.attrs.sh` to the builder’s directory
+    that initialises shell variables corresponding to all attributes
+    that are representable in Bash. This includes non-nested
+    (associative) arrays. For example, the attribute `hardening.format = true`
+    ends up as the Bash associative array element `${hardening[format]}`.
+
+  - [`outputChecks`]{#adv-attr-outputChecks}\
+    When using [structured attributes](#adv-attr-structuredAttrs), the `outputChecks`
+    attribute allows defining checks per-output.
+
+    In addition to
+    [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
+    [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites),
+    the following attributes are available:
+
+    - `maxSize` defines the maximum size of the output path.
+    - `maxClosureSize` defines the maximum size of the output's closure.
+    - `ignoreSelfRefs` controls whether self-references should be considered when
+      checking for allowed references/requisites.
+
+    ```nix
+    __structuredAttrs = true;
+
+    outputChecks.out = {
+      # The closure of 'out' must not be larger than 256 MiB.
+      maxClosureSize = 256 * 1024 * 1024;
+
+      # It must not refer to the C compiler or to the 'dev' output.
+      disallowedRequisites = [ stdenv.cc "dev" ];
+    };
+
+    outputChecks.dev = {
+      # The 'dev' output must not be larger than 128 KiB.
+      maxSize = 128 * 1024;
+    };
+    ```
+
+  - [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
+    When using [structured attributes](#adv-attr-structuredAttrs), the **experimental**
+    attribute `unsafeDiscardReferences` is a per-output boolean which, if set to `true`,
+    disables scanning the build output for runtime dependencies altogether.
+
+    ```nix
+    __structuredAttrs = true;
+    unsafeDiscardReferences.out = true;
+    ```
+
+    This is useful, for example, when generating self-contained filesystem images with
+    their own embedded Nix store: hashes found inside such an image refer
+    to the embedded store and not to the host's Nix store.
+
+    This is only allowed if the `discard-references` experimental feature is enabled.