eb233e728f
unreachable paths that haven't been used for N hours. For instance, `nix-collect-garbage --min-age 168' only deletes paths that haven't been accessed in the last week. This is useful for instance in the build farm where many derivations can be shared between consecutive builds, and we wouldn't want a garbage collect to throw them all away. We could of course register them as roots, but then we'd to unregister them at some point, which would be a pain to manage. The `--min-age' flag gives us a sort of MRU caching scheme. BUG: this really shouldn't be in gc.cc since that violates mechanism/policy separation.
563 lines
18 KiB
XML
563 lines
18 KiB
XML
<refentry>
|
|
<refnamediv>
|
|
<refname>nix-store</refname>
|
|
<refpurpose>manipulate or query the Nix store</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>nix-store</command>
|
|
&opt-common-syn;
|
|
<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.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
&opt-common;
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection>
|
|
<title>Environment variables</title>
|
|
|
|
<para>
|
|
The following environment variables affect the behaviour of
|
|
<command>nix-store</command>.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><envar>TMPDIR</envar>=<replaceable>path</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Use the directory <replaceable>path</replaceable> to store
|
|
temporary files. In particular, this includes temporary
|
|
build directories; these can take up substantial amounts
|
|
of disk space. The default is <filename>/tmp</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
|
|
|
|
<!--######################################################################-->
|
|
|
|
<refsection>
|
|
<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>
|
|
The operation <option>--gc</option> performs a garbage
|
|
collection on the Nix store. What it does specifically is
|
|
determined by the sub-operation, which is one of the
|
|
following:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<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 a set of <quote>root</quote> store
|
|
expressions read from standard input. 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>
|
|
|
|
<para>
|
|
The set of root store expressions is read from standard input.
|
|
Each line should contain exactly one store path.
|
|
</para>
|
|
|
|
<para>
|
|
The option <option>--min-age</option> specifies a minimum time
|
|
in hours that an unreachable store path must not have been
|
|
used before it is considered dead. The default is 0 (consider
|
|
all unreachable store paths dead). Whether a store path has
|
|
been used is determined by looking at its access time
|
|
(<literal>atime</literal>), so this does not work if the store
|
|
is located on a file system that has the
|
|
<literal>noatime</literal> option set.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>
|
|
You generally will want to use the command
|
|
<command>nix-collect-garbage</command>, which figures out
|
|
the roots and then calls this command automatically.
|
|
</para>
|
|
</warning>
|
|
|
|
</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:
|
|
-->
|