forked from lix-project/lix
60da5d2b8f
The second command variant is now its own cmdsynopsis, which ensures it's not indented as was the case using sbrk.
264 lines
7.8 KiB
XML
264 lines
7.8 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
version="5.0"
|
||
xml:id="sec-nix-instantiate">
|
||
|
||
<refmeta>
|
||
<refentrytitle>nix-instantiate</refentrytitle>
|
||
<manvolnum>1</manvolnum>
|
||
<refmiscinfo class="source">Nix</refmiscinfo>
|
||
<refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>nix-instantiate</refname>
|
||
<refpurpose>instantiate store derivations from Nix expressions</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<cmdsynopsis>
|
||
<command>nix-instantiate</command>
|
||
<group>
|
||
<arg choice='plain'><option>--parse</option></arg>
|
||
<arg choice='plain'>
|
||
<option>--eval</option>
|
||
<arg><option>--strict</option></arg>
|
||
<arg><option>--xml</option></arg>
|
||
</arg>
|
||
</group>
|
||
<arg><option>--read-write-mode</option></arg>
|
||
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
|
||
<arg>
|
||
<group choice='req'>
|
||
<arg choice='plain'><option>--attr</option></arg>
|
||
<arg choice='plain'><option>-A</option></arg>
|
||
</group>
|
||
<replaceable>attrPath</replaceable>
|
||
</arg>
|
||
<arg><option>--add-root</option> <replaceable>path</replaceable></arg>
|
||
<arg><option>--indirect</option></arg>
|
||
<group choice='req'>
|
||
<arg choice='plain'><option>--expr</option></arg>
|
||
<arg choice='plain'><option>-E</option></arg>
|
||
</group>
|
||
<arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
|
||
</cmdsynopsis>
|
||
<cmdsynopsis>
|
||
<command>nix-instantiate</command>
|
||
<arg choice='plain'><option>--find-file</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsynopsisdiv>
|
||
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The command <command>nix-instantiate</command> generates <link
|
||
linkend="gloss-derivation">store derivations</link> from (high-level)
|
||
Nix expressions. It evaluates the Nix expressions in each of
|
||
<replaceable>files</replaceable> (which defaults to
|
||
<replaceable>./default.nix</replaceable>). 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.</para>
|
||
|
||
<para>If <replaceable>files</replaceable> is the character
|
||
<literal>-</literal>, then a Nix expression will be read from standard
|
||
input.</para>
|
||
|
||
<para condition="manual">See also <xref linkend="sec-common-options"
|
||
/> for a list of common options.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Options</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry>
|
||
<term><option>--add-root</option> <replaceable>path</replaceable></term>
|
||
<term><option>--indirect</option></term>
|
||
|
||
<listitem><para>See the <link linkend="opt-add-root">corresponding
|
||
options</link> in <command>nix-store</command>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--parse</option></term>
|
||
|
||
<listitem><para>Just parse the input files, and print their
|
||
abstract syntax trees on standard output in ATerm
|
||
format.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--eval</option></term>
|
||
|
||
<listitem><para>Just parse and evaluate the input files, and print
|
||
the resulting values on standard output. No instantiation of
|
||
store derivations takes place.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--find-file</option></term>
|
||
|
||
<listitem><para>Look up the given files in Nix’s search path (as
|
||
specified by the <envar linkend="env-NIX_PATH">NIX_PATH</envar>
|
||
environment variable). If found, print the corresponding absolute
|
||
paths on standard output. For instance, if
|
||
<envar>NIX_PATH</envar> is
|
||
<literal>nixpkgs=/home/alice/nixpkgs</literal>, then
|
||
<literal>nix-instantiate --find-file nixpkgs/default.nix</literal>
|
||
will print
|
||
<literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--xml</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, 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 <link
|
||
linkend="builtin-toXML"><function>toXML</function> built-in</link>.
|
||
</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--json</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, print the resulting
|
||
value as an JSON representation of the abstract syntax tree rather
|
||
than as an ATerm.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--strict</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>,
|
||
recursively evaluate list elements and attributes. Normally, such
|
||
sub-expressions are left unevaluated (since the Nix expression
|
||
language is lazy).</para>
|
||
|
||
<warning><para>This option can cause non-termination, because lazy
|
||
data structures can be infinitely large.</para></warning>
|
||
|
||
</listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--read-write-mode</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, 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).</para>
|
||
|
||
</listitem>
|
||
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
<variablelist condition="manpage">
|
||
<xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<para>Instantiating store derivations from a Nix expression, and
|
||
building them using <command>nix-store</command>:
|
||
|
||
<screen>
|
||
$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
|
||
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
|
||
|
||
$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
|
||
<replaceable>...</replaceable>
|
||
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>
|
||
|
||
$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
|
||
dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib
|
||
...</screen>
|
||
|
||
</para>
|
||
|
||
<para>You can also give a Nix expression on the command line:
|
||
|
||
<screen>
|
||
$ nix-instantiate -E 'with import <nixpkgs> { }; hello'
|
||
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
|
||
</screen>
|
||
|
||
This is equivalent to:
|
||
|
||
<screen>
|
||
$ nix-instantiate '<nixpkgs>' -A hello
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
<para>Parsing and evaluating Nix expressions:
|
||
|
||
<screen>
|
||
$ nix-instantiate --parse -E '1 + 2'
|
||
1 + 2
|
||
|
||
$ nix-instantiate --eval -E '1 + 2'
|
||
3
|
||
|
||
$ nix-instantiate --eval --xml -E '1 + 2'
|
||
<![CDATA[<?xml version='1.0' encoding='utf-8'?>
|
||
<expr>
|
||
<int value="3" />
|
||
</expr>]]></screen>
|
||
|
||
</para>
|
||
|
||
<para>The difference between non-strict and strict evaluation:
|
||
|
||
<screen>
|
||
$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
|
||
<replaceable>...</replaceable><![CDATA[
|
||
<attr name="x">
|
||
<string value="foo" />
|
||
</attr>
|
||
<attr name="y">
|
||
<unevaluated />
|
||
</attr>]]>
|
||
<replaceable>...</replaceable></screen>
|
||
|
||
Note that <varname>y</varname> is left unevaluated (the XML
|
||
representation doesn’t attempt to show non-normal forms).
|
||
|
||
<screen>
|
||
$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
|
||
<replaceable>...</replaceable><![CDATA[
|
||
<attr name="x">
|
||
<string value="foo" />
|
||
</attr>
|
||
<attr name="y">
|
||
<string value="foo" />
|
||
</attr>]]>
|
||
<replaceable>...</replaceable></screen>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection condition="manpage"><title>Environment variables</title>
|
||
|
||
<variablelist>
|
||
<xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refentry>
|