nix-super/doc/manual/nix-instantiate.xml

193 lines
5.8 KiB
XML
Raw Normal View History

<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
2005-04-05 18:28:30 +03:00
<refnamediv>
<refname>nix-instantiate</refname>
<refpurpose>instantiate store derivations from Nix expressions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-instantiate</command>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
2006-10-05 12:08:52 +03:00
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
2006-10-05 23:07:41 +03:00
<arg>
<group choice='req'>
<arg choice='plain'><option>--attr</option></arg>
<arg choice='plain'><option>-A</option></arg>
</group>
<replaceable>attrPath</replaceable>
</arg>
2005-04-05 18:28:30 +03:00
<arg><option>--add-root</option> <replaceable>path</replaceable></arg>
<arg><option>--indirect</option></arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--parse-only</option></arg>
<arg choice='plain'>
<option>--eval-only</option>
<arg><option>--strict</option></arg>
</arg>
</group>
<arg><option>--xml</option></arg>
</arg>
2005-04-05 18:28:30 +03:00
<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 loads and evaluates the Nix expressions in each
of <replaceable>files</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>
2005-04-05 18:28:30 +03:00
<para>Most users and developers dont need to use this command
(<command>nix-env</command> and <command>nix-build</command> perform
store derivation instantiation from Nix expressions automatically).
It is most commonly used for implementing new deployment
policies.</para>
<para>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-only</option></term>
<listitem><para>Just parse the input files, and print their
abstract syntax trees on standard output in ATerm
format.</para></listitem>
</varlistentry>
2005-04-05 18:28:30 +03:00
<varlistentry><term><option>--eval-only</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>--xml</option></term>
<listitem><para>When used with <option>--parse-only</option> and
<option>--eval-only</option>, print the resulting expression 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>--strict</option></term>
<listitem><para>When used with <option>--eval-only</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>
2005-04-05 18:28:30 +03:00
</variablelist>
2005-04-05 18:28:30 +03:00
</refsection>
2005-04-05 18:28:30 +03:00
<refsection><title>Examples</title>
<para>Instantiating store derivations from a Nix expression, and
building them using <command>nix-store</command>:
2005-04-05 18:28:30 +03:00
<screen>
$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
2005-04-05 18:28:30 +03:00
$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
<replaceable>...</replaceable>
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>
2005-04-05 18:28:30 +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
...</screen>
2003-08-14 14:27:02 +03:00
</para>
<para>Parsing and evaluating Nix expressions:
<screen>
$ echo '"foo" + "bar"' | nix-instantiate --parse-only -
OpPlus(Str("foo"),Str("bar"))
$ echo '"foo" + "bar"' | nix-instantiate --eval-only -
Str("foobar")
$ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
<![CDATA[<?xml version='1.0' encoding='utf-8'?>
<expr>
<string value="foobar" />
</expr>]]></screen>
</para>
<para>The difference between non-strict and strict evaluation:
<screen>
$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml -
<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 doesnt attempt to show non-normal forms).
<screen>
$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict -
<replaceable>...</replaceable><![CDATA[
<attr name="x">
<string value="foo" />
</attr>
<attr name="y">
<string value="foo" />
</attr>]]>
<replaceable>...</replaceable></screen>
</para>
2005-04-05 18:28:30 +03:00
</refsection>
2003-08-14 14:27:02 +03:00
</refentry>