manual: document derivation options in the store section - #16261
Merged
Conversation
Ericson2314
force-pushed
the
derivation-options-doc-to-store
branch
from
August 5, 2026 15:49
0d1f4c9 to
707d6a8
Compare
xokdvium
reviewed
Aug 5, 2026
xokdvium
reviewed
Aug 5, 2026
Comment on lines
+219
to
+220
| - [*additional sandbox profile*]{#additional-sandbox-profile}: | ||
| (Darwin only) Additional sandbox profile text, granting the build extra permissions inside the sandbox. |
Contributor
There was a problem hiding this comment.
Do we have any docs for the sandbox profile script or is just arcane nonsense that's not documented anywhere?
xokdvium
reviewed
Aug 5, 2026
xokdvium
reviewed
Aug 5, 2026
Ericson2314
force-pushed
the
derivation-options-doc-to-store
branch
from
August 5, 2026 21:12
7fe6c06 to
3ac8fd2
Compare
lisanna-dettwyler
approved these changes
Aug 5, 2026
Ericson2314
force-pushed
the
derivation-options-doc-to-store
branch
from
August 5, 2026 21:33
3ac8fd2 to
e799186
Compare
Ericson2314
enabled auto-merge
August 5, 2026 21:33
Ericson2314
disabled auto-merge
August 5, 2026 21:33
xokdvium
reviewed
Aug 5, 2026
Comment on lines
+94
to
+98
| - [*max size*]{#max-size}: | ||
| The size of the output's store object may not exceed the given number of bytes. | ||
|
|
||
| - [*max closure size*]{#max-closure-size}: | ||
| The total size of the output's closure may not exceed the given number of bytes. |
Contributor
There was a problem hiding this comment.
We can probably be more specific in that it's the length of the NAR serialisation.
Ericson2314
force-pushed
the
derivation-options-doc-to-store
branch
from
August 5, 2026 22:07
e799186 to
82bf944
Compare
xokdvium
approved these changes
Aug 5, 2026
The various derivation options ("advanced attributes") are concepts of
the store layer: they exist on the derivation itself, regardless of
which language front-end produced it. Document their *semantics* in the
store section of the manual: a new "Options" section for the
whole-derivation options, an "Output checks" section for the per-output
checks, and *pass as file* as part of the environment section.
The language "advanced attributes" page now documents just the
Nix-language syntax for setting each option via `builtins.derivation`,
with an example, linking to the store section for the concepts. All its
existing anchors are preserved.
Documenting the output size checks also required defining the sizes
they constrain. The *NAR size* and *closure NAR size* were referred to
in various places --- `nix path-info`, the store object info JSON
format, the narinfo format --- but only ever defined in passing in the
store object info JSON schema. Define them as store object metadata in
the store section, so the concrete formats can link up to the abstract
concept rather than being the sole source of truth for it.
Co-authored-by: Sergei Zimmerman <sergei@zimmerman.foo>
Ericson2314
enabled auto-merge
August 5, 2026 22:12
Ericson2314
force-pushed
the
derivation-options-doc-to-store
branch
from
August 5, 2026 22:24
82bf944 to
237fbce
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The various derivation options ("advanced attributes") are concepts of the store layer: they exist on the derivation itself, regardless of which language front-end produced it. Document their semantics in the store section of the manual: a new "Options" section for the whole-derivation options, an "Output checks" section for the per-output checks, and pass as file as part of the environment section.
The language "advanced attributes" page now documents just the Nix-language syntax for setting each option via
builtins.derivation, with an example, linking to the store section for the concepts. All its existing anchors are preserved.Context
Depends on #5538
Add 👍 to pull requests you find important.
The Nix maintainer team uses a GitHub project board to schedule and track reviews.