path: root/doc/manual/nix-instantiate.xml

<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>
    <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>
    <sbr/>
    <command>nix-instantiate</command>
    <arg choice='plain'><option>--file-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>--parse</option> and
    <option>--eval</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>--json</option></term>

    <listitem><para>When used with <option>--parse</option> and
    <option>--eval</option>, print the resulting expression 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 &lt;nixpkgs> { }; hello'
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
</screen>

This is equivalent to:

<screen>
$ nix-instantiate '&lt;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>