nix-super/doc/manual/src/expressions/advanced-attributes.md

# 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,
    
        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,
    
        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,
    
        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,
    
        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:
    
        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
    
        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](#fixed-output-drvs), 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,
    
        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.,
    
        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`:
    
        { 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`](#refsec-nix-store-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](#sec-nix-hash) for information about converting to and from
    base-32 notation.)

  - `passAsFile`  
    A list of names of attributes that should be passed via files rather
    than environment variables. For example, if you have
    
    ``` 
    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](#chap-distributed-builds), then, if possible, the derivaton
    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.