aboutsummaryrefslogtreecommitdiff
path: root/doc/manual/src/expressions/advanced-attributes.md
diff options
context:
space:
mode:
authorregnat <rg@regnat.ovh>2021-04-23 14:30:42 +0200
committerregnat <rg@regnat.ovh>2021-04-23 14:37:21 +0200
commit31313d1401ffe387e69b84c62ba8798bf23a8914 (patch)
treee5c76e44d9d0dffaf972e56c879cb5779a154823 /doc/manual/src/expressions/advanced-attributes.md
parent293220bed5a75efc963e33c183787e87e55e28d9 (diff)
Replace the trailing markdown spaces by a backslash
They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
Diffstat (limited to 'doc/manual/src/expressions/advanced-attributes.md')
-rw-r--r--doc/manual/src/expressions/advanced-attributes.md92
1 files changed, 46 insertions, 46 deletions
diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md
index 31ebadda1..8a30c42a0 100644
--- a/doc/manual/src/expressions/advanced-attributes.md
+++ b/doc/manual/src/expressions/advanced-attributes.md
@@ -2,14 +2,14 @@
Derivations can declare some infrequently used optional attributes.
- - `allowedReferences`
+ - `allowedReferences`\
The optional attribute `allowedReferences` specifies a list of legal
references (dependencies) of the output of the builder. For example,
-
+
```nix
allowedReferences = [];
```
-
+
enforces that the output of a derivation cannot have any runtime
dependencies on its inputs. To allow an output to have a runtime
dependency on itself, use `"out"` as a list item. This is used in
@@ -17,45 +17,45 @@ Derivations can declare some infrequently used optional attributes.
booting Linux don’t have accidental dependencies on other paths in
the Nix store.
- - `allowedRequisites`
+ - `allowedRequisites`\
This attribute is similar to `allowedReferences`, but it specifies
the legal requisites of the whole closure, so all the dependencies
recursively. For example,
-
+
```nix
allowedRequisites = [ foobar ];
```
-
+
enforces that the output of a derivation cannot have any other
runtime dependency than `foobar`, and in addition it enforces that
`foobar` itself doesn't introduce any other dependency itself.
- - `disallowedReferences`
+ - `disallowedReferences`\
The optional attribute `disallowedReferences` specifies a list of
illegal references (dependencies) of the output of the builder. For
example,
-
+
```nix
disallowedReferences = [ foo ];
```
-
+
enforces that the output of a derivation cannot have a direct
runtime dependencies on the derivation `foo`.
- - `disallowedRequisites`
+ - `disallowedRequisites`\
This attribute is similar to `disallowedReferences`, but it
specifies illegal requisites for the whole closure, so all the
dependencies recursively. For example,
-
+
```nix
disallowedRequisites = [ foobar ];
```
-
+
enforces that the output of a derivation cannot have any runtime
dependency on `foobar` or any other derivation depending recursively
on `foobar`.
- - `exportReferencesGraph`
+ - `exportReferencesGraph`\
This attribute allows builders access to the references graph of
their inputs. The attribute is a list of inputs in the Nix store
whose references graph the builder needs to know. The value of
@@ -65,17 +65,17 @@ Derivations can declare some infrequently used optional attributes.
files have the format used by `nix-store --register-validity`
(with the deriver fields left empty). For example, when the
following derivation is built:
-
+
```nix
derivation {
...
exportReferencesGraph = [ "libfoo-graph" libfoo ];
};
```
-
+
the references graph of `libfoo` is placed in the file
`libfoo-graph` in the temporary build directory.
-
+
`exportReferencesGraph` is useful for builders that want to do
something with the closure of a store path. Examples include the
builders in NixOS that generate the initial ramdisk for booting
@@ -84,66 +84,66 @@ Derivations can declare some infrequently used optional attributes.
with a Nix store containing the closure of a bootable NixOS
configuration).
- - `impureEnvVars`
+ - `impureEnvVars`\
This attribute allows you to specify a list of environment variables
that should be passed from the environment of the calling user to
the builder. Usually, the environment is cleared completely when the
builder is executed, but with this attribute you can allow specific
environment variables to be passed unmodified. For example,
`fetchurl` in Nixpkgs has the line
-
+
```nix
impureEnvVars = [ "http_proxy" "https_proxy" ... ];
```
-
+
to make it use the proxy server configuration specified by the user
in the environment variables `http_proxy` and friends.
-
+
This attribute is only allowed in *fixed-output derivations* (see
below), where impurities such as these are okay since (the hash
of) the output is known in advance. It is ignored for all other
derivations.
-
+
> **Warning**
- >
+ >
> `impureEnvVars` implementation takes environment variables from
> the current builder process. When a daemon is building its
> environmental variables are used. Without the daemon, the
> environmental variables come from the environment of the
> `nix-build`.
- - `outputHash`; `outputHashAlgo`; `outputHashMode`
+ - `outputHash`; `outputHashAlgo`; `outputHashMode`\
These attributes declare that the derivation is a so-called
*fixed-output derivation*, which means that a cryptographic hash of
the output is already known in advance. When the build of a
fixed-output derivation finishes, Nix computes the cryptographic
hash of the output and compares it to the hash declared with these
attributes. If there is a mismatch, the build fails.
-
+
The rationale for fixed-output derivations is derivations such as
those produced by the `fetchurl` function. This function downloads a
file from a given URL. To ensure that the downloaded file has not
been modified, the caller must also specify a cryptographic hash of
the file. For example,
-
+
```nix
fetchurl {
url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
```
-
+
It sometimes happens that the URL of the file changes, e.g., because
servers are reorganised or no longer available. We then must update
the call to `fetchurl`, e.g.,
-
+
```nix
fetchurl {
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
```
-
+
If a `fetchurl` derivation was treated like a normal derivation, the
output paths of the derivation and *all derivations depending on it*
would change. For instance, if we were to change the URL of the
@@ -151,16 +151,16 @@ Derivations can declare some infrequently used optional attributes.
other packages depend) massive rebuilds would be needed. This is
unfortunate for a change which we know cannot have a real effect as
it propagates upwards through the dependency graph.
-
+
For fixed-output derivations, on the other hand, the name of the
output path only depends on the `outputHash*` and `name` attributes,
while all other attributes are ignored for the purpose of computing
the output path. (The `name` attribute is included because it is
part of the path.)
-
+
As an example, here is the (simplified) Nix expression for
`fetchurl`:
-
+
```nix
{ stdenv, curl }: # The curl program is used for downloading.
@@ -180,43 +180,43 @@ Derivations can declare some infrequently used optional attributes.
inherit url;
}
```
-
+
The `outputHashAlgo` attribute specifies the hash algorithm used to
compute the hash. It can currently be `"sha1"`, `"sha256"` or
`"sha512"`.
-
+
The `outputHashMode` attribute determines how the hash is computed.
It must be one of the following two values:
-
- - `"flat"`
+
+ - `"flat"`\
The output must be a non-executable regular file. If it isn’t,
the build fails. The hash is simply computed over the contents
of that file (so it’s equal to what Unix commands like
`sha256sum` or `sha1sum` produce).
-
+
This is the default.
-
- - `"recursive"`
+
+ - `"recursive"`\
The hash is computed over the NAR archive dump of the output
(i.e., the result of [`nix-store
--dump`](../command-ref/nix-store.md#operation---dump)). In
this case, the output can be anything, including a directory
tree.
-
+
The `outputHash` attribute, finally, must be a string containing
the hash in either hexadecimal or base-32 notation. (See the
[`nix-hash` command](../command-ref/nix-hash.md) for information
about converting to and from base-32 notation.)
- - `passAsFile`
+ - `passAsFile`\
A list of names of attributes that should be passed via files rather
than environment variables. For example, if you have
-
+
```nix
passAsFile = ["big"];
big = "a very long string";
```
-
+
then when the builder runs, the environment variable `bigPath`
will contain the absolute path to a temporary file containing `a
very long string`. That is, for any attribute *x* listed in
@@ -226,7 +226,7 @@ Derivations can declare some infrequently used optional attributes.
builder, since most operating systems impose a limit on the size
of the environment (typically, a few hundred kilobyte).
- - `preferLocalBuild`
+ - `preferLocalBuild`\
If this attribute is set to `true` and [distributed building is
enabled](../advanced-topics/distributed-builds.md), then, if
possible, the derivaton will be built locally instead of forwarded
@@ -234,14 +234,14 @@ Derivations can declare some infrequently used optional attributes.
where the cost of doing a download or remote build would exceed
the cost of building locally.
- - `allowSubstitutes`
+ - `allowSubstitutes`\
If this attribute is set to `false`, then Nix will always build this
derivation; it will not try to substitute its outputs. This is
useful for very trivial derivations (such as `writeText` in Nixpkgs)
that are cheaper to build than to substitute from a binary cache.
-
+
> **Note**
- >
+ >
> You need to have a builder configured which satisfies the
> derivation’s `system` attribute, since the derivation cannot be
> substituted. Thus it is usually a good idea to align `system` with