diff options
Diffstat (limited to 'third_party/nix/doc/manual/command-ref/nix-instantiate.xml')
| -rw-r--r-- | third_party/nix/doc/manual/command-ref/nix-instantiate.xml | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/third_party/nix/doc/manual/command-ref/nix-instantiate.xml b/third_party/nix/doc/manual/command-ref/nix-instantiate.xml new file mode 100644 index 000000000000..3fd2ef2a9507 --- /dev/null +++ b/third_party/nix/doc/manual/command-ref/nix-instantiate.xml @@ -0,0 +1,278 @@ +<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> + <arg><option>--<arg>no</arg>trace-file-access</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>--<arg>no</arg>trace-file-access</option></term> + <listitem><para>While instantiating the expression, the evaluator will + print the full path to any files it reads with the prefix + <envar>trace-file-access: </envar> to the standard error.</para> + </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). If this option is + not enabled, there may be uninstantiated store paths in the final + output.</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><title>Conformance</title> + <para>The <option>--trace-file-access</option> option is a nonstandard + extension added by Tvix in 2020.</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> |