lix/doc/manual/nix-instantiate.xml
2012-04-06 21:56:20 +02:00

215 lines
6.6 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
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>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
<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>
<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>
<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>
<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 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-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>
<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>
</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>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>
</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>