diff options
| -rw-r--r-- | doc/manual/glossary.xml | 27 | ||||
| -rw-r--r-- | doc/manual/nix-instantiate.xml | 162 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 4 | ||||
| -rw-r--r-- | doc/manual/troubleshooting.xml | 27 | ||||
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 2 |
5 files changed, 137 insertions, 85 deletions
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml index 2c4f55c7e7f0..cf0da38245b1 100644 --- a/doc/manual/glossary.xml +++ b/doc/manual/glossary.xml @@ -3,10 +3,16 @@ <glosslist> -<glossentry><glossterm>derivation</glossterm> +<glossentry id="gloss-derivation"><glossterm>derivation</glossterm> <glossdef><para>A description of a build action. The result of a - derivation is a store object.</para></glossdef> + derivation is a store object. Derivations are typically specified + in Nix expressions using the <link + linkend="ssec-derivation"><function>derivation</function> + primitive</link>. These are translated into low-level + <emphasis>store derivations</emphasis> (implicitly by + <command>nix-env</command> and <command>nix-build</command>, or + explicitly by <command>nix-instantiate</command>).</para></glossdef> </glossentry> @@ -73,7 +79,22 @@ </glossentry> +<glossentry><glossterm>closure</glossterm> + + <glossdef><para>The closure of a store path is the set of store + paths that are directly or indirectly “reachable” from that store + path. For instance, if the store object at path + <varname>P</varname> contains a reference to path + <varname>Q</varname>, then <varname>Q</varname> is in the closure of + <varname>P</varname>. For correct deployment it is necessary to + deploy whole closures, since otherwise at runtime files could be + missing. The command <command>nix-store -qR</command> prints out + closures of store paths.</para></glossdef> + +</glossentry> + + </glosslist> -</appendix> \ No newline at end of file +</appendix> diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml index d854941a09bd..d6cbe77c93de 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/nix-instantiate.xml @@ -1,89 +1,97 @@ <refentry> - <refnamediv> - <refname>nix-instantiate</refname> - <refpurpose>instantiate store expressions 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#xpointer(/nop/*)" /> - <group choice='opt'> - <arg choice='plain'><option>--parse-only</option></arg> - <arg choice='plain'><option>--eval-only</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - - <para> - The command <command>nix-instantiate</command> generates - (low-level) store expressions from (high-level) Nix expressions. - It loads and evaluates the Nix expressions in each of - <replaceable>files</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 expressions - are printed on standard output. - </para> - - <para> - This command is generally used for testing Nix expression before - they are used with <command>nix-env</command>. See also <xref - linkend="sec-common-options" />. - </para> - - </refsection> - - <refsection> - <title>Options</title> - - <variablelist> - - <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> + +<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#xpointer(/nop/*)" /> + <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 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>. 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>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>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 expressions takes place. - </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> - </variablelist> +</variablelist> - </refsection> +</refsection> - <refsection> - <title>Examples</title> - <screen> -$ nix-instantiate gcc.nix <lineannotation>(instantiate)</lineannotation> -/nix/store/468abdcb93aa22bb721142615b97698b-d-gcc-3.3.2.store +<refsection><title>Examples</title> -$ nix-store -r $(nix-instantiate gcc.nix) <lineannotation>(build)</lineannotation> +<screen> +$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation> +/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv -$ nix-store -r $(nix-instantiate gcc.nix) <lineannotation>(print output path)</lineannotation> -/nix/store/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2 +$ 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/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2 -dr-xr-xr-x 2 eelco users 360 2003-12-01 16:12 bin -dr-xr-xr-x 3 eelco users 72 2003-12-01 16:12 include +$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 +dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib ...</screen> - </refsection> - +</refsection> + + </refentry> diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index da96630a5367..0ad0f32a5f8f 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -39,11 +39,11 @@ be performed. These are documented below.</para> <para>This section lists the options that are common to all operations. These options are allowed for every subcommand, though they may not always have an effect. See also <xref -linkend="sec-common-options" />.</para> +linkend="sec-common-options" /> for a list of common options.</para> <variablelist> - <varlistentry><term><option>--add-root</option> <replaceable>path</replaceable></term> + <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term> <listitem><para>Causes the result of a build action (<option>--realise</option> and <option>--force-realise</option>) diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index cc3cd361f8b5..cd0bafe3d663 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -1,8 +1,31 @@ <appendix> <title>Troubleshooting</title> - <para> - (Nothing.) + <para>This section provides solutions for some common problems.</para> + + <sect1><title>Berkeley DB: <quote>Cannot allocate memory</quote></title> + + <para>Symptom: Nix operations (in particular the + <command>nix-store</command> operations <option>--gc</option>, + <option>--verify</option>, and <option>--clear-substitutes</option> + — the latter being called by <command>nix-channel + --update</command>) failing: + +<screen> +$ nix-store --verify +error: Db::del: Cannot allocate memory</screen> + + Possible solution: make sure that no Nix processes are running, + then do: + +<screen> +$ cd /nix/var/nix/db +$ rm __db.00*</screen> + </para> + + + </sect1> + </appendix> diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index a465177f30f6..50cbc4249d7f 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -1103,7 +1103,7 @@ weakest binding).</para> </simplesect> -<simplesect><title>Derivations</title> +<simplesect id="ssec-derivation"><title>Derivations</title> <para>The most important built-in function is <function>derivation</function>, which is used to describe a |