You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata.
33
+
22
34
-[store derivation]{#gloss-store-derivation}
23
35
24
36
A single build task.
25
-
See [Store Derivation](@docroot@/store/drv.md#store-derivation) for details.
37
+
See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
26
38
27
39
[store derivation]: #gloss-store-derivation
28
40
29
41
-[derivation path]{#gloss-derivation-path}
30
42
31
43
A [store path] which uniquely identifies a [store derivation].
32
44
33
-
See [Referencing Store Derivations](@docroot@/store/drv.md#derivation-path) for details.
45
+
See [Referencing Store Derivations](@docroot@/store/derivation/index.md#derivation-path) for details.
34
46
35
47
Not to be confused with [deriving path].
36
48
@@ -88,6 +100,12 @@
88
100
89
101
[store]: #gloss-store
90
102
103
+
-[Nix instance]{#gloss-nix-instance}
104
+
<!-- ambiguous -->
105
+
1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
106
+
A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
107
+
2. A running Nix process, such as the `nix` command.
108
+
91
109
-[binary cache]{#gloss-binary-cache}
92
110
93
111
A *binary cache* is a Nix store which uses a different format: its
@@ -220,7 +238,7 @@
220
238
directly or indirectly “reachable” from that store path; that is,
221
239
it’s the closure of the path under the *references* relation. For
222
240
a package, the closure of its derivation is equivalent to the
223
-
build-time dependencies, while the closure of its output path is
241
+
build-time dependencies, while the closure of its [output path] is
224
242
equivalent to its runtime dependencies. For correct deployment it
225
243
is necessary to deploy whole closures, since otherwise at runtime
226
244
files could be missing. The command `nix-store --query --requisites ` prints out
@@ -252,7 +270,7 @@
252
270
253
271
Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
254
272
255
-
See [Deriving Path](./store/drv.md#deriving-path) for details.
273
+
See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
These attributes declare that the derivation is a so-called *fixed-output derivation* (FOD), which means that a cryptographic hash of the output is already known in advance.
124
-
125
-
As opposed to regular derivations, the [`builder`] executable of a fixed-output derivation has access to the network.
126
-
Nix computes a cryptographic hash of its output and compares that to the hash declared with these attributes.
127
-
If there is a mismatch, the derivation fails.
128
-
129
-
The rationale for fixed-output derivations is derivations such as
130
-
those produced by the `fetchurl` function. This function downloads a
131
-
file from a given URL. To ensure that the downloaded file has not
132
-
been modified, the caller must also specify a cryptographic hash of
If a `fetchurl` derivation was treated like a normal derivation, the
154
-
output paths of the derivation and *all derivations depending on it*
155
-
would change. For instance, if we were to change the URL of the
156
-
Glibc source distribution in Nixpkgs (a package on which almost all
157
-
other packages depend) massive rebuilds would be needed. This is
158
-
unfortunate for a change which we know cannot have a real effect as
159
-
it propagates upwards through the dependency graph.
160
-
161
-
For fixed-output derivations, on the other hand, the name of the
162
-
output path only depends on the `outputHash*` and `name` attributes,
163
-
while all other attributes are ignored for the purpose of computing
164
-
the output path. (The `name` attribute is included because it is
165
-
part of the path.)
166
-
167
-
As an example, here is the (simplified) Nix expression for
168
-
`fetchurl`:
169
-
170
-
```nix
171
-
{ stdenv, curl }: # The curl program is used for downloading.
172
-
173
-
{ url, sha256 }:
174
-
175
-
stdenv.mkDerivation {
176
-
name = baseNameOf (toString url);
177
-
builder = ./builder.sh;
178
-
buildInputs = [ curl ];
179
-
180
-
# This is a fixed-output derivation; the output must be a regular
181
-
# file with SHA256 hash sha256.
182
-
outputHashMode = "flat";
183
-
outputHashAlgo = "sha256";
184
-
outputHash = sha256;
185
-
186
-
inherit url;
187
-
}
188
-
```
189
-
190
-
The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
191
-
The "nix32" encoding is an adaptation of base-32 encoding.
192
-
The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings, and the [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
193
-
194
-
The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
195
-
It can currently be `"blake3", "sha1"`, `"sha256"`, `"sha512"`, or `null`.
196
-
`outputHashAlgo` can only be `null` when `outputHash` follows the SRI format.
197
-
198
-
The `outputHashMode` attribute determines how the hash is computed.
> For example, in [nix.conf](../command-ref/conf-file.md) you could add:
234
-
>
235
-
> ```
236
-
> extra-experimental-features = ca-derivations
237
-
> ```
238
-
239
-
If this attribute is set to `true`, then the derivation
240
-
outputs will be stored in a content-addressed location rather than the
241
-
traditional input-addressed one.
242
-
243
-
Setting this attribute also requires setting
244
-
[`outputHashMode`](#adv-attr-outputHashMode)
245
-
and
246
-
[`outputHashAlgo`](#adv-attr-outputHashAlgo)
247
-
like for *fixed-output derivations* (see above).
248
-
249
-
It also implicitly requires that the machine to build the derivation must have the `ca-derivations` [system feature](@docroot@/command-ref/conf-file.md#conf-system-features).
250
-
251
122
- [`passAsFile`]{#adv-attr-passAsFile}\
252
123
A list of names of attributes that should be passed via files rather
253
124
than environment variables. For example, if you have
@@ -370,6 +241,134 @@ Derivations can declare some infrequently used optional attributes.
370
241
371
242
ensures that the derivation can only be built on a machine with the `kvm` feature.
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.
247
+
The choice of the following attributes determines which kind of derivation we are making.
248
+
249
+
-[`__contentAddressed`]
250
+
251
+
-[`outputHash`]
252
+
253
+
-[`outputHashAlgo`]
254
+
255
+
-[`outputHashMode`]
256
+
257
+
The three types of derivations are chosen based on the following combinations of these attributes.
> This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
321
+
322
+
See [content-addressing store objects](@docroot@/store/store-object/content-address.md) for more information about the process this flag controls.
323
+
324
+
-[`outputHashAlgo`]{#adv-attr-outputHashAlgo}
325
+
326
+
This specifies the hash alorithm used to digest the [file system object] data of a content-addressing derivation output.
327
+
328
+
This works in conjunction with [`outputHashMode`](#adv-attr-outputHashAlgo).
329
+
Specifying one without the other is an error (unless [`outputHash` is also specified and includes its own hash algorithm as described below).
330
+
331
+
The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
332
+
It can currently be `"blake3"`, "sha1"`, `"sha256"`, `"sha512"`, or `null`.
333
+
334
+
`outputHashAlgo` can only be `null` when `outputHash` follows the SRI format, because in that case the choice of hash algorithm is determined by `outputHash`.
This will specify the output hash of the single output of a [fixed-output derivation].
339
+
340
+
The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
341
+
The "nix32" encoding is an adaptation of base-32 encoding.
342
+
343
+
> **Note**
344
+
>
345
+
> The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings.
346
+
> The [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
0 commit comments