<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>--json</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> <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>--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>--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>--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>--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>