<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> <arg choice='plain'><option>--find-file</option></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> (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>Most users and developers don’t 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>--find-file</option></term> <listitem><para>Look up the given files in Nix’s search path (as specified by the <envar>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>--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 doesn’t 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>