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

<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink">
  
<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/*)" />
    <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 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>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>

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


</refentry>