forked from lix-project/lix
* More manual updates.
This commit is contained in:
parent
f1ae10b992
commit
57d023a184
|
@ -5,9 +5,10 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
|
|||
--param section.autolabel 1 \
|
||||
--param section.label.includes.component.label 1 \
|
||||
--param html.stylesheet \'style.css\' \
|
||||
--param xref.with.number.and.title 0
|
||||
--param xref.with.number.and.title 0 \
|
||||
--param toc.section.depth 3
|
||||
|
||||
man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1 \
|
||||
man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
|
||||
nix-collect-garbage.1 nix-push.1 nix-pull.1 \
|
||||
nix-prefetch-url.1
|
||||
|
||||
|
|
|
@ -46,7 +46,7 @@
|
|||
</glossentry>
|
||||
|
||||
|
||||
<glossentry><glossterm>substitute</glossterm>
|
||||
<glossentry id="gloss-substitute"><glossterm>substitute</glossterm>
|
||||
|
||||
<glossdef><para>A substitute is a command invocation stored in the
|
||||
Nix database that describes how to build a store object, bypassing
|
||||
|
@ -94,6 +94,16 @@
|
|||
</glossentry>
|
||||
|
||||
|
||||
<glossentry id="gloss-validity"><glossterm>validity</glossterm>
|
||||
|
||||
<glossdef><para>A store path is considered
|
||||
<emphasis>valid</emphasis> if it exists in the file system, is
|
||||
listed in the Nix database as being valid, and if all paths in its
|
||||
closure are also valid.</para></glossdef>
|
||||
|
||||
</glossentry>
|
||||
|
||||
|
||||
</glosslist>
|
||||
|
||||
|
||||
|
|
|
@ -39,11 +39,15 @@
|
|||
<title>nix-env</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
|
||||
</sect1>
|
||||
<sect1 id="sec-nix-build">
|
||||
<title>nix-build</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-build.xml" />
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title>nix-store</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-store.xml" />
|
||||
</sect1>
|
||||
<sect1>
|
||||
<sect1 id="sec-nix-instantiate">
|
||||
<title>nix-instantiate</title>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-instantiate.xml" />
|
||||
</sect1>
|
||||
|
|
72
doc/manual/nix-build.xml
Normal file
72
doc/manual/nix-build.xml
Normal file
|
@ -0,0 +1,72 @@
|
|||
<refentry>
|
||||
|
||||
<refnamediv>
|
||||
<refname>nix-build</refname>
|
||||
<refpurpose>build a Nix expression</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>nix-build</command>
|
||||
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsection><title>Description</title>
|
||||
|
||||
<para>The <command>nix-build</command> command builds the derivations
|
||||
described by the Nix expressions in <replaceable>paths</replaceable>.
|
||||
If the build succeeds, it places a symlink to the result in the
|
||||
current directory. The symlink is called <filename>result</filename>.
|
||||
If there are multiple Nix expressions, or the Nix expressions evaluate
|
||||
to multiple derivations, multiple sequentially numbered symlinks are
|
||||
created (<filename>result</filename>, <filename>result-2</filename>,
|
||||
and so on).</para>
|
||||
|
||||
<note><para><command>nix-build</command> is essentially a wrapper
|
||||
around <link
|
||||
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
|
||||
(to translate a high-level Nix expression to a low-level store
|
||||
derivation) and <link
|
||||
linkend="rsec-nix-store-realise"><command>nix-store
|
||||
--realise</command></link> (to build the store
|
||||
derivation).</para></note>
|
||||
|
||||
<warning><para>The result of the build is automatically registered as
|
||||
a root of the Nix garbage collector. This root disappears
|
||||
automatically when the <filename>result</filename> symlink is deleted
|
||||
or renamed. So don’t rename the symlink.</para></warning>
|
||||
|
||||
</refsection>
|
||||
|
||||
|
||||
<refsection><title>Options</title>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term><option>--add-drv-link</option></term>
|
||||
|
||||
<listitem><para>Add a symlink in the current directory to the
|
||||
store derivation produced by <command>nix-instantiate</command>.
|
||||
The symlink is called <filename>derivation</filename> (which is
|
||||
numbered in the case of multiple derivations). The derivation is
|
||||
a root of the garbage collector until the symlink is deleted or
|
||||
renamed.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><option>--no-link</option></term>
|
||||
|
||||
<listitem><para>Do not create a symlink to the output path. Note
|
||||
that as a result the output does not become a root of the garbage
|
||||
collector, and so might be deleted by <command>nix-store
|
||||
--gc</command>.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsection>
|
||||
|
||||
|
||||
</refentry>
|
|
@ -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 operation <option>--realise</option> essentially “builds”
|
||||
the specified store paths. Realisation is a somewhat overloaded term:
|
||||
|
||||
<para>The paths of the closure expression corresponding to each
|
||||
expression in <replaceable>paths</replaceable> is printed on standard
|
||||
output.</para>
|
||||
<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>
|
||||
|
||||
|
|
|
@ -447,7 +447,8 @@ following:
|
|||
(import pkgs/system/i686-linux.nix).hello</programlisting>
|
||||
|
||||
Call it <filename>test.nix</filename>. You can then build it without
|
||||
installing it using the command <command>nix-build</command>:
|
||||
installing it using the command <link
|
||||
linkend="sec-nix-build"><command>nix-build</command></link>:
|
||||
|
||||
<screen>
|
||||
$ nix-build ./test.nix
|
||||
|
|
Loading…
Reference in a new issue