diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/manual/bugs.xml | 57 | ||||
| -rw-r--r-- | doc/manual/conf-file.xml | 82 | ||||
| -rw-r--r-- | doc/manual/glossary.xml | 46 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 1 | ||||
| -rw-r--r-- | doc/manual/nix-push.xml | 18 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 282 | ||||
| -rw-r--r-- | doc/manual/opt-common.xml | 30 | ||||
| -rw-r--r-- | doc/manual/package-management.xml | 39 | ||||
| -rw-r--r-- | doc/manual/quick-start.xml | 14 | ||||
| -rw-r--r-- | doc/manual/troubleshooting.xml | 72 |
11 files changed, 465 insertions, 177 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 60853df05..f5a93cf30 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -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 diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 8a56a28c5..9f8faae96 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -2,36 +2,25 @@ <itemizedlist> - <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> - <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>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><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> diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml new file mode 100644 index 000000000..13fac5335 --- /dev/null +++ b/doc/manual/conf-file.xml @@ -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> diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml index c3dc36fb3..cee6dac25 100644 --- a/doc/manual/glossary.xml +++ b/doc/manual/glossary.xml @@ -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, it’s 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> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index b71798e80..f1dd0430a 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -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" /> diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml index c9c4b40c6..f683784ad 100644 --- a/doc/manual/nix-push.xml +++ b/doc/manual/nix-push.xml @@ -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> diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 0fec253bd..614d30b6a 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -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&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&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> diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index fb35c1a74..467959f19 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -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> diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index 0b0e57504..b827ae75b 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -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>won’t</emphasis> be deleted.</para> + <sect2 id="ssec-gc-roots"><title>Garbage collector roots</title> -<para>TODO</para> - -<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> +<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 symlinks to non-store paths +<emphasis>inside</emphasis> the paths reached in that way are not +followed to prevent infinite recursion.</para> </sect2> diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml index e12b28da2..a6433ae42 100644 --- a/doc/manual/quick-start.xml +++ b/doc/manual/quick-start.xml @@ -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> diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index cd0bafe3d..4179eb841 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -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> |