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>
    <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><option>--read-write-mode</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>

  <varlistentry><term><option>--read-write-mode</option></term>

    <listitem><para>When used with <option>--eval-only</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>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>