nix-super/doc/manual/src/command-ref/nix-instantiate.md

159 lines
4.2 KiB
Markdown
Raw Normal View History

2020-07-24 13:56:19 +03:00
# Name
2020-07-23 13:58:42 +03:00
2020-07-24 13:56:19 +03:00
`nix-instantiate` - instantiate store derivations from Nix expressions
2020-07-23 13:58:42 +03:00
2020-07-24 13:56:19 +03:00
# Synopsis
2020-07-23 13:58:42 +03:00
2020-07-24 13:56:19 +03:00
`nix-instantiate`
[`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
[`--read-write-mode`]
[`--arg` *name* *value*]
[{`--attr`| `-A`} *attrPath*]
[`--add-root` *path*]
[`--expr` | `-E`]
*files…*
2020-07-23 13:58:42 +03:00
2020-07-24 13:56:19 +03:00
`nix-instantiate` `--find-file` *files…*
2020-07-23 13:58:42 +03:00
# Description
The command `nix-instantiate` generates [store
2020-07-24 16:46:16 +03:00
derivations](../glossary.md) 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
2020-07-24 16:46:16 +03:00
derivation, a list of derivations, or a set of derivations. The paths
of the resulting store derivations are printed on standard output.
2020-07-23 13:58:42 +03:00
If *files* is the character `-`, then a Nix expression will be read from
2020-07-23 13:58:42 +03:00
standard input.
# Options
- `--add-root` *path*\
See the [corresponding option](nix-store.md) in `nix-store`.
2020-07-23 13:58:42 +03:00
- `--parse`\
2020-07-23 13:58:42 +03:00
Just parse the input files, and print their abstract syntax trees on
standard output in ATerm format.
- `--eval`\
2020-07-23 13:58:42 +03:00
Just parse and evaluate the input files, and print the resulting
values on standard output. No instantiation of store derivations
takes place.
- `--find-file`\
2020-07-23 13:58:42 +03:00
Look up the given files in Nixs 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`.
2020-07-23 13:58:42 +03:00
- `--strict`\
2020-07-23 13:58:42 +03:00
When used with `--eval`, recursively evaluate list elements and
attributes. Normally, such sub-expressions are left unevaluated
(since the Nix expression language is lazy).
2020-07-24 13:56:19 +03:00
2020-07-23 13:58:42 +03:00
> **Warning**
2020-07-24 13:56:19 +03:00
>
2020-07-23 13:58:42 +03:00
> This option can cause non-termination, because lazy data
> structures can be infinitely large.
- `--json`\
2020-07-23 13:58:42 +03:00
When used with `--eval`, print the resulting value as an JSON
representation of the abstract syntax tree rather than as an ATerm.
- `--xml`\
2020-07-23 13:58:42 +03:00
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`
2020-07-24 16:46:16 +03:00
built-in](../expressions/builtins.md).
2020-07-23 13:58:42 +03:00
- `--read-write-mode`\
2020-07-23 13:58:42 +03:00
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). If
this option is not enabled, there may be uninstantiated store paths
in the final output.
<!-- end list -->
# Examples
Instantiating store derivations from a Nix expression, and building them
using `nix-store`:
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate test.nix (instantiate)
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
2020-07-24 13:56:19 +03:00
2020-07-31 16:43:25 +03:00
$ nix-store -r $(nix-instantiate test.nix) (build)
...
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)
2020-07-24 13:56:19 +03:00
2020-07-31 16:43:25 +03:00
$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib
...
```
2020-07-23 13:58:42 +03:00
You can also give a Nix expression on the command line:
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate -E 'with import <nixpkgs> { }; hello'
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
```
2020-07-23 13:58:42 +03:00
This is equivalent to:
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate '<nixpkgs>' -A hello
```
2020-07-23 13:58:42 +03:00
Parsing and evaluating Nix expressions:
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate --parse -E '1 + 2'
1 + 2
```
2020-07-24 13:56:19 +03:00
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate --eval -E '1 + 2'
3
```
2020-07-24 13:56:19 +03:00
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate --eval --xml -E '1 + 2'
<?xml version='1.0' encoding='utf-8'?>
<expr>
<int value="3" />
</expr>
```
2020-07-23 13:58:42 +03:00
The difference between non-strict and strict evaluation:
2020-07-31 16:43:25 +03:00
```console
$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
...
<attr name="x">
<string value="foo" />
</attr>
<attr name="y">
<unevaluated />
</attr>
...
```
2020-07-23 13:58:42 +03:00
Note that `y` is left unevaluated (the XML representation doesnt
attempt to show non-normal forms).
2020-07-31 16:43:25 +03:00
```console
$ 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>
...
```