* 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
parent
4271385a73
commit
8b70f138e0
11 changed files with 462 additions and 174 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<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>
|
||||
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
82
doc/manual/conf-file.xml
Normal 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>
|
||||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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" />
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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 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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,21 +1,23 @@
|
|||
<appendix>
|
||||
<title>Troubleshooting</title>
|
||||
<appendix><title>Troubleshooting</title>
|
||||
|
||||
<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:
|
||||
<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,
|
||||
</para>
|
||||
|
||||
<para>Possible solution: make sure that no Nix processes are running,
|
||||
then do:
|
||||
|
||||
<screen>
|
||||
|
|
@ -24,6 +26,44 @@ $ rm __db.00*</screen>
|
|||
|
||||
</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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue