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