diff options
Diffstat (limited to 'doc/manual/nix-store.xml')
| -rw-r--r-- | doc/manual/nix-store.xml | 86 |
1 files changed, 61 insertions, 25 deletions
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index d9ef17e26ec3..c67e20266ff5 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -45,7 +45,7 @@ linkend="sec-common-options" /> for a list of common options.</para> <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term> - <listitem><para>Causes the result of a build action + <listitem><para>Causes the result of a realisation (<option>--realise</option> and <option>--force-realise</option>) to be registered as a root of the garbage collector (see <xref linkend="ssec-gc-roots" />). The root is stored in @@ -54,7 +54,12 @@ linkend="sec-common-options" /> for a list of common options.</para> typically in a subdirectory of <filename>/nix/var/nix/gcroots/</filename>) <emphasis>unless</emphasis> the <option>--indirect</option> flag - is used.</para></listitem> + 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> @@ -121,25 +126,56 @@ lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134 <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> +<para>The operation <option>--realise</option> essentially “builds” +the specified store paths. Realisation is a somewhat overloaded term: + +<itemizedlist> + + <listitem><para>If the store path is a + <emphasis>derivation</emphasis>, realisation ensures that the output + paths of the derivation are <link + linkend="gloss-validity">valid</link> (i.e., the output path and its + closure exist in the file system). This can be done in several + ways. First, it is possible that the outputs are already valid, in + which case we are done immediately. Otherwise, there may be <link + linkend="gloss-substitute">substitutes</link> that produce the + outputs (e.g., by downloading them). Finally, the outputs can be + produced by performing the build action described by the + derivation.</para></listitem> + + <listitem><para>If the store path is not a derivation, realisation + ensures that the specified path is valid (i.e., it and its closure + exist in the file system). If the path is already valid, we are + done immediately. Otherwise, the path and any missing paths in its + closure may be produced through substitutes. If there are no + (succesful) subsitutes, realisation fails.</para></listitem> + +</itemizedlist> + +</para> + +<para>The output path of each derivation is printed on standard +output. (For non-derivations argument, the argument itself is +printed.)</para> </refsection> + +<refsection><title>Examples</title> + +<para>This operation is typically used to build store derivations +produced by <link +linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>: + +<screen> +$ nix-store -r $(nix-instantiate ./foo.nix)</screen> + +This is essentially what <link +linkend="sec-nix-build"><command>nix-build</command></link> does.</para> + +</refsection> + + </refsection> @@ -168,7 +204,7 @@ output.</para> <para>Without additional flags, the operation <option>--gc</option> performs a garbage collection on the Nix store. That is, all paths in the Nix store not reachable via file system references from a set of -<quote>roots</quote>, are deleted.</para> +“roots”, are deleted.</para> <para>The following suboperations may be specified:</para> @@ -184,9 +220,9 @@ the Nix store not reachable via file system references from a set of <varlistentry><term><option>--print-live</option></term> <listitem><para>This operation prints on standard output the set - of <quote>live</quote> store paths, which are all the store paths - reachable from the roots. Live paths should never be deleted, - since that would break consistency — it would become possible that + 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> @@ -195,9 +231,9 @@ the Nix store not reachable via file system references from a set of <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> + 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> |