524 lines
16 KiB
XML
524 lines
16 KiB
XML
<refentry>
|
|
|
|
<refnamediv>
|
|
<refname>nix-store</refname>
|
|
<refpurpose>manipulate or query the Nix store</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
|
|
<arg><option>--add-root</option> <replaceable>path</replaceable></arg>
|
|
<arg><option>--indirect</option></arg>
|
|
<arg choice='plain'><replaceable>operation</replaceable></arg>
|
|
<arg rep='repeat'><replaceable>options</replaceable></arg>
|
|
<arg rep='repeat'><replaceable>arguments</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The command <command>nix-store</command> performs primitive
|
|
operations on the Nix store. You generally do not need to run this
|
|
command manually.</para>
|
|
|
|
<para><command>nix-store</command> takes exactly one
|
|
<emphasis>operation</emphasis> flag which indicates the subcommand to
|
|
be performed. These are documented below.</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection><title>Common options</title>
|
|
|
|
<para>This section lists the options that are common to all
|
|
operations. These options are allowed for every subcommand, though
|
|
they may not always have an effect. See also <xref
|
|
linkend="sec-common-options" /> for a list of common options.</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
|
|
|
|
<listitem><para>Causes the result of a realisation
|
|
(<option>--realise</option> and <option>--force-realise</option>)
|
|
to be registered as a root of the garbage collector (see <xref
|
|
linkend="ssec-gc-roots" />). The root is stored in
|
|
<replaceable>path</replaceable>, which must be inside a directory
|
|
that is scanned for roots by the garbage collector (i.e.,
|
|
typically in a subdirectory of
|
|
<filename>/nix/var/nix/gcroots/</filename>)
|
|
<emphasis>unless</emphasis> the <option>--indirect</option> flag
|
|
is used.</para>
|
|
|
|
<para>If there are multiple results, then multiple symlinks will
|
|
be created by sequentially numbering symlinks beyond the first one
|
|
(e.g., <filename>foo</filename>, <filename>foo-2</filename>,
|
|
<filename>foo-3</filename>, and so on).</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--indirect</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>In conjunction with <option>--add-root</option>, this option
|
|
allows roots to be stored <emphasis>outside</emphasis> of the GC
|
|
roots directory. This is useful for commands such as
|
|
<command>nix-build</command> that place a symlink to the build
|
|
result in the current directory; such a build result should not be
|
|
garbage-collected unless the symlink is removed.</para>
|
|
|
|
<para>The <option>--indirect</option> flag causes a uniquely named
|
|
symlink to <replaceable>path</replaceable> to be stored in
|
|
<filename>/nix/var/nix/gcroots/auto/</filename>. For instance,
|
|
|
|
<screen>
|
|
$ nix-store --add-root /home/eelco/bla/result --indirect -r <replaceable>...</replaceable>
|
|
|
|
$ ls -l /nix/var/nix/gcroots/auto
|
|
lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
|
|
|
|
$ ls -l /home/eelco/bla/result
|
|
lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10</screen>
|
|
|
|
Thus, when <filename>/home/eelco/bla/result</filename> is removed,
|
|
the GC root in the <filename>auto</filename> directory becomes a
|
|
dangling symlink and will be ignored by the collector.</para>
|
|
|
|
<warning><para>Note that it is not possible to move or rename
|
|
indirect GC roots, since the symlink in the
|
|
<filename>auto</filename> directory will still point to the old
|
|
location.</para></warning>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection id='rsec-nix-store-realise'><title>Operation
|
|
<option>--realise</option></title>
|
|
|
|
<refsection><title>Synopsis</title>
|
|
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<group choice='req'>
|
|
<arg choice='plain'><option>--realise</option></arg>
|
|
<arg choice='plain'><option>-r</option></arg>
|
|
</group>
|
|
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
</refsection>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The operation <option>--realise</option> essentially “builds”
|
|
the specified store paths. Realisation is a somewhat overloaded term:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>If the store path is a
|
|
<emphasis>derivation</emphasis>, realisation ensures that the output
|
|
paths of the derivation are <link
|
|
linkend="gloss-validity">valid</link> (i.e., the output path and its
|
|
closure exist in the file system). This can be done in several
|
|
ways. First, it is possible that the outputs are already valid, in
|
|
which case we are done immediately. Otherwise, there may be <link
|
|
linkend="gloss-substitute">substitutes</link> that produce the
|
|
outputs (e.g., by downloading them). Finally, the outputs can be
|
|
produced by performing the build action described by the
|
|
derivation.</para></listitem>
|
|
|
|
<listitem><para>If the store path is not a derivation, realisation
|
|
ensures that the specified path is valid (i.e., it and its closure
|
|
exist in the file system). If the path is already valid, we are
|
|
done immediately. Otherwise, the path and any missing paths in its
|
|
closure may be produced through substitutes. If there are no
|
|
(succesful) subsitutes, realisation fails.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
<para>The output path of each derivation is printed on standard
|
|
output. (For non-derivations argument, the argument itself is
|
|
printed.)</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Examples</title>
|
|
|
|
<para>This operation is typically used to build store derivations
|
|
produced by <link
|
|
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
|
|
|
|
<screen>
|
|
$ nix-store -r $(nix-instantiate ./foo.nix)</screen>
|
|
|
|
This is essentially what <link
|
|
linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title>
|
|
|
|
<refsection><title>Synopsis</title>
|
|
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<arg choice='plain'><option>--gc</option></arg>
|
|
<group choice='req'>
|
|
<arg choice='plain'><option>--print-roots</option></arg>
|
|
<arg choice='plain'><option>--print-live</option></arg>
|
|
<arg choice='plain'><option>--print-dead</option></arg>
|
|
<arg choice='plain'><option>--delete</option></arg>
|
|
</group>
|
|
</cmdsynopsis>
|
|
|
|
</refsection>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>Without additional flags, the operation <option>--gc</option>
|
|
performs a garbage collection on the Nix store. That is, all paths in
|
|
the Nix store not reachable via file system references from a set of
|
|
“roots”, are deleted.</para>
|
|
|
|
<para>The following suboperations may be specified:</para>
|
|
|
|
<variablelist>
|
|
|
|
<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>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--print-live</option></term>
|
|
|
|
<listitem><para>This operation prints on standard output the set
|
|
of “live” store paths, which are all the store paths reachable
|
|
from the roots. Live paths should never be deleted, since that
|
|
would break consistency — it would become possible that
|
|
applications are installed that reference things that are no
|
|
longer present in the store.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--print-dead</option></term>
|
|
|
|
<listitem><para>This operation prints out on standard output the
|
|
set of “dead” store paths, which is just the opposite of the set
|
|
of live paths: any path in the store that is not live (with
|
|
respect to the roots) is dead.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--delete</option></term>
|
|
|
|
<listitem><para>This operation performs an actual garbage
|
|
collection. All dead paths are removed from the
|
|
store. This is the default.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</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>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Examples</title>
|
|
|
|
<para>To delete all unreachable paths, just do:
|
|
|
|
<screen>
|
|
$ nix-store --gc</screen>
|
|
|
|
</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection><title>Operation <option>--query</option></title>
|
|
|
|
<refsection><title>Synopsis</title>
|
|
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<group choice='req'>
|
|
<arg choice='plain'><option>--query</option></arg>
|
|
<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>--requisites</option></arg>
|
|
<arg choice='plain'><option>-R</option></arg>
|
|
<arg choice='plain'><option>--predecessors</option></arg>
|
|
<arg choice='plain'><option>--graph</option></arg>
|
|
</group>
|
|
<arg><option>--normalise</option></arg>
|
|
<arg><option>-n</option></arg>
|
|
<arg><option>--force-realise</option></arg>
|
|
<arg><option>-f</option></arg>
|
|
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The operation <option>--query</option> displays various bits of
|
|
information about store paths. The queries are described below. At
|
|
most one query can be specified. The default query is
|
|
<option>--list</option>.</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Common query options</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>--use-output</option> / <option>-u</option></term>
|
|
|
|
<listitem><para>For each argument to the query that is a store
|
|
derivation, apply the query to the output path of the derivation
|
|
instead.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--force-realise</option> / <option>-f</option></term>
|
|
|
|
<listitem><para>Realise each argument to the query first (see
|
|
<link linkend="rsec-nix-store-realise"><command>nix-store
|
|
--realise</command></link>).</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection id='nixref-queries'><title>Queries</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>--list</option> / <option>-l</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>
|
|
|
|
</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>
|
|
|
|
<para>This query has one option:</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>--include-outputs</option></term>
|
|
|
|
<listitem><para>Also include the output path of store
|
|
derivations, and their closures.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</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>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection id="rsec-nix-store-reg-val"><title>Operation <option>--register-validity</option></title>
|
|
|
|
<refsection><title>Synopsis</title>
|
|
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<arg choice='req'><option>--register-validity</option></arg>
|
|
</cmdsynopsis>
|
|
</refsection>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>TODO</para>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection><title>Operation <option>--substitute</option></title>
|
|
|
|
<refsection><title>Synopsis</title>
|
|
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<arg choice='req'><option>--substitute</option></arg>
|
|
<arg choice='plain'
|
|
rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsection>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The operation <option>--substitute</option> registers that the
|
|
store path <replaceable>srcpath</replaceable> can be built by
|
|
realising the derivation expression in
|
|
<replaceable>subpath</replaceable>. This is used to implement binary
|
|
deployment.</para>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection><title>Operation <option>--verify</option></title>
|
|
|
|
<refsection>
|
|
<title>Synopsis</title>
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<arg choice='req'><option>--verify</option></arg>
|
|
</cmdsynopsis>
|
|
</refsection>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The operation <option>--verify</option> verifies the internal
|
|
consistency of the Nix database, and the consistency between the Nix
|
|
database and the Nix store. Any inconsistencies encountered are
|
|
automatically repaired. Inconsistencies are generally the result of
|
|
the Nix store or database being modified by non-Nix tools, or of bugs
|
|
in Nix itself.</para>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
</refentry>
|