mirror of
https://github.com/NixOS/nix
synced 2025-06-27 04:21:16 +02:00
36b059748d
Documentation on "classic" commands with many sub-commands are notoriously hard to discover due to lack of overview and anchor links. Additionally the information on common options and environment variables is not accessible offline in man pages, and therefore often overlooked by readers. With this change, each sub-command of nix-store and nix-env gets its own page in the manual (listed in the table of contents), and each own man page. Also, man pages for each subcommand now (again) list common options and environment variables. While this makes each page quite long and some common parameters don't apply, this should still make it easier to navigate as that additional information was not accessible on the command line at all. It is now possible to run 'nix-store --<subcommand> --help` to display help pages for the given subcommand. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
160 lines
4.3 KiB
Markdown
160 lines
4.3 KiB
Markdown
# Name
|
||
|
||
`nix-instantiate` - instantiate store derivations from Nix expressions
|
||
|
||
# Synopsis
|
||
|
||
`nix-instantiate`
|
||
[`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
|
||
[`--read-write-mode`]
|
||
[`--arg` *name* *value*]
|
||
[{`--attr`| `-A`} *attrPath*]
|
||
[`--add-root` *path*]
|
||
[`--expr` | `-E`]
|
||
*files…*
|
||
|
||
`nix-instantiate` `--find-file` *files…*
|
||
|
||
# Description
|
||
|
||
The command `nix-instantiate` produces [store derivation]s 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.
|
||
|
||
[store derivation]: ../glossary.md#gloss-store-derivation
|
||
|
||
If *files* is the character `-`, then a Nix expression will be read from
|
||
standard input.
|
||
|
||
# Options
|
||
|
||
- `--add-root` *path*\
|
||
See the [corresponding option](nix-store.md) 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 language is lazy).
|
||
|
||
> **Warning**
|
||
>
|
||
> 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](../language/builtins.md).
|
||
|
||
- `--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). If
|
||
this option is not enabled, there may be uninstantiated store paths
|
||
in the final output.
|
||
|
||
{{#include ./opt-common.md}}
|
||
|
||
{{#include ./env-common.md}}
|
||
|
||
# Examples
|
||
|
||
Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`:
|
||
|
||
```console
|
||
$ 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:
|
||
|
||
```console
|
||
$ nix-instantiate -E 'with import <nixpkgs> { }; hello'
|
||
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
|
||
```
|
||
|
||
This is equivalent to:
|
||
|
||
```console
|
||
$ nix-instantiate '<nixpkgs>' -A hello
|
||
```
|
||
|
||
Parsing and evaluating Nix expressions:
|
||
|
||
```console
|
||
$ nix-instantiate --parse -E '1 + 2'
|
||
1 + 2
|
||
```
|
||
|
||
```console
|
||
$ nix-instantiate --eval -E '1 + 2'
|
||
3
|
||
```
|
||
|
||
```console
|
||
$ 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:
|
||
|
||
```console
|
||
$ 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).
|
||
|
||
```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>
|
||
...
|
||
```
|