88 lines
3.8 KiB
XML
88 lines
3.8 KiB
XML
<section 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-building-simple'>
|
||
|
||
<title>Building and Testing</title>
|
||
|
||
<para>You can now try to build Hello. Of course, you could do
|
||
<literal>nix-env -f pkgs/top-level/all-packages.nix -i hello</literal>,
|
||
but you may not want to install a possibly broken package just yet.
|
||
The best way to test the package is by using the command <command
|
||
linkend="sec-nix-build">nix-build</command>, which builds a Nix
|
||
expression and creates a symlink named <filename>result</filename> in
|
||
the current directory:
|
||
|
||
<screen>
|
||
$ nix-build pkgs/top-level/all-packages.nix -A hello
|
||
building path `/nix/store/632d2b22514d...-hello-2.1.1'
|
||
hello-2.1.1/
|
||
hello-2.1.1/intl/
|
||
hello-2.1.1/intl/ChangeLog
|
||
<replaceable>...</replaceable>
|
||
|
||
$ ls -l result
|
||
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
|
||
|
||
$ ./result/bin/hello
|
||
Hello, world!</screen>
|
||
|
||
The <link linkend='opt-attr'><option>-A</option></link> option selects
|
||
the <literal>hello</literal> attribute from
|
||
<filename>all-packages.nix</filename>. This is faster than using the
|
||
symbolic package name specified by the <literal>name</literal>
|
||
attribute (which also happens to be <literal>hello</literal>) and is
|
||
unambiguous (there can be multiple packages with the symbolic name
|
||
<literal>hello</literal>, but there can be only one attribute in a set
|
||
named <literal>hello</literal>).</para>
|
||
|
||
<para><command>nix-build</command> registers the
|
||
<filename>./result</filename> symlink as a garbage collection root, so
|
||
unless and until you delete the <filename>./result</filename> symlink,
|
||
the output of the build will be safely kept on your system. You can
|
||
use <command>nix-build</command>’s <option
|
||
linkend='opt-out-link'>-o</option> switch to give the symlink another
|
||
name.</para>
|
||
|
||
<para>Nix has a transactional semantics. Once a build finishes
|
||
successfully, Nix makes a note of this in its database: it registers
|
||
that the path denoted by <envar>out</envar> is now
|
||
<quote>valid</quote>. If you try to build the derivation again, Nix
|
||
will see that the path is already valid and finish immediately. If a
|
||
build fails, either because it returns a non-zero exit code, because
|
||
Nix or the builder are killed, or because the machine crashes, then
|
||
the output paths will not be registered as valid. If you try to build
|
||
the derivation again, Nix will remove the output paths if they exist
|
||
(e.g., because the builder died half-way through <literal>make
|
||
install</literal>) and try again. Note that there is no
|
||
<quote>negative caching</quote>: Nix doesn't remember that a build
|
||
failed, and so a failed build can always be repeated. This is because
|
||
Nix cannot distinguish between permanent failures (e.g., a compiler
|
||
error due to a syntax error in the source) and transient failures
|
||
(e.g., a disk full condition).</para>
|
||
|
||
<para>Nix also performs locking. If you run multiple Nix builds
|
||
simultaneously, and they try to build the same derivation, the first
|
||
Nix instance that gets there will perform the build, while the others
|
||
block (or perform other derivations if available) until the build
|
||
finishes:
|
||
|
||
<screen>
|
||
$ nix-build pkgs/top-level/all-packages.nix -A hello
|
||
waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</screen>
|
||
|
||
So it is always safe to run multiple instances of Nix in parallel
|
||
(which isn’t the case with, say, <command>make</command>).</para>
|
||
|
||
<para>If you have a system with multiple CPUs, you may want to have
|
||
Nix build different derivations in parallel (insofar as possible).
|
||
Just pass the option <link linkend='opt-max-jobs'><option>-j
|
||
<replaceable>N</replaceable></option></link>, where
|
||
<replaceable>N</replaceable> is the maximum number of jobs to be run
|
||
in parallel, or set. Typically this should be the number of
|
||
CPUs.</para>
|
||
|
||
<xi:include href="debug-build.xml" />
|
||
|
||
</section>
|