diff options
Diffstat (limited to 'doc/manual/src/expressions/advanced-attributes.md')
| -rw-r--r-- | doc/manual/src/expressions/advanced-attributes.md | 257 |
1 files changed, 0 insertions, 257 deletions
diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md deleted file mode 100644 index 000595815..000000000 --- a/doc/manual/src/expressions/advanced-attributes.md +++ /dev/null @@ -1,257 +0,0 @@ -# Advanced Attributes - -Derivations can declare some infrequently used optional attributes. - - - `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 - NixOS to check that generated files such as initial ramdisks for - booting Linux don’t have accidental dependencies on other paths in - the Nix store. - - - `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`\ - 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`\ - 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`\ - 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 - this attribute should be a list of pairs `[ name1 path1 name2 - path2 ... ]`. The references graph of each *pathN* will be stored - in a text file *nameN* in the temporary build directory. The text - 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 - Linux (a `cpio` archive containing the closure of the boot script) - and the ISO-9660 image for the installation CD (which is populated - with a Nix store containing the closure of a bootable NixOS - configuration). - - - `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`\ - 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 - Glibc source distribution in Nixpkgs (a package on which almost all - 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. - - { url, sha256 }: - - stdenv.mkDerivation { - name = baseNameOf (toString url); - builder = ./builder.sh; - buildInputs = [ curl ]; - - # This is a fixed-output derivation; the output must be a regular - # file with SHA256 hash sha256. - outputHashMode = "flat"; - outputHashAlgo = "sha256"; - outputHash = sha256; - - 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"`\ - 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"`\ - 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.) - - - `__contentAddressed` - If this **experimental** attribute is set to true, then the derivation - outputs will be stored in a content-addressed location rather than the - traditional input-addressed one. - This only has an effect if the `ca-derivation` experimental feature is enabled. - - Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above). - - - `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 - `passAsFile`, Nix will pass an environment variable `xPath` - holding the path of the file containing the value of attribute - *x*. This is useful when you need to pass large strings to a - builder, since most operating systems impose a limit on the size - of the environment (typically, a few hundred kilobyte). - - - `preferLocalBuild`\ - If this attribute is set to `true` and [distributed building is - enabled](../advanced-topics/distributed-builds.md), then, if - possible, the derivation will be built locally instead of forwarded - to a remote machine. This is appropriate for trivial builders - where the cost of doing a download or remote build would exceed - the cost of building locally. - - - `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 - > `builtins.currentSystem` when setting `allowSubstitutes` to - > `false`. For most trivial derivations this should be the case. |