* Lots of manual updates, in particular the new `nix-store --query'

options were documented, as well as the Nix configuration file.
This commit is contained in:
Eelco Dolstra 2005-04-08 13:00:38 +00:00
parent 4271385a73
commit 8b70f138e0
11 changed files with 462 additions and 174 deletions

View file

@ -20,6 +20,7 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
$(man1_MANS:.1=.xml) \
troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
conf-file.xml \
style.css images
manual.is-valid: $(MANUAL_SRCS) version.txt

View file

@ -2,36 +2,25 @@
<itemizedlist>
<listitem>
<para>
The man-pages generated from the DocBook documentation are ugly.
</para>
</listitem>
<listitem><para>The man-pages generated from the DocBook documentation
are ugly.</para></listitem>
<listitem>
<para>
Generations properly form a tree. E.g., if after switching to
generation 39, we perform an installation action, a generation
43 is created which is a descendant of 39, not 42. So a
rollback from 43 ought to go back to 39. This is not
currently implemented; generations form a linear sequence.
</para>
</listitem>
<listitem><para>Generations properly form a tree. E.g., if after
switching to generation 39, we perform an installation action, a
generation 43 is created which is a descendant of 39, not 42. So a
rollback from 43 ought to go back to 39. This is not currently
implemented; generations form a linear sequence.</para></listitem>
<listitem>
<para>
<emphasis>Build management.</emphasis> In principle it is already
possible to do build management using Nix (by writing builders that
perform appropriate build steps), but the Nix expression language is
not yet powerful enough to make this pleasant (?). The language should
be extended with features from the <ulink
url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
Another interesting idea is to write a <command>make</command>
implementation that uses Nix as a back-end to support <ulink
url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
build files.
</para>
</listitem>
<listitem><para><emphasis>Build management.</emphasis> In principle it
is already possible to do build management using Nix (by writing
builders that perform appropriate build steps), but the Nix expression
language is not yet powerful enough to make this pleasant (?). The
language should be extended with features from the <ulink
url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
Another interesting idea is to write a <command>make</command>
implementation that uses Nix as a back-end to support <ulink
url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
build files.</para></listitem>
<listitem><para>For security, <command>nix-push</command> manifests
should be digitally signed, and <command>nix-pull</command> should
@ -44,6 +33,14 @@ them).</para></listitem>
<command>nix-env --delete-generations</command> to remove non-current
generations older than a certain age.</para></listitem>
<listitem><para>There should be a flexible way to change the user
environment builder. Currently, you have to replace
<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>,
which is hard-coded into <command>nix-env</command>. Also, the
default builder should be more powerful. For instance, there should
be some way to specify priorities to resolve
collisions.</para></listitem>
</itemizedlist>
</appendix>

82
doc/manual/conf-file.xml Normal file
View file

@ -0,0 +1,82 @@
<sect1 id="sec-conf-file"><title>Nix configuration file</title>
<para>A number of persistent settings of Nix are stored in the file
<filename><replaceable>prefix</replaceable>/etc/nix/nix.conf</filename>.
This file is a list of <literal><replaceable>name</replaceable> =
<replaceable>value</replaceable></literal> pairs, one per line.
Comments start with a <literal>#</literal> character. An example
configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
<example id='ex-nix-conf'><title>Nix expression for GNU Hello</title>
<programlisting>
gc-keep-outputs = true # Nice for developers
gc-keep-derivations = true # Idem
env-keep-derivations = false
</programlisting>
</example>
<para>The following variables are currently available:
<variablelist>
<varlistentry id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
<listitem><para>If <literal>true</literal>, the garbage collector
will keep the outputs of non-garbage derivations. If
<literal>false</literal> (default), outputs will be deleted unless
they are GC roots themselves (or reachable from other roots).</para>
<para>In general, outputs must be registered as roots separately.
However, even if the output of a derivation is registered as a
root, the collector will still delete store paths that are used
only at build time (e.g., the C compiler, or source tarballs
downloaded from the network). To prevent it from doing so, set
this option to <literal>true</literal>.</para></listitem>
</varlistentry>
<varlistentry id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
<listitem><para>If <literal>true</literal> (default), the garbage
collector will keep the derivations from which non-garbage store
paths were built. If <literal>false</literal>, they will be
deleted unless explicitly registered as a root (or reachable from
other roots).</para>
<para>Keeping derivation around is useful for querying and
traceability (e.g., it allows you to ask with what dependencies or
options a store path was built), so by default this option is on.
Turn it off to safe a bit of disk space (or a lot if
<literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
</varlistentry>
<varlistentry><term><literal>env-keep-derivations</literal></term>
<listitem><para>If <literal>false</literal> (default), derivations
are not stored in Nix user environments. That is, the derivation
any build-time-only dependencies may be garbage-collected.</para>
<para>If <literal>true</literal>, when you add a Nix derivation to
a user environment, the path of the derivation is stored in the
user environment. Thus, the derivation will not be
garbage-collected until the user environment generation is deleted
(<command>nix-env --delete-generations</command>). To prevent
build-time-only dependencies from being collected, you should also
turn on <literal>gc-keep-outputs</literal>.</para>
<para>The difference between this option and
<literal>gc-keep-derivations</literal> is that this one is
“sticky”: it applies to any user environment created while this
option was enabled, while <literal>gc-keep-derivations</literal>
only applies at the moment the garbage collector is
run.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

View file

@ -79,17 +79,47 @@
</glossentry>
<glossentry><glossterm>closure</glossterm>
<glossentry id="gloss-reference"><glossterm>reference</glossterm>
<glossdef><para>A store path <varname>P</varname> is said to have a
reference to a store path <varname>Q</varname> if the store object
at <varname>P</varname> contains the path <varname>Q</varname>
somewhere. This implies than an execution involving
<varname>P</varname> potentially needs <varname>Q</varname> to be
present. The <emphasis>references</emphasis> of a store path are
the set of store paths to which it has a reference.</para></glossdef>
</glossentry>
<glossentry id="gloss-closure"><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>
path; that is, its the closure of the path under the <link
linkend="gloss-reference">references</link> relation. 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>
<glossentry id="gloss-output-path"><glossterm>output path</glossterm>
<glossdef><para>A store path produced by a derivation.</para></glossdef>
</glossentry>
<glossentry id="gloss-deriver"><glossterm>deriver</glossterm>
<glossdef><para>The deriver of an <link
linkend="gloss-output-path">output path</link> is the store
derivation that built it.</para></glossdef>
</glossentry>

View file

@ -35,6 +35,7 @@
<title>Command Reference</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conf-file.xml" />
<sect1>
<title>nix-env</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />

View file

@ -10,14 +10,14 @@
<command>nix-push</command>
<group choice='req'>
<arg choice='req'>
<arg choice='plain'><replaceable>archives-put-url</replaceable></arg>
<arg choice='plain'><replaceable>archives-get-url</replaceable></arg>
<arg choice='plain'><replaceable>manifest-put-url</replaceable></arg>
<arg choice='plain'><replaceable>archivesPutURL</replaceable></arg>
<arg choice='plain'><replaceable>archivesGetURL</replaceable></arg>
<arg choice='plain'><replaceable>manifestPutURL</replaceable></arg>
</arg>
<arg choice='req'>
<arg choice='plain'><option>--copy</option></arg>
<arg choice='plain'><replaceable>archives-dir</replaceable></arg>
<arg choice='plain'><replaceable>manifest-file</replaceable></arg>
<arg choice='plain'><replaceable>archivesDir</replaceable></arg>
<arg choice='plain'><replaceable>manifestFile</replaceable></arg>
</arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
@ -59,20 +59,20 @@ machines using the <command>nix-pull</command> command.</para>
archives.</para></listitem>
<listitem><para>Each store path is uploaded to the remote directory
specified by <replaceable>archives-put-url</replaceable>. HTTP PUT
specified by <replaceable>archivesPutURL</replaceable>. HTTP PUT
requests are used to do this. However, before a file
<varname>x</varname> is uploaded to
<literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>,
<literal><replaceable>archivesPutURL</replaceable>/<varname>x</varname></literal>,
<command>nix-push</command> first determines whether this upload is
unnecessary by issuing a HTTP HEAD request on
<literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>.
<literal><replaceable>archivesGetURL</replaceable>/<varname>x</varname></literal>.
This allows a cache to be shared between many partially overlapping
<command>nix-push</command> invocations. (We use two URLs because
the upload URL typically refers to a CGI script, while the download
URL just refers to a file system directory on the server.)</para></listitem>
<listitem><para>The manifest is uploaded using an HTTP PUT request
to <replaceable>manifest-put-url</replaceable>. The corresponding
to <replaceable>manifestPutURL</replaceable>. The corresponding
URL to download the manifest can then be used by
<command>nix-pull</command>.</para></listitem>

View file

@ -168,7 +168,8 @@ produced by <link
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
<screen>
$ nix-store -r $(nix-instantiate ./foo.nix)</screen>
$ nix-store -r $(nix-instantiate ./test.nix)
/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen>
This is essentially what <link
linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
@ -213,7 +214,9 @@ the Nix store not reachable via file system references from a set of
<varlistentry><term><option>--print-roots</option></term>
<listitem><para>This operation prints on standard output the set
of roots used by the garbage collector.</para></listitem>
of roots used by the garbage collector. What constitutes a root
is described in <xref linkend="ssec-gc-roots"
/>.</para></listitem>
</varlistentry>
@ -247,35 +250,11 @@ the Nix store not reachable via file system references from a set of
</variablelist>
</refsection>
<refsection><title>Roots</title>
<para>The roots of the garbage collector are all store paths to which
there are symlinks in the directory
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
For instance, the following command makes the path
<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
<screen>
$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
That is, after this command, the garbage collector will not remove
<filename>/nix/store/d718ef...-foo</filename> or any of its
dependencies.</para>
<para>Subdirectories of
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
are also searched for symlinks. Symlinks to non-store paths are
followed and searched for roots, but TODO.</para>
</refsection>
<refsection><title>Configuration file</title>
<para>TODO</para>
<para>The behaviour of the collector is influenced by the <link
linkend="conf-gc-keep-outputs"><literal>gc-keep-outputs</literal></link>
and <link
linkend="conf-gc-keep-derivations"><literal>gc-keep-derivations</literal></link>
variables in the Nix configuration file.</para>
</refsection>
@ -309,18 +288,24 @@ $ nix-store --gc</screen>
<arg choice='plain'><option>-q</option></arg>
</group>
<group choice='req'>
<arg choice='plain'><option>--list</option></arg>
<arg choice='plain'><option>-l</option></arg>
<arg choice='plain'><option>--outputs</option></arg>
<arg choice='plain'><option>--requisites</option></arg>
<arg choice='plain'><option>-R</option></arg>
<arg choice='plain'><option>--predecessors</option></arg>
<arg choice='plain'><option>--references</option></arg>
<arg choice='plain'><option>--referers</option></arg>
<arg choice='plain'><option>--referers-closure</option></arg>
<arg choice='plain'><option>--deriver</option></arg>
<arg choice='plain'><option>--deriver</option></arg>
<arg choice='plain'><option>--graph</option></arg>
<arg choice='plain'><option>--tree</option></arg>
<arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg>
<arg choice='plain'><option>--hash</option></arg>
</group>
<arg><option>--normalise</option></arg>
<arg><option>-n</option></arg>
<arg><option>--use-output</option></arg>
<arg><option>-u</option></arg>
<arg><option>--force-realise</option></arg>
<arg><option>-f</option></arg>
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsection>
@ -329,9 +314,14 @@ $ nix-store --gc</screen>
<refsection><title>Description</title>
<para>The operation <option>--query</option> displays various bits of
information about store paths. The queries are described below. At
information about the store paths . The queries are described below. At
most one query can be specified. The default query is
<option>--list</option>.</para>
<option>--outputs</option>.</para>
<para>The paths <replaceable>paths</replaceable> may also be symlinks
from outside of the Nix store, to the Nix store. In that case, the
query is applied to the target of the symlink.</para>
</refsection>
@ -365,47 +355,21 @@ most one query can be specified. The default query is
<variablelist>
<varlistentry><term><option>--list</option> / <option>-l</option></term>
<varlistentry><term><option>--outputs</option></term>
<listitem><para>Prints out the <emphasis>output paths</emphasis>
of the store expressions indicated by the identifiers
<replaceable>args</replaceable>. In the case of a derivation
expression, these are the paths that will be produced when the
derivation is realised. In the case of a closure expression,
these are the paths that were produced the derivation expression
of which the closure expression is a successor.</para></listitem>
<listitem><para>Prints out the <link
linkend="gloss-output-path">output paths</link> of the store
derivations <replaceable>paths</replaceable>. These are the paths
that will be produced when the derivation is
built.</para></listitem>
</varlistentry>
<varlistentry><term><option>--requisites</option> / <option>-R</option></term>
<listitem><para>Prints out the requisite paths of the store
expressions indicated by the identifiers
<replaceable>args</replaceable>. The requisite paths of a Nix
expression are the paths that need to be present in the system to
be able to realise the expression. That is, they form the
<emphasis>closure</emphasis> of the expression in the file system
(i.e., no path in the set of requisite paths points to anything
outside the set of requisite paths).</para>
<para>The notion of requisite paths is very useful when one wants
to distribute store expressions. Since they form a closure, they
are the only paths one needs to distribute to another system to be
able to realise the expression on the other system.</para>
<para>This query is generally used to implement various kinds of
deployment. A <emphasis>source deployment</emphasis> is obtained
by distributing the requisite paths of a derivation expression. A
<emphasis>binary deployment</emphasis> is obtained by distributing
the requisite paths of a closure expression. A <emphasis>cache
deployment</emphasis> is obtained by distributing the requisite
paths of a derivation expression and specifying the option
<option>--include-successors</option>. This will include not just
the paths of a source and binary deployment, but also all
expressions and paths of subterms of the source. This is useful
if one wants to realise on the target system a Nix expression that
is similar but not quite the same as the one being distributed,
since any common subterms will be reused.</para>
<listitem><para>Prints out the <link
linkend="gloss-closure">closure</link> of the store path
<replaceable>paths</replaceable>.</para>
<para>This query has one option:</para>
@ -420,17 +384,104 @@ most one query can be specified. The default query is
</variablelist>
<para>This query can be used to implement various kinds of
deployment. A <emphasis>source deployment</emphasis> is obtained
by distributing the closure of a store derivation. A
<emphasis>binary deployment</emphasis> is obtained by distributing
the closure of an output path. A <emphasis>cache
deployment</emphasis> (combined source/binary deployment,
including binaries of build-time-only dependencies) is obtained by
distributing the closure of a store derivation and specifying the
option <option>--include-outputs</option>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>--references</option></term>
<listitem><para>Prints the set of <link
linkend="gloss-reference">references</link> of the store paths
<replaceable>paths</replaceable>, that is, their immediate
dependencies. (For <emphasis>all</emphasis> dependencies, use
<option>--requisites</option>.)</para></listitem>
</varlistentry>
<varlistentry><term><option>--referers</option></term>
<listitem><para>Prints the set of <emphasis>referers</emphasis> of
the store paths <replaceable>paths</replaceable>, that is, the
store paths currently existing in the Nix store that refer to one
of <replaceable>paths</replaceable>. Note that contrary to the
references, the set of referers is not constant; it can change as
store paths are added or removed.</para></listitem>
</varlistentry>
<varlistentry><term><option>--referers-closure</option></term>
<listitem><para>Prints the closure of the set of store paths
<replaceable>paths</replaceable> under the referers relation; that
is, all store paths that directly or indirectly refer to one of
<replaceable>paths</replaceable>. These are all the path currently
in the Nix store that are dependent on
<replaceable>paths</replaceable>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--deriver</option></term>
<listitem><para>Prints the <link
linkend="gloss-deriver">deriver</link> of the store paths
<replaceable>paths</replaceable>. If the path has no deriver
(e.g., if it is a source file), or if the deriver is not known
(e.g., in the case of a binary-only deployment), the string
<literal>unknown-deriver</literal> is printed.</para></listitem>
</varlistentry>
<varlistentry><term><option>--graph</option></term>
<listitem><para>Prints a graph of the closure of the store
expressions identified by <replaceable>args</replaceable> in the
format of the <command>dot</command> tool of AT&amp;T's GraphViz
package.</para></listitem>
<listitem><para>Prints the references graph of the store paths
<replaceable>paths</replaceable> in the format of the
<command>dot</command> tool of AT&amp;T's <ulink
url="http://www.graphviz.org/">Graphviz package</ulink>. This can
be used to visualise dependency graphs. To obtain a build-time
dependency graph, apply this to a store derivation. To obtain a
runtime dependency graph, apply it to an output
path.</para></listitem>
</varlistentry>
<varlistentry><term><option>--tree</option></term>
<listitem><para>Prints the references graph of the store paths
<replaceable>paths</replaceable> as a nested ASCII tree.
References are ordered by descending closure size; this tends to
flatten the tree, making it more readable. The query only
recurses into a store path when it is first encountered; this
prevents a blowup of the tree representation of the
graph.</para></listitem>
</varlistentry>
<varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term>
<listitem><para>Prints the value of the attribute
<replaceable>name</replaceable> (i.e., environment variable) of
the store derivations <replaceable>paths</replaceable>. It is an
error for a derivation to not have the specified
attribute.</para></listitem>
</varlistentry>
<varlistentry><term><option>--hash</option></term>
<listitem><para>Prints the SHA-256 hash of the contents of the
store path <replaceable>paths</replaceable>. Since the hash is
stored in the Nix database, this is a fast
operation.</para></listitem>
</varlistentry>
@ -439,6 +490,81 @@ most one query can be specified. The default query is
</refsection>
<refsection><title>Examples</title>
<para>Print the closure (runtime dependencies) of the
<command>svn</command> program in the current user environment:
<screen>
$ nix-store -qR $(which svn)
/nix/store/4mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
/nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
<replaceable>...</replaceable></screen>
</para>
<para>Print the build-time dependencies of <command>svn</command>:
<screen>
$ nix-store -qR $(nix-store -qd $(which svn))
/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
<replaceable>... lots of other paths ...</replaceable></screen>
The difference with the previous example is that we ask the closure of
the derivation (<option>-qd</option>), not the closure of the output
path that contains <command>svn</command>.</para>
<para>Show the build-time dependencies as a tree:
<screen>
$ nix-store -q --tree $(nix-store -qd $(which svn))
/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
+---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
+---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
<replaceable>...</replaceable></screen>
</para>
<para>Show all paths that depend on the same OpenSSL library as
<command>svn</command>:
<screen>
$ nix-store -q --referers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
/nix/store/4mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen>
</para>
<para>Show all paths that directly or indirectly depend on the Glibc
(C library) used by <command>svn</command>:
<screen>
$ nix-store -q --referers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
/nix/store/05l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
<replaceable>...</replaceable></screen>
Note that <command>ldd</command> is a command that prints out the
dynamic libraries used by an ELF executable.</para>
<para>Make a picture of the runtime dependency graph of the current
user environment:
<screen>
$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
$ gv graph.ps</screen>
</para>
</refsection>
</refsection>

View file

@ -35,33 +35,33 @@
<variablelist>
<varlistentry><term>0</term>
<listitem><para><quote>Errors only</quote>: only print messages
<listitem><para>“Errors only”: only print messages
explaining why the Nix invocation failed.</para></listitem>
</varlistentry>
<varlistentry><term>1</term>
<listitem><para><quote>Informational</quote>: print
<listitem><para>“Informational”: print
<emphasis>useful</emphasis> messages about what Nix is doing.
This is the default.</para></listitem>
</varlistentry>
<varlistentry><term>2</term>
<listitem><para><quote>Talkative</quote>: print more informational
<listitem><para>“Talkative”: print more informational
messages.</para></listitem>
</varlistentry>
<varlistentry><term>3</term>
<listitem><para><quote>Chatty</quote>: print even more
<listitem><para>“Chatty”: print even more
informational messages.</para></listitem>
</varlistentry>
<varlistentry><term>4</term>
<listitem><para><quote>Debug</quote>: print debug
<listitem><para>“Debug”: print debug
information.</para></listitem>
</varlistentry>
<varlistentry><term>5</term>
<listitem><para><quote>Vomit</quote>: print vast amounts of debug
<listitem><para>“Vomit”: print vast amounts of debug
information.</para></listitem>
</varlistentry>
@ -120,19 +120,21 @@
<listitem>
<para>Whenever Nix attempts to realise a derivation for which a
closure is already known, but this closure cannot be realised, fall
back on normalising the derivation.</para>
<para>Whenever Nix attempts to build a derivation for which
substitutes are known for each output path, but realising the output
paths through the substitutes fails, fall back on building the
derivation.</para>
<para>The most common scenario in which this is useful is when we
have registered substitutes in order to perform binary distribution
from, say, a network repository. If the repository is down, the
realisation of the derivation will fail. When this option is
specified, Nix will build the derivation instead. Thus, binary
installation falls back on a source installation. This option is
not the default since it is generally not desirable for a transient
failure in obtaining the substitutes to lead to a full build from
source (with the related consumption of resources).</para>
specified, Nix will build the derivation instead. Thus,
installation from binaries falls back on nstallation from source.
This option is not the default since it is generally not desirable
for a transient failure in obtaining the substitutes to lead to a
full build from source (with the related consumption of
resources).</para>
</listitem>

View file

@ -369,30 +369,39 @@ $ nix-env --delete-generations 10 11 14</screen>
garbage collector as follows:
<screen>
$ nix-collect-garbage</screen>
$ nix-store --gc</screen>
You can alo first view what files would be deleted:
If you are feeling uncertain, you can also first view what files would
be deleted:
<screen>
$ nix-collect-garbage --print-dead</screen>
$ nix-store --gc --print-dead</screen>
Likewise, the option <option>--print-live</option> will show the paths
that <emphasis>wont</emphasis> be deleted.</para>
<sect2 id="ssec-gc-roots"><title>Garbage collector roots</title>
<para>TODO</para>
<para>The roots of the garbage collector are all store paths to which
there are symlinks in the directory
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
For instance, the following command makes the path
<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
<para>The garbage collector uses as roots all store expressions
mentioned in all files with extension <filename>.gcroot</filename> in
the directory
<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>,
or in any file or directory symlinked to from that directory. E.g.,
by default,
<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>
contains a symlink to
<filename><replaceable>prefix</replaceable>/var/nix/profiles/</filename>,
so all generations of all profiles are also roots of the collector.</para>
<screen>
$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
That is, after this command, the garbage collector will not remove
<filename>/nix/store/d718ef...-foo</filename> or any of its
dependencies.</para>
<para>Subdirectories of
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
are also searched for symlinks. Symlinks to non-store paths are
followed and searched for roots, but symlinks to non-store paths
<emphasis>inside</emphasis> the paths reached in that way are not
followed to prevent infinite recursion.</para>
</sect2>

View file

@ -88,8 +88,8 @@ $ nix-channel --update
$ nix-env -u '*'</screen>
The latter command will upgrade each installed component for which
there is a <quote>newer</quote> version (as determined by comparing
the version numbers).</para></listitem>
there is a “newer” version (as determined by comparing the version
numbers).</para></listitem>
<listitem><para>If you're unhappy with the result of a
<command>nix-env</command> action (e.g., an upgraded component turned
@ -106,12 +106,12 @@ actually delete them:
<screen>
$ nix-env --delete-generations old
$ nix-collect-garbage</screen>
$ nix-store --gc</screen>
The first command deletes old <quote>generations</quote> of your
profile (making rollbacks impossible, but also making the components
in those old generations available for garbage collection), while the
second command actually deletes them.</para></listitem>
The first command deletes old “generations” of your profile (making
rollbacks impossible, but also making the components in those old
generations available for garbage collection), while the second
command actually deletes them.</para></listitem>
</orderedlist>

View file

@ -1,31 +1,71 @@
<appendix>
<title>Troubleshooting</title>
<appendix><title>Troubleshooting</title>
<para>This section provides solutions for some common problems.</para>
<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:
<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:
</para>
<para>Possible solution: make sure that no Nix processes are running,
then do:
<screen>
$ cd /nix/var/nix/db
$ rm __db.00*</screen>
</para>
</para>
</sect1>
<sect1><title>Collisions in <command>nix-env</command></title>
<para>Symptom: when installing or upgrading, you get an error message such as
<screen>
$ nix-env -i docbook-xml
...
adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
collission between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
at /nix/store/...-builder.pl line 62.</screen>
</para>
<para>The cause is that two installed packages in the user environment
have overlapping filenames (e.g.,
<filename>xml/dtd/docbook/calstblx.dtd</filename>. This usually
happens when you accidentally try to install two versions of the same
package. For instance, in the example above, the Nix Packages
collection contains two versions of <literal>docbook-xml</literal>, so
<command>nix-env -i</command> will try to install both. The default
user environment builder has no way to way to resolve such conflicts,
so it just gives up.</para>
<para>Solution: remove one of the offending packages from the user
environment (if already installed) using <command>nix-env
-u</command>, or specify exactly which version should be installed
(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
<para>Alternatively, you can modify the user environment builder
script (in
<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
to implement some conflict resolution policy. E.g., the script could
be modified to rename conflicting file names, or to pick one over the
other.</para>
</sect1>
</sect1>
</appendix>