Skip to content

Commit af4c587

Browse files
Mic92Mic92
authored
Merge pull request #12596 from obsidiansystems/adv-attrs-organize
Advanced attributes organize
2 parents cba1a21 + 637aa09 commit af4c587

File tree

1 file changed

+113
-103
lines changed

1 file changed

+113
-103
lines changed

‎doc/manual/source/language/advanced-attributes.md‎

Lines changed: 113 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,7 @@
22

33
Derivations can declare some infrequently used optional attributes.
44

5-
- [`allowedReferences`]{#adv-attr-allowedReferences}\
6-
The optional attribute `allowedReferences` specifies a list of legal
7-
references (dependencies) of the output of the builder. For example,
8-
9-
```nix
10-
allowedReferences = [];
11-
```
12-
13-
enforces that the output of a derivation cannot have any runtime
14-
dependencies on its inputs. To allow an output to have a runtime
15-
dependency on itself, use `"out"` as a list item. This is used in
16-
NixOS to check that generated files such as initial ramdisks for
17-
booting Linux don’t have accidental dependencies on other paths in
18-
the Nix store.
19-
20-
- [`allowedRequisites`]{#adv-attr-allowedRequisites}\
21-
This attribute is similar to `allowedReferences`, but it specifies
22-
the legal requisites of the whole closure, so all the dependencies
23-
recursively. For example,
24-
25-
```nix
26-
allowedRequisites = [ foobar ];
27-
```
28-
29-
enforces that the output of a derivation cannot have any other
30-
runtime dependency than `foobar`, and in addition it enforces that
31-
`foobar` itself doesn't introduce any other dependency itself.
32-
33-
- [`disallowedReferences`]{#adv-attr-disallowedReferences}\
34-
The optional attribute `disallowedReferences` specifies a list of
35-
illegal references (dependencies) of the output of the builder. For
36-
example,
37-
38-
```nix
39-
disallowedReferences = [ foo ];
40-
```
41-
42-
enforces that the output of a derivation cannot have a direct
43-
runtime dependencies on the derivation `foo`.
44-
45-
- [`disallowedRequisites`]{#adv-attr-disallowedRequisites}\
46-
This attribute is similar to `disallowedReferences`, but it
47-
specifies illegal requisites for the whole closure, so all the
48-
dependencies recursively. For example,
49-
50-
```nix
51-
disallowedRequisites = [ foobar ];
52-
```
53-
54-
enforces that the output of a derivation cannot have any runtime
55-
dependency on `foobar` or any other derivation depending recursively
56-
on `foobar`.
5+
## Inputs
576

587
- [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
598
This attribute allows builders access to the references graph of
@@ -84,41 +33,6 @@ Derivations can declare some infrequently used optional attributes.
8433
with a Nix store containing the closure of a bootable NixOS
8534
configuration).
8635
87-
- [`impureEnvVars`]{#adv-attr-impureEnvVars}\
88-
This attribute allows you to specify a list of environment variables
89-
that should be passed from the environment of the calling user to
90-
the builder. Usually, the environment is cleared completely when the
91-
builder is executed, but with this attribute you can allow specific
92-
environment variables to be passed unmodified. For example,
93-
`fetchurl` in Nixpkgs has the line
94-
95-
```nix
96-
impureEnvVars = [ "http_proxy" "https_proxy" ... ];
97-
```
98-
99-
to make it use the proxy server configuration specified by the user
100-
in the environment variables `http_proxy` and friends.
101-
102-
This attribute is only allowed in [fixed-output derivations][fixed-output derivation],
103-
where impurities such as these are okay since (the hash
104-
of) the output is known in advance. It is ignored for all other
105-
derivations.
106-
107-
> **Warning**
108-
>
109-
> `impureEnvVars` implementation takes environment variables from
110-
> the current builder process. When a daemon is building its
111-
> environmental variables are used. Without the daemon, the
112-
> environmental variables come from the environment of the
113-
> `nix-build`.
114-
115-
If the [`configurable-impure-env` experimental
116-
feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
117-
is enabled, these environment variables can also be controlled
118-
through the
119-
[`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
120-
configuration setting.
121-
12236
- [`passAsFile`]{#adv-attr-passAsFile}\
12337
A list of names of attributes that should be passed via files rather
12438
than environment variables. For example, if you have
@@ -137,22 +51,6 @@ Derivations can declare some infrequently used optional attributes.
13751
builder, since most operating systems impose a limit on the size
13852
of the environment (typically, a few hundred kilobyte).
13953
140-
- [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
141-
If this attribute is set to `true` and [distributed building is enabled](@docroot@/command-ref/conf-file.md#conf-builders), then, if possible, the derivation will be built locally instead of being forwarded to a remote machine.
142-
This is useful for derivations that are cheapest to build locally.
143-
144-
- [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
145-
If this attribute is set to `false`, then Nix will always build this derivation (locally or remotely); it will not try to substitute its outputs.
146-
This is useful for derivations that are cheaper to build than to substitute.
147-
148-
This attribute can be ignored by setting [`always-allow-substitutes`](@docroot@/command-ref/conf-file.md#conf-always-allow-substitutes) to `true`.
149-
150-
> **Note**
151-
>
152-
> If set to `false`, the [`builder`] should be able to run on the system type specified in the [`system` attribute](./derivations.md#attr-system), since the derivation cannot be substituted.
153-
154-
[`builder`]: ./derivations.md#attr-builder
155-
15654
- [`__structuredAttrs`]{#adv-attr-structuredAttrs}\
15755
If the special attribute `__structuredAttrs` is set to `true`, the other derivation
15856
attributes are serialised into a file in JSON format. The environment variable
@@ -179,6 +77,61 @@ Derivations can declare some infrequently used optional attributes.
17977
[`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites), maxSize, and maxClosureSize.
18078
will have no effect.
18179
80+
## Output checks
81+
82+
- [`allowedReferences`]{#adv-attr-allowedReferences}\
83+
The optional attribute `allowedReferences` specifies a list of legal
84+
references (dependencies) of the output of the builder. For example,
85+
86+
```nix
87+
allowedReferences = [];
88+
```
89+
90+
enforces that the output of a derivation cannot have any runtime
91+
dependencies on its inputs. To allow an output to have a runtime
92+
dependency on itself, use `"out"` as a list item. This is used in
93+
NixOS to check that generated files such as initial ramdisks for
94+
booting Linux don’t have accidental dependencies on other paths in
95+
the Nix store.
96+
97+
- [`allowedRequisites`]{#adv-attr-allowedRequisites}\
98+
This attribute is similar to `allowedReferences`, but it specifies
99+
the legal requisites of the whole closure, so all the dependencies
100+
recursively. For example,
101+
102+
```nix
103+
allowedRequisites = [ foobar ];
104+
```
105+
106+
enforces that the output of a derivation cannot have any other
107+
runtime dependency than `foobar`, and in addition it enforces that
108+
`foobar` itself doesn't introduce any other dependency itself.
109+
110+
- [`disallowedReferences`]{#adv-attr-disallowedReferences}\
111+
The optional attribute `disallowedReferences` specifies a list of
112+
illegal references (dependencies) of the output of the builder. For
113+
example,
114+
115+
```nix
116+
disallowedReferences = [ foo ];
117+
```
118+
119+
enforces that the output of a derivation cannot have a direct
120+
runtime dependencies on the derivation `foo`.
121+
122+
- [`disallowedRequisites`]{#adv-attr-disallowedRequisites}\
123+
This attribute is similar to `disallowedReferences`, but it
124+
specifies illegal requisites for the whole closure, so all the
125+
dependencies recursively. For example,
126+
127+
```nix
128+
disallowedRequisites = [ foobar ];
129+
```
130+
131+
enforces that the output of a derivation cannot have any runtime
132+
dependency on `foobar` or any other derivation depending recursively
133+
on `foobar`.
134+
182135
- [`outputChecks`]{#adv-attr-outputChecks}\
183136
When using [structured attributes](#adv-attr-structuredAttrs), the `outputChecks`
184137
attribute allows defining checks per-output.
@@ -212,6 +165,8 @@ Derivations can declare some infrequently used optional attributes.
212165
};
213166
```
214167
168+
## Other output modifications
169+
215170
- [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
216171
217172
When using [structured attributes](#adv-attr-structuredAttrs), the
@@ -229,6 +184,24 @@ Derivations can declare some infrequently used optional attributes.
229184
their own embedded Nix store: hashes found inside such an image refer
230185
to the embedded store and not to the host's Nix store.
231186
187+
## Build scheduling
188+
189+
- [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
190+
If this attribute is set to `true` and [distributed building is enabled](@docroot@/command-ref/conf-file.md#conf-builders), then, if possible, the derivation will be built locally instead of being forwarded to a remote machine.
191+
This is useful for derivations that are cheapest to build locally.
192+
193+
- [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
194+
If this attribute is set to `false`, then Nix will always build this derivation (locally or remotely); it will not try to substitute its outputs.
195+
This is useful for derivations that are cheaper to build than to substitute.
196+
197+
This attribute can be ignored by setting [`always-allow-substitutes`](@docroot@/command-ref/conf-file.md#conf-always-allow-substitutes) to `true`.
198+
199+
> **Note**
200+
>
201+
> If set to `false`, the [`builder`] should be able to run on the system type specified in the [`system` attribute](./derivations.md#attr-system), since the derivation cannot be substituted.
202+
203+
[`builder`]: ./derivations.md#attr-builder
204+
232205
- [`requiredSystemFeatures`]{#adv-attr-requiredSystemFeatures}\
233206
234207
If a derivation has the `requiredSystemFeatures` attribute, then Nix will only build it on a machine that has the corresponding features set in its [`system-features` configuration](@docroot@/command-ref/conf-file.md#conf-system-features).
@@ -241,6 +214,43 @@ Derivations can declare some infrequently used optional attributes.
241214

242215
ensures that the derivation can only be built on a machine with the `kvm` feature.
243216

217+
# Impure builder configuration
218+
219+
- [`impureEnvVars`]{#adv-attr-impureEnvVars}\
220+
This attribute allows you to specify a list of environment variables
221+
that should be passed from the environment of the calling user to
222+
the builder. Usually, the environment is cleared completely when the
223+
builder is executed, but with this attribute you can allow specific
224+
environment variables to be passed unmodified. For example,
225+
`fetchurl` in Nixpkgs has the line
226+
227+
```nix
228+
impureEnvVars = [ "http_proxy" "https_proxy" ... ];
229+
```
230+
231+
to make it use the proxy server configuration specified by the user
232+
in the environment variables `http_proxy` and friends.
233+
234+
This attribute is only allowed in [fixed-output derivations][fixed-output derivation],
235+
where impurities such as these are okay since (the hash
236+
of) the output is known in advance. It is ignored for all other
237+
derivations.
238+
239+
> **Warning**
240+
>
241+
> `impureEnvVars` implementation takes environment variables from
242+
> the current builder process. When a daemon is building its
243+
> environmental variables are used. Without the daemon, the
244+
> environmental variables come from the environment of the
245+
> `nix-build`.
246+
247+
If the [`configurable-impure-env` experimental
248+
feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
249+
is enabled, these environment variables can also be controlled
250+
through the
251+
[`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
252+
configuration setting.
253+
244254
## Setting the derivation type
245255
246256
As discussed in [Derivation Outputs and Types of Derivations](@docroot@/store/derivation/outputs/index.md), there are multiples kinds of derivations / kinds of derivation outputs.

0 commit comments

Comments
 (0)