diff options
| -rw-r--r-- | doc/manual/nix-build.xml | 16 | ||||
| -rw-r--r-- | doc/manual/nix-instantiate.xml | 90 | ||||
| -rw-r--r-- | doc/manual/opt-common.xml | 2 | ||||
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 2 |
4 files changed, 104 insertions, 6 deletions
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index dc4a5ac874b6..bb64085f8380 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -117,4 +117,20 @@ except for <option>--arg</option> and <option>--attr</option> / </refsection> +<refsection><title>Examples</title> + +<screen> +$ nix-build pkgs/top-level/all-packages.nix -A firefox +store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv +/nix/store/d18hyl92g30l...-firefox-1.5.0.7 + +$ ls -l result +lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 + +$ ls ./result/bin/ +firefox firefox-config</screen> + +</refsection> + + </refentry> diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml index 5f3874308164..71c8d3ec37eb 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/nix-instantiate.xml @@ -20,10 +20,16 @@ </arg> <arg><option>--add-root</option> <replaceable>path</replaceable></arg> <arg><option>--indirect</option></arg> - <group choice='opt'> - <arg choice='plain'><option>--parse-only</option></arg> - <arg choice='plain'><option>--eval-only</option></arg> - </group> + <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> @@ -85,6 +91,31 @@ common options.</para> </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> @@ -92,6 +123,9 @@ common options.</para> <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 @@ -104,6 +138,54 @@ $ 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> diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index 95e8f78d99cc..1d09fef955f1 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -286,4 +286,4 @@ </variablelist> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index cf590190ca56..e8d84164e3df 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -1769,7 +1769,7 @@ in foo</programlisting> </varlistentry> - <varlistentry><term><function>builtins.toXML</function> <replaceable>e</replaceable></term> + <varlistentry xml:id='builtin-toXML'><term><function>builtins.toXML</function> <replaceable>e</replaceable></term> <listitem><para>Return a string containing an XML representation of <replaceable>e</replaceable>. The main application for |