nix-instantiate
1
Nix

# nix-instantiate

instantiate store derivations from Nix expressions

        nix-instantiate

          --parse

            --eval
            --strict
            --json
            --xml

        --read-write-mode
        --arg name value

            --attr
            -A

          attrPath

        --add-root path
        --indirect

          --expr
          -E

        files

        nix-instantiate
        --find-file
        files

## Description

The command `nix-instantiate` generates store derivations from (high-level) Nix expressions. It evaluates the Nix expressions in each of files (which defaults to ./default.nix). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed on standard output.

If files is the character `-`, then a Nix expression will be read from standard input.

See also for a list of common options.

## Options

`--add-root` path
`--indirect`

  See the corresponding options in `nix-store`.

`--parse`

  Just parse the input files, and print their abstract syntax trees on standard output in ATerm format.

`--eval`

  Just parse and evaluate the input files, and print the resulting values on standard output. No instantiation of store derivations takes place.

`--find-file`

  Look up the given files in Nix’s search path (as specified by the `NIX_PATH` environment variable). If found, print the corresponding absolute paths on standard output. For instance, if `NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.

`--strict`

  When used with `--eval`, recursively evaluate list elements and attributes. Normally, such sub-expressions are left unevaluated (since the Nix expression language is lazy).

  This option can cause non-termination, because lazy data structures can be infinitely large.

`--json`

  When used with `--eval`, print the resulting value as an JSON representation of the abstract syntax tree rather than as an ATerm.

`--xml`

  When used with `--eval`, print the resulting value as an XML representation of the abstract syntax tree rather than as an ATerm. The schema is the same as that used by the `toXML` built-in.

`--read-write-mode`

  When used with `--eval`, perform evaluation in read/write mode so nix language features that require it will still work (at the cost of needing to do instantiation of every evaluated derivation).

## Examples

Instantiating store derivations from a Nix expression, and building them using `nix-store`:

    $ nix-instantiate test.nix (instantiate)
    /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv

    $ nix-store -r $(nix-instantiate test.nix) (build)
    ...
    /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)

    $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
    dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
    ...

You can also give a Nix expression on the command line:

    $ nix-instantiate -E 'with import <nixpkgs> { }; hello'
    /nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv

This is equivalent to:

    $ nix-instantiate '<nixpkgs>' -A hello

Parsing and evaluating Nix expressions:

    $ nix-instantiate --parse -E '1 + 2'
    1 + 2

    $ nix-instantiate --eval -E '1 + 2'
    3

    $ nix-instantiate --eval --xml -E '1 + 2'
    <?xml version='1.0' encoding='utf-8'?>
    <expr>
      <int value="3" />
    </expr>

The difference between non-strict and strict evaluation:

    $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
    ...
      <attr name="x">
        <string value="foo" />
      </attr>
      <attr name="y">
        <unevaluated />
      </attr>
    ...

Note that `y` is left unevaluated (the XML representation doesn’t attempt to show non-normal forms).

    $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
    ...
      <attr name="x">
        <string value="foo" />
      </attr>
      <attr name="y">
        <string value="foo" />
      </attr>
    ...

## Environment variables