596 lines
20 KiB
XML
596 lines
20 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" />.</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>--add-root</option> <replaceable>path</replaceable></term>
|
|
|
|
<listitem><para>Causes the result of a build action
|
|
(<option>--realise</option> and <option>--force-realise</option>)
|
|
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></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>--install</option> realises in the file
|
|
system the store expressions stored in
|
|
<replaceable>paths</replaceable>. If these expressions are derivation
|
|
expressions, they are first <emphasis>normalised</emphasis> into a
|
|
closure expression. This may happen in two ways. First, the
|
|
corresponding closure expression (the <emphasis>successor</emphasis>)
|
|
may already known (either because the build has already been
|
|
performed, or because a successor was explicitly registered through
|
|
the <option>--successor</option> operation). Otherwise, the build
|
|
action described by the derivation is performed, and a closure
|
|
expression is computed by scanning the result of the build for
|
|
references to other paths in the store.</para>
|
|
|
|
<para>The paths of the closure expression corresponding to each
|
|
expression in <replaceable>paths</replaceable> is printed on standard
|
|
output.</para>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection>
|
|
<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-live</option></arg>
|
|
<arg choice='plain'><option>--print-dead</option></arg>
|
|
<arg choice='plain'><option>--delete</option></arg>
|
|
</group>
|
|
<arg><option>--min-age</option> <replaceable>age</replaceable></arg>
|
|
</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 <quote>roots</quote>, are deleted.
|
|
</para>
|
|
|
|
<para>
|
|
The following flags 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
|
|
<quote>live</quote> 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
|
|
<quote>dead</quote> 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.
|
|
</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>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<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 expressions or 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>--normalise</option> / <option>-n</option></term>
|
|
<listitem>
|
|
<para>
|
|
For those queries that take a Nix store expression, this
|
|
option causes those expressions to be normalised first.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--force-realise</option> / <option>-f</option></term>
|
|
<listitem>
|
|
<para>
|
|
For those queries that take a Nix store expression, this
|
|
option causes those expressions to be realised first.
|
|
This is just a short-cut for the common idiom
|
|
</para>
|
|
<screen>
|
|
nix-store --realise /nix/store/bla.store
|
|
x=`nix-store --query --normalise /nix/store/bla.store`
|
|
<emphasis>(do something with the path $x</emphasis></screen>
|
|
<para>
|
|
which using this flag can be written as
|
|
</para>
|
|
<screen>
|
|
x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
|
|
<emphasis>(do something with the path $x</emphasis></screen>
|
|
</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 a number of options:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--exclude-exprs</option></term>
|
|
<listitem>
|
|
<para>
|
|
Excludes the paths of store expressions. This
|
|
causes the closure property to be lost, that is,
|
|
the resulting set of paths is not enough to ensure
|
|
realisibility.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--include-successors</option></term>
|
|
<listitem>
|
|
<para>
|
|
Also include the requisites of successors (normal forms).
|
|
Only the requisites of <emphasis>known</emphasis>
|
|
successors are included, i.e., the normal forms of
|
|
derivation expressions that have never been normalised will
|
|
not be included.
|
|
</para>
|
|
|
|
<para>
|
|
Note that not just the successor of a derivation expression
|
|
will be included, but also the successors of all input
|
|
expressions of that derivation expression. I.e., all
|
|
normal forms of subterms involved in the normalisation of
|
|
the top-level term are included.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--predecessors</option></term>
|
|
<listitem>
|
|
<para>
|
|
For each store expression stored at paths
|
|
<replaceable>args</replaceable>, prints its
|
|
<emphasis>predecessors</emphasis>. A derivation
|
|
expression <varname>p</varname> is a predecessor of a
|
|
store expression <varname>q</varname> iff
|
|
<varname>q</varname> is a successor of
|
|
<varname>p</varname>.
|
|
</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>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection>
|
|
<title>Operation <option>--successor</option></title>
|
|
|
|
<refsection>
|
|
<title>Synopsis</title>
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
<arg choice='req'><option>--successor</option></arg>
|
|
<arg choice='plain'
|
|
rep='repeat'><replaceable>srcpath</replaceable> <replaceable>sucpath</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The operation <option>--successor</option> registers that the
|
|
closure expression in <replaceable>sucpath</replaceable> is a
|
|
successor of the derivation expression in
|
|
<replaceable>srcpath</replaceable>. This is used to implement
|
|
binary deployment.
|
|
</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>
|
|
|
|
|
|
<!--
|
|
local variables:
|
|
sgml-parent-document: ("book.xml" "refentry")
|
|
end:
|
|
-->
|