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, 0 insertions, 278 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 deleted file mode 100644 index 3fd2ef2a95..0000000000 --- a/third_party/nix/doc/manual/command-ref/nix-instantiate.xml +++ /dev/null @@ -1,278 +0,0 @@ -<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> |