<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 -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 -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.  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 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 -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>

</section>