Restructuring the Nix manual

1 files changed, 263 insertions, 0 deletions

diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml
new file mode 100644
index 000000000000..a4e45cf97af4
--- /dev/null
+++ b/doc/manual/command-ref/nix-instantiate.xml
@@ -0,0 +1,263 @@
+<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>--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>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>