about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/command-ref/nix-store.xml
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/nix/doc/manual/command-ref/nix-store.xml')
-rw-r--r--third_party/nix/doc/manual/command-ref/nix-store.xml1525
1 files changed, 0 insertions, 1525 deletions
diff --git a/third_party/nix/doc/manual/command-ref/nix-store.xml b/third_party/nix/doc/manual/command-ref/nix-store.xml
deleted file mode 100644
index 113a3c2e41ed..000000000000
--- a/third_party/nix/doc/manual/command-ref/nix-store.xml
+++ /dev/null
@@ -1,1525 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      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
-  (successful) 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>The following flags are available:</para>
-
-<variablelist>
-
-  <varlistentry><term><option>--dry-run</option></term>
-
-    <listitem><para>Print on standard error a description of what
-    packages would be built or downloaded, without actually performing
-    the operation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--ignore-unknown</option></term>
-
-    <listitem><para>If a non-derivation path does not have a
-    substitute, then silently ignore it.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--check</option></term>
-
-    <listitem><para>This option allows you to check whether a
-    derivation is deterministic. It rebuilds the specified derivation
-    and checks whether the result is bitwise-identical with the
-    existing outputs, printing an error if that’s not the case. The
-    outputs of the specified derivation must already exist. When used
-    with <option>-K</option>, if an output path is not identical to
-    the corresponding output from the previous build, the new output
-    path is left in
-    <filename>/nix/store/<replaceable>name</replaceable>.check.</filename></para>
-
-    <para>See also the <option>build-repeat</option> configuration
-    option, which repeats a derivation a number of times and prevents
-    its outputs from being registered as “valid” in the Nix store
-    unless they are identical.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-<para>Special exit codes:</para>
-
-<variablelist>
-
-  <varlistentry><term><literal>100</literal></term>
-    <listitem><para>Generic build failure, the builder process
-    returned with a non-zero exit code.</para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>101</literal></term>
-    <listitem><para>Build timeout, the build was aborted because it
-    did not complete within the specified <link
-    linkend='conf-timeout'><literal>timeout</literal></link>.
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>102</literal></term>
-    <listitem><para>Hash mismatch, the build output was rejected
-    because it does not match the specified <link
-    linkend="fixed-output-drvs"><varname>outputHash</varname></link>.
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>104</literal></term>
-    <listitem><para>Not deterministic, the build succeeded in check
-    mode but the resulting output is not binary reproducable.</para>
-    </listitem>
-  </varlistentry>
-
-</variablelist>
-
-<para>With the <option>--keep-going</option> flag it's possible for
-multiple failures to occur, in this case the 1xx status codes are or combined
-using binary or. <screen>
-1100100
-   ^^^^
-   |||`- timeout
-   ||`-- output hash mismatch
-   |`--- build failure
-   `---- not deterministic
-</screen></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>
-
-<para>To test whether a previously-built derivation is deterministic:
-
-<screen>
-$ nix-build '&lt;nixpkgs>' -A hello --check -K
-</screen>
-
-</para>
-
-</refsection>
-
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection xml:id='rsec-nix-store-serve'><title>Operation <option>--serve</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-store</command>
-  <arg choice='plain'><option>--serve</option></arg>
-  <arg><option>--write</option></arg>
-</cmdsynopsis>
-
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The operation <option>--serve</option> provides access to
-the Nix store over stdin and stdout, and is intended to be used
-as a means of providing Nix store access to a restricted ssh user.
-</para>
-
-<para>The following flags are available:</para>
-
-<variablelist>
-
-  <varlistentry><term><option>--write</option></term>
-
-    <listitem><para>Allow the connected client to request the realization
-    of derivations. In effect, this can be used to make the host act
-    as a remote builder.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<para>To turn a host into a build server, the
-<filename>authorized_keys</filename> file can be used to provide build
-access to a given SSH public key:
-
-<screen>
-$ cat &lt;&lt;EOF >>/root/.ssh/authorized_keys
-command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
-EOF
-</screen>
-
-</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.  The argument <replaceable>bytes</replaceable> can be
-    followed by the multiplicative suffix <literal>K</literal>,
-    <literal>M</literal>, <literal>G</literal> or
-    <literal>T</literal>, denoting KiB, MiB, GiB or TiB
-    units.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</para>
-
-<para>The behaviour of the collector is also influenced by the <link
-linkend="conf-keep-outputs"><literal>keep-outputs</literal></link>
-and <link
-linkend="conf-keep-derivations"><literal>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>-d</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>-b</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>
-    <term><option>-d</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&amp;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>--graphml</option></term>
-
-    <listitem><para>Prints the references graph of the store paths
-    <replaceable>paths</replaceable> in the <link
-    xlink:href="http://graphml.graphdrawing.org/">GraphML</link> file format.
-    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>--binding</option> <replaceable>name</replaceable></term>
-    <term><option>-b</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><title>Operation <option>--add-fixed</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-store</command>
-  <arg><option>--recursive</option></arg>
-  <arg choice='plain'><option>--add-fixed</option></arg>
-  <arg choice='plain'><replaceable>algorithm</replaceable></arg>
-  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The operation <option>--add-fixed</option> adds the specified paths to
-the Nix store.  Unlike <option>--add</option> paths are registered using the
-specified hashing algorithm, resulting in the same output path as a fixed output
-derivation.  This can be used for sources that are not available from a public
-url or broke since the download expression was written.
-</para>
-
-<para>This operation has the following options:
-
-<variablelist>
-
-  <varlistentry><term><option>--recursive</option></term>
-
-    <listitem><para>
-      Use recursive instead of flat hashing mode, used when adding directories
-      to the store.
-    </para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</para>
-
-</refsection>
-
-<refsection><title>Example</title>
-
-<screen>
-$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
-/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz</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>
-    <arg><option>--repair</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>This operation has the following options:
-
-<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>
-
-  <varlistentry><term><option>--repair</option></term>
-
-    <listitem><para>If any valid path is missing from the store, or
-    (if <option>--check-contents</option> is given) the contents of a
-    valid path has been modified, then try to repair the path by
-    redownloading it.  See <command>nix-store --repair-path</command>
-    for details.</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-path</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><title>Operation <option>--repair-path</option></title>
-
-<refsection>
-  <title>Synopsis</title>
-  <cmdsynopsis>
-    <command>nix-store</command>
-    <arg choice='plain'><option>--repair-path</option></arg>
-    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-  </cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The operation <option>--repair-path</option> attempts to
-“repair” the specified paths by redownloading them using the available
-substituters.  If no substitutes are available, then repair is not
-possible.</para>
-
-<warning><para>During repair, there is a very small time window during
-which the old path (if it exists) is moved out of the way and replaced
-with the new path.  If repair is interrupted in between, then the
-system may be left in a broken state (e.g., if the path contains a
-critical system component like the GNU C Library).</para></warning>
-
-</refsection>
-
-<refsection><title>Example</title>
-
-<screen>
-$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
-path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
-  expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
-  got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
-
-$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
-fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
-…
-</screen>
-
-</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>
-
-To import the whole closure again, run:
-
-<screen>
-$ nix-store --import &lt; out</screen>
-
-</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>--import</option> reads a serialisation of
-a set of store paths produced by <command
-linkend="refsec-nix-store-export">nix-store --export</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>
-    <arg rep='repeat'><replaceable>paths</replaceable></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>
-
-<para>By default, <option>--dump-db</option> will dump the entire Nix
-database.  When one or more store paths is passed, only the subset of
-the Nix database for those store paths is dumped.  As with
-<option>--export</option>, the user is responsible for passing all the
-store paths for a closure.  See <option>--export</option> for an
-example.</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 '&lt;nixpkgs>' -A firefox)
-<replaceable>…</replaceable>
-export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
-export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
-export system; system='x86_64-linux'
-export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
-</screen>
-
-</refsection>
-
-</refsection>
-
-
-<!--######################################################################-->
-
-<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title>
-
-<refsection>
-  <title>Synopsis</title>
-  <cmdsynopsis>
-    <command>nix-store</command>
-    <arg choice='plain'>
-      <option>--generate-binary-cache-key</option>
-      <option>key-name</option>
-      <option>secret-key-file</option>
-      <option>public-key-file</option>
-    </arg>
-  </cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>This command generates an <link
-xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can
-be used to create a signed binary cache. It takes three mandatory
-parameters:
-
-<orderedlist>
-
-  <listitem><para>A key name, such as
-  <literal>cache.example.org-1</literal>, that is used to look up keys
-  on the client when it verifies signatures. It can be anything, but
-  it’s suggested to use the host name of your cache
-  (e.g. <literal>cache.example.org</literal>) with a suffix denoting
-  the number of the key (to be incremented every time you need to
-  revoke a key).</para></listitem>
-
-  <listitem><para>The file name where the secret key is to be
-  stored.</para></listitem>
-
-  <listitem><para>The file name where the public key is to be
-  stored.</para></listitem>
-
-</orderedlist>
-
-</para>
-
-</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>