diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/manual/glossary.xml | 12 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 6 | ||||
| -rw-r--r-- | doc/manual/nix-build.xml | 72 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 86 | ||||
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 3 |
6 files changed, 154 insertions, 30 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index f5dfdb1dd876..60853df05dfa 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -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 diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml index cf0da38245b1..c3dc36fb3f2f 100644 --- a/doc/manual/glossary.xml +++ b/doc/manual/glossary.xml @@ -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> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 9f0e4ae94c50..b71798e80ac9 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -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> diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml new file mode 100644 index 000000000000..2a5af6adb3d7 --- /dev/null +++ b/doc/manual/nix-build.xml @@ -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> 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> diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 1b177c7dab6b..a664f1e3256e 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -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 |