Skip to content

Commit 637aa09

Browse files
Ericson2314Mic92
Ericson2314
and
Mic92
committed
Advanced attributes organize
This is supposed to firstly improve the docs as they are, and secondly hint at how the core conceptual information ought to be moved to the store derivation section of the manual. Co-authored-by: Jörg Thalheim <[email protected]>
1 parent 2c1447b commit 637aa09

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)