mirror of
https://github.com/NixOS/nix.git
synced 2024-11-30 02:32:26 +00:00
1270 lines
40 KiB
XML
1270 lines
40 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
xml:id="sec-nix-store">
|
||
|
||
<refmeta>
|
||
<refentrytitle>nix-store</refentrytitle>
|
||
<manvolnum>1</manvolnum>
|
||
<refmiscinfo class="source">Nix</refmiscinfo>
|
||
<refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
|
||
</refmeta>
|
||
|
||
<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#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db: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. <phrase condition="manual">See
|
||
also <xref linkend="sec-common-options" /> for a list of common
|
||
options.</phrase></para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry xml: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<phrase
|
||
condition="manual"> (see <xref linkend="ssec-gc-roots"
|
||
/>)</phrase>. 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>
|
||
|
||
<variablelist condition="manpage">
|
||
<xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml: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>
|
||
<arg><option>--dry-run</option></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>
|
||
|
||
<para>If the <option>--dry-run</option> option is used, then
|
||
<command>nix-store</command> will print on standard error a
|
||
description of what packages would be built or downloaded, and then
|
||
quit.</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 ./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>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml: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>
|
||
<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>
|
||
<arg><option>--max-freed</option> <replaceable>bytes</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
|
||
“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. What constitutes a root
|
||
is described in <xref linkend="ssec-gc-roots"
|
||
/>.</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>
|
||
|
||
<para>By default, all unreachable paths are deleted. The following
|
||
options control what gets deleted and in what order:
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term>
|
||
|
||
<listitem><para>Keep deleting paths until at least
|
||
<replaceable>bytes</replaceable> bytes have been
|
||
deleted, then stop.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
<para>The behaviour of the collector is also 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>
|
||
|
||
<para>With <option>--delete</option>, the collector prints the total
|
||
number of freed bytes when it finishes (or when it is interrupted).
|
||
With <option>--print-dead</option>, it prints the number of bytes that
|
||
would be freed.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<para>To delete all unreachable paths, just do:
|
||
|
||
<screen>
|
||
$ nix-store --gc
|
||
deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
|
||
<replaceable>...</replaceable>
|
||
8825586 bytes freed (8.42 MiB)</screen>
|
||
|
||
</para>
|
||
|
||
<para>To delete at least 100 MiBs of unreachable paths:
|
||
|
||
<screen>
|
||
$ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--delete</option></title>
|
||
|
||
<refsection><title>Synopsis</title>
|
||
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--delete</option></arg>
|
||
<arg><option>--ignore-liveness</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--delete</option> deletes the store paths
|
||
<replaceable>paths</replaceable> from the Nix store, but only if it is
|
||
safe to do so; that is, when the path is not reachable from a root of
|
||
the garbage collector. This means that you can only delete paths that
|
||
would also be deleted by <literal>nix-store --gc</literal>. Thus,
|
||
<literal>--delete</literal> is a more targeted version of
|
||
<literal>--gc</literal>.</para>
|
||
|
||
<para>With the option <option>--ignore-liveness</option>, reachability
|
||
from the roots is ignored. However, the path still won’t be deleted
|
||
if there are other paths in the store that refer to it (i.e., depend
|
||
on it).</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4
|
||
0 bytes freed (0.00 MiB)
|
||
error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml:id='refsec-nix-store-query'><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>--outputs</option></arg>
|
||
<arg choice='plain'><option>--requisites</option></arg>
|
||
<arg choice='plain'><option>-R</option></arg>
|
||
<arg choice='plain'><option>--references</option></arg>
|
||
<arg choice='plain'><option>--referrers</option></arg>
|
||
<arg choice='plain'><option>--referrers-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>
|
||
<arg choice='plain'><option>--size</option></arg>
|
||
<arg choice='plain'><option>--roots</option></arg>
|
||
</group>
|
||
<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>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--query</option> displays various bits of
|
||
information about the store paths . The queries are described below. At
|
||
most one query can be specified. The default query is
|
||
<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>
|
||
|
||
|
||
<refsection><title>Common query options</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry><term><option>--use-output</option></term>
|
||
<term><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></term>
|
||
<term><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 xml:id='nixref-queries'><title>Queries</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry><term><option>--outputs</option></term>
|
||
|
||
<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></term>
|
||
<term><option>-R</option></term>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
|
||
<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>--referrers</option></term>
|
||
|
||
<listitem><para>Prints the set of <emphasis>referrers</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 referrers is not constant; it can change as
|
||
store paths are added or removed.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--referrers-closure</option></term>
|
||
|
||
<listitem><para>Prints the closure of the set of store paths
|
||
<replaceable>paths</replaceable> under the referrers 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 the references graph of the store paths
|
||
<replaceable>paths</replaceable> in the format of the
|
||
<command>dot</command> tool of AT&T's <link
|
||
xlink:href="http://www.graphviz.org/">Graphviz package</link>.
|
||
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 paths <replaceable>paths</replaceable> (that is, the hash of
|
||
the output of <command>nix-store --dump</command> on the given
|
||
paths). Since the hash is stored in the Nix database, this is a
|
||
fast operation.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--size</option></term>
|
||
|
||
<listitem><para>Prints the size in bytes of the contents of the
|
||
store paths <replaceable>paths</replaceable> — to be precise, the
|
||
size of the output of <command>nix-store --dump</command> on the
|
||
given paths. Note that the actual disk space required by the
|
||
store paths may be higher, especially on filesystems with large
|
||
cluster sizes.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--roots</option></term>
|
||
|
||
<listitem><para>Prints the garbage collector roots that point,
|
||
directly or indirectly, at the store paths
|
||
<replaceable>paths</replaceable>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</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/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
|
||
/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-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 --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
|
||
/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
|
||
/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-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 --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
|
||
/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
|
||
/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-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>
|
||
|
||
<para>Show every garbage collector root that points to a store path
|
||
that depends on <command>svn</command>:
|
||
|
||
<screen>
|
||
$ nix-store -q --roots $(which svn)
|
||
/nix/var/nix/profiles/default-81-link
|
||
/nix/var/nix/profiles/default-82-link
|
||
/nix/var/nix/profiles/per-user/eelco/profile-97-link
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<!--
|
||
<refsection xml:id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title>
|
||
|
||
<refsection><title>Synopsis</title>
|
||
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>-XXX-register-validity</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>TODO</para>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
-->
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--add</option></title>
|
||
|
||
<refsection><title>Synopsis</title>
|
||
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--add</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--add</option> adds the specified paths to
|
||
the Nix store. It prints the resulting paths in the Nix store on
|
||
standard output.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --add ./foo.c
|
||
/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--verify</option></arg>
|
||
<arg><option>--check-contents</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>
|
||
|
||
<para>There is one option:
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry><term><option>--check-contents</option></term>
|
||
|
||
<listitem><para>Checks that the contents of every valid store path
|
||
has not been altered by computing a SHA-256 hash of the contents
|
||
and comparing it with the hash stored in the Nix database at build
|
||
time. Paths that have been modified are printed out. For large
|
||
stores, <option>--check-contents</option> is obviously quite
|
||
slow.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--verify-path</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--verify-path</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--verify-paths</option> compares the
|
||
contents of the given store paths to their cryptographic hashes stored
|
||
in Nix’s database. For every changed path, it prints a warning
|
||
message. The exit status is 0 if no path has changed, and 1
|
||
otherwise.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<para>To verify the integrity of the <command>svn</command> command and all its dependencies:
|
||
|
||
<screen>
|
||
$ nix-store --verify-path $(nix-store -qR $(which svn))
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml:id='refsec-nix-store-dump'><title>Operation <option>--dump</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--dump</option></arg>
|
||
<arg choice='plain'><replaceable>path</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--dump</option> produces a NAR (Nix
|
||
ARchive) file containing the contents of the file system tree rooted
|
||
at <replaceable>path</replaceable>. The archive is written to
|
||
standard output.</para>
|
||
|
||
<para>A NAR archive is like a TAR or Zip archive, but it contains only
|
||
the information that Nix considers important. For instance,
|
||
timestamps are elided because all files in the Nix store have their
|
||
timestamp set to 0 anyway. Likewise, all permissions are left out
|
||
except for the execute bit, because all files in the Nix store have
|
||
644 or 755 permission.</para>
|
||
|
||
<para>Also, a NAR archive is <emphasis>canonical</emphasis>, meaning
|
||
that “equal” paths always produce the same NAR archive. For instance,
|
||
directory entries are always sorted so that the actual on-disk order
|
||
doesn’t influence the result. This means that the cryptographic hash
|
||
of a NAR dump of a path is usable as a fingerprint of the contents of
|
||
the path. Indeed, the hashes of store paths stored in Nix’s database
|
||
(see <link linkend="refsec-nix-store-query"><literal>nix-store -q
|
||
--hash</literal></link>) are SHA-256 hashes of the NAR dump of each
|
||
store path.</para>
|
||
|
||
<para>NAR archives support filenames of unlimited length and 64-bit
|
||
file sizes. They can contain regular files, directories, and symbolic
|
||
links, but not other types of files (such as device nodes).</para>
|
||
|
||
<para>A Nix archive can be unpacked using <literal>nix-store
|
||
--restore</literal>.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--restore</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--restore</option></arg>
|
||
<arg choice='plain'><replaceable>path</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--restore</option> unpacks a NAR archive
|
||
to <replaceable>path</replaceable>, which must not already exist. The
|
||
archive is read from standard input.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml:id='refsec-nix-store-export'><title>Operation <option>--export</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--export</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--export</option> writes a serialisation
|
||
of the specified store paths to standard output in a format that can
|
||
be imported into another Nix store with <command
|
||
linkend="refsec-nix-store-import">nix-store --import</command>. This
|
||
is like <command linkend="refsec-nix-store-dump">nix-store
|
||
--dump</command>, except that the NAR archive produced by that command
|
||
doesn’t contain the necessary meta-information to allow it to be
|
||
imported into another Nix store (namely, the set of references of the
|
||
path).</para>
|
||
|
||
<para>This command does not produce a <emphasis>closure</emphasis> of
|
||
the specified paths, so if a store path references other store paths
|
||
that are missing in the target Nix store, the import will fail. To
|
||
copy a whole closure, do something like
|
||
|
||
<screen>
|
||
$ nix-store --export $(nix-store -qR <replaceable>paths</replaceable>) > out</screen>
|
||
|
||
</para>
|
||
|
||
<para>For an example of how <option>--export</option> and
|
||
<option>--import</option> can be used, see the source of the <command
|
||
linkend="sec-nix-copy-closure">nix-copy-closure</command>
|
||
command.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection xml:id='refsec-nix-store-import'><title>Operation <option>--import</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--import</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--export</option> reads a serialisation of
|
||
a set of store paths produced by <command
|
||
linkend="refsec-nix-store-export">nix-store --import</command> from
|
||
standard input and adds those store paths to the Nix store. Paths
|
||
that already exist in the Nix store are ignored. If a path refers to
|
||
another path that doesn’t exist in the Nix store, the import
|
||
fails.</para>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--optimise</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--optimise</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--optimise</option> reduces Nix store disk
|
||
space usage by finding identical files in the store and hard-linking
|
||
them to each other. It typically reduces the size of the store by
|
||
something like 25-35%. Only regular files and symlinks are
|
||
hard-linked in this manner. Files are considered identical when they
|
||
have the same NAR archive serialisation: that is, regular files must
|
||
have the same contents and permission (executable or non-executable),
|
||
and symlinks must have the same contents.</para>
|
||
|
||
<para>After completion, or when the command is interrupted, a report
|
||
on the achieved savings is printed on standard error.</para>
|
||
|
||
<para>Use <option>-vv</option> or <option>-vvv</option> to get some
|
||
progress indication.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --optimise
|
||
hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
|
||
<replaceable>...</replaceable>
|
||
541838819 bytes (516.74 MiB) freed by hard-linking 54143 files;
|
||
there are 114486 files with equal contents out of 215894 files in total
|
||
</screen>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--read-log</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<group choice='req'>
|
||
<arg choice='plain'><option>--read-log</option></arg>
|
||
<arg choice='plain'><option>-l</option></arg>
|
||
</group>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--read-log</option> prints the build log
|
||
of the specified store paths on standard output. The build log is
|
||
whatever the builder of a derivation wrote to standard output and
|
||
standard error. If a store path is not a derivation, the deriver of
|
||
the store path is used.</para>
|
||
|
||
<para>Build logs are kept in
|
||
<filename>/nix/var/log/nix/drvs</filename>. However, there is no
|
||
guarantee that a build log is available for any particular store
|
||
path. For instance, if the path was downloaded as a pre-built binary
|
||
through a substitute, then the log is unavailable.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store -l $(which ktorrent)
|
||
building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1
|
||
unpacking sources
|
||
unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz
|
||
ktorrent-2.2.1/
|
||
ktorrent-2.2.1/NEWS
|
||
<replaceable>...</replaceable>
|
||
</screen>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--dump-db</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--dump-db</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--dump-db</option> writes a dump of the
|
||
Nix database to standard output. It can be loaded into an empty Nix
|
||
store using <option>--load-db</option>. This is useful for making
|
||
backups and when migrating to different database schemas.</para>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--load-db</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--load-db</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--load-db</option> reads a dump of the Nix
|
||
database created by <option>--dump-db</option> from standard input and
|
||
loads it into the Nix database.</para>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--print-env</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--print-env</option></arg>
|
||
<arg choice='plain'><replaceable>drvpath</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>The operation <option>--print-env</option> prints out the
|
||
environment of a derivation in a format that can be evaluated by a
|
||
shell. The command line arguments of the builder are placed in the
|
||
variable <envar>_args</envar>.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox)
|
||
<replaceable>…</replaceable>
|
||
export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
|
||
export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnm-stdenv'
|
||
export system; system='x86_64-linux'
|
||
export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25b-default-builder.sh'
|
||
</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--query-failed-paths</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--query-failed-paths</option></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>If build failure caching is enabled through the
|
||
<literal>build-cache-failures</literal> configuration option, the
|
||
operation <option>--query-failed-paths</option> will print out all
|
||
store paths that have failed to build.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --query-failed-paths
|
||
/nix/store/000zi5dcla86l92jn1g997jb06sidm7x-perl-PerlMagick-6.59
|
||
/nix/store/0011iy7sfwbc1qj5a1f6ifjnbcdail8a-haskell-gitit-ghc7.0.4-0.8.1
|
||
/nix/store/001c0yn1hkh86gprvrb46cxnz3pki7q3-gamin-0.1.10
|
||
<replaceable>…</replaceable>
|
||
</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--clear-failed-paths</option></title>
|
||
|
||
<refsection>
|
||
<title>Synopsis</title>
|
||
<cmdsynopsis>
|
||
<command>nix-store</command>
|
||
<arg choice='plain'><option>--clear-failed-paths</option></arg>
|
||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||
</cmdsynopsis>
|
||
</refsection>
|
||
|
||
<refsection><title>Description</title>
|
||
|
||
<para>If build failure caching is enabled through the
|
||
<literal>build-cache-failures</literal> configuration option, the
|
||
operation <option>--clear-failed-paths</option> clears the “failed”
|
||
state of the given store paths, allowing them to be built again. This
|
||
is useful if the failure was actually transient (e.g. because the disk
|
||
was full).</para>
|
||
|
||
<para>If a path denotes a derivation, its output paths are cleared.
|
||
You can provide the argument <literal>*</literal> to clear all store
|
||
paths.</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Example</title>
|
||
|
||
<screen>
|
||
$ nix-store --clear-failed-path /nix/store/000zi5dcla86l92jn1g997jb06sidm7x-perl-PerlMagick-6.59
|
||
$ nix-store --clear-failed-path *
|
||
</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection condition="manpage"><title>Environment variables</title>
|
||
|
||
<variablelist>
|
||
<xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refentry>
|