* Manual updates (especially how nix-build makes testing packages much

easier; no longer need a helper expression).
This commit is contained in:
Eelco Dolstra 2006-10-02 11:50:55 +00:00
parent 91a01e6fcf
commit f316b6c1a9
5 changed files with 120 additions and 81 deletions

View file

@ -25,6 +25,7 @@ env-keep-derivations = false
<variablelist> <variablelist>
<varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term> <varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
<listitem><para>If <literal>true</literal>, the garbage collector <listitem><para>If <literal>true</literal>, the garbage collector
@ -41,6 +42,7 @@ env-keep-derivations = false
</varlistentry> </varlistentry>
<varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term> <varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
<listitem><para>If <literal>true</literal> (default), the garbage <listitem><para>If <literal>true</literal> (default), the garbage
@ -57,6 +59,7 @@ env-keep-derivations = false
</varlistentry> </varlistentry>
<varlistentry xml:id="conf-gc-reserved-space"><term><literal>gc-reserved-space</literal></term> <varlistentry xml:id="conf-gc-reserved-space"><term><literal>gc-reserved-space</literal></term>
<listitem><para>This option specifies how much space should be <listitem><para>This option specifies how much space should be
@ -77,6 +80,7 @@ env-keep-derivations = false
</varlistentry> </varlistentry>
<varlistentry><term><literal>env-keep-derivations</literal></term> <varlistentry><term><literal>env-keep-derivations</literal></term>
<listitem><para>If <literal>false</literal> (default), derivations <listitem><para>If <literal>false</literal> (default), derivations
@ -100,6 +104,21 @@ env-keep-derivations = false
</varlistentry> </varlistentry>
<varlistentry xml:id="conf-build-max-jobs"><term><literal>build-max-jobs</literal></term>
<listitem><para>This option defines the maximum number of jobs
that Nix will try to build in parallel. The default is
<literal>1</literal>. You should generally set it to the number
of CPUs in your system (e.g., <literal>2</literal> on a Athlon 64
X2). It can be overriden using the <option
linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
command line switch.</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>

View file

@ -10,7 +10,15 @@
<cmdsynopsis> <cmdsynopsis>
<command>nix-build</command> <command>nix-build</command>
<arg><option>--add-drv-link</option></arg> <arg><option>--add-drv-link</option></arg>
<arg><option>--no-link</option></arg> <arg><option>--drv-link </option><replaceable>drvlink</replaceable></arg>
<arg><option>--no-out-link</option></arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--out-link</option></arg>
<arg choice='plain'><option>-o</option></arg>
</group>
<replaceable>outlink</replaceable>
</arg>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -30,14 +38,13 @@ and so on).</para>
<command>nix-build</command> will use <filename>default.nix</filename> <command>nix-build</command> will use <filename>default.nix</filename>
in the current directory, if it exists.</para> in the current directory, if it exists.</para>
<note><para><command>nix-build</command> is essentially a wrapper <para><command>nix-build</command> is essentially a wrapper around
around <link <link
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link> linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
(to translate a high-level Nix expression to a low-level store (to translate a high-level Nix expression to a low-level store
derivation) and <link derivation) and <link
linkend="rsec-nix-store-realise"><command>nix-store linkend="rsec-nix-store-realise"><command>nix-store
--realise</command></link> (to build the store --realise</command></link> (to build the store derivation).</para>
derivation).</para></note>
<warning><para>The result of the build is automatically registered as <warning><para>The result of the build is automatically registered as
a root of the Nix garbage collector. This root disappears a root of the Nix garbage collector. This root disappears
@ -62,7 +69,16 @@ or renamed. So dont rename the symlink.</para></warning>
</varlistentry> </varlistentry>
<varlistentry><term><option>--no-link</option></term> <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
<listitem><para>Change the name of the symlink to the derivation
created when <option>--add-drv-link</option> is used from
<filename>derivation</filename> to
<replaceable>drvlink</replaceable>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--no-out-link</option></term>
<listitem><para>Do not create a symlink to the output path. Note <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 that as a result the output does not become a root of the garbage
@ -71,6 +87,16 @@ or renamed. So dont rename the symlink.</para></warning>
</varlistentry> </varlistentry>
<varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
<option>-o</option> <replaceable>outlink</replaceable></term>
<listitem><para>Change the name of the symlink to the output path
created unless <option>--no-out-link</option> is used from
<filename>result</filename> to
<replaceable>outlink</replaceable>.</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</refsection> </refsection>

View file

@ -514,8 +514,9 @@ then you should unsubscribe from the offending channel
<replaceable>URL</replaceable></command>; leave out <replaceable>URL</replaceable></command>; leave out
<literal>/MANIFEST</literal>), and subscribe to the same URL, with <literal>/MANIFEST</literal>), and subscribe to the same URL, with
<literal>channels</literal> replaced by <literal>channels-v3</literal> <literal>channels</literal> replaced by <literal>channels-v3</literal>
(e.g., (e.g., <link
http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable).</para> xlink:href='http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable'
/>).</para>
<para>Nix 0.8 has the following improvements: <para>Nix 0.8 has the following improvements:
@ -524,8 +525,9 @@ http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable).</para>
<listitem><para>The cryptographic hashes used in store paths are now <listitem><para>The cryptographic hashes used in store paths are now
160 bits long, but encoded in base-32 so that they are still only 32 160 bits long, but encoded in base-32 so that they are still only 32
characters long (e.g., characters long (e.g.,
/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0). (This is <filename>/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</filename>).
actually a 160 bit truncation of a SHA-256 hash.)</para></listitem> (This is actually a 160 bit truncation of a SHA-256
hash.)</para></listitem>
<listitem><para>Big cleanups and simplifications of the basic store <listitem><para>Big cleanups and simplifications of the basic store
semantics. The notion of "closure store expressions" is gone (and semantics. The notion of "closure store expressions" is gone (and
@ -583,8 +585,9 @@ $ nix-store -q --referrers-closure \
<listitem><para>One-click installation :-) It is now possible to <listitem><para>One-click installation :-) It is now possible to
install any top-level component in Nixpkgs directly, through the web install any top-level component in Nixpkgs directly, through the web
- see, e.g., http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/. All - see, e.g., <link
you have to do is associate xlink:href='http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/' />.
All you have to do is associate
<filename>/nix/bin/nix-install-package</filename> with the MIME type <filename>/nix/bin/nix-install-package</filename> with the MIME type
<literal>application/nix-package</literal> (or the extension <literal>application/nix-package</literal> (or the extension
<filename>.nixpkg</filename>), and clicking on a package link will <filename>.nixpkg</filename>), and clicking on a package link will
@ -740,7 +743,7 @@ $ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'</screen>
mechanism.</para></listitem> mechanism.</para></listitem>
<listitem><para>Nix-pull now stores downloaded manifests in <listitem><para>Nix-pull now stores downloaded manifests in
/nix/var/nix/manifests.</para></listitem> <filename>/nix/var/nix/manifests</filename>.</para></listitem>
<listitem><para>Metadata on files in the Nix store is canonicalised <listitem><para>Metadata on files in the Nix store is canonicalised
after builds: the last-modified timestamp is set to 0 (00:00:00 after builds: the last-modified timestamp is set to 0 (00:00:00

View file

@ -83,7 +83,7 @@ pre.programlisting
Screen dumps: Screen dumps:
***************************************************************************/ ***************************************************************************/
pre.screen pre.screen, pre.programlisting
{ {
border: 1px solid #6185a0; border: 1px solid #6185a0;
padding: 3px 3px; padding: 3px 3px;
@ -260,3 +260,8 @@ strong.command
// font-weight: normal; // font-weight: normal;
color: #400000; color: #400000;
} }
div.calloutlist td
{
padding-bottom: 1em;
}

View file

@ -35,7 +35,7 @@ need to do three things:
the inputs.</para></listitem> the inputs.</para></listitem>
<listitem><para>Add the component to the file <listitem><para>Add the component to the file
<filename>pkgs/system/all-packages-generic.nix</filename>. The Nix <filename>pkgs/top-level/all-packages.nix</filename>. The Nix
expression written in the first step is a expression written in the first step is a
<emphasis>function</emphasis>; it requires other components in order <emphasis>function</emphasis>; it requires other components in order
to build it. In this step you put it all together, i.e., you call to build it. In this step you put it all together, i.e., you call
@ -309,7 +309,7 @@ error check.</para>
<section><title>Composition</title> <section><title>Composition</title>
<example xml:id='ex-hello-composition'><title>Composing GNU Hello <example xml:id='ex-hello-composition'><title>Composing GNU Hello
(<filename>all-packages-generic.nix</filename>)</title> (<filename>all-packages.nix</filename>)</title>
<programlisting> <programlisting>
... ...
@ -336,11 +336,11 @@ rec { <co xml:id='ex-hello-composition-co-1' />
<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a <para>The Nix expression in <xref linkend='ex-hello-nix' /> is a
function; it is missing some arguments that have to be filled in function; it is missing some arguments that have to be filled in
somewhere. In the Nix Packages collection this is done in the file somewhere. In the Nix Packages collection this is done in the file
<filename>pkgs/system/all-packages-generic.nix</filename>, where all <filename>pkgs/top-level/all-packages.nix</filename>, where all
Nix expressions for components are imported and called with the Nix expressions for components are imported and called with the
appropriate arguments. <xref linkend='ex-hello-composition' /> shows appropriate arguments. <xref linkend='ex-hello-composition' /> shows
some fragments of some fragments of
<filename>all-packages-generic.nix</filename>.</para> <filename>all-packages.nix</filename>.</para>
<calloutlist> <calloutlist>
@ -361,7 +361,7 @@ some fragments of
GNU Hello. The import operation just loads and returns the GNU Hello. The import operation just loads and returns the
specified Nix expression. In fact, we could just have put the specified Nix expression. In fact, we could just have put the
contents of <xref linkend='ex-hello-nix' /> in contents of <xref linkend='ex-hello-nix' /> in
<filename>all-packages-generic.nix</filename> at this point. That <filename>all-packages.nix</filename> at this point. That
would be completely equivalent, but it would make the file rather would be completely equivalent, but it would make the file rather
bulky.</para> bulky.</para>
@ -406,71 +406,38 @@ some fragments of
<section><title>Testing</title> <section><title>Testing</title>
<para>You can now try to build Hello. The simplest way to do that is <para>You can now try to build Hello. Of course, you could do
by using <command>nix-env</command>: <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> <screen>
$ nix-env -f pkgs/system/i686-linux.nix -i hello $ nix-build pkgs/top-level/all-packages.nix -A hello
installing `hello-2.1.1' building path `/nix/store/632d2b22514d...-hello-2.1.1'
building path `/nix/store/632d2b22514dcebe704887c3da15448d-hello-2.1.1'
hello-2.1.1/ hello-2.1.1/
hello-2.1.1/intl/ hello-2.1.1/intl/
hello-2.1.1/intl/ChangeLog hello-2.1.1/intl/ChangeLog
<replaceable>...</replaceable> <replaceable>...</replaceable>
</screen>
This will build Hello and install it into your profile. The file $ ls -l result
<filename>i686-linux</filename> is just a simple Nix expression that lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
imports <filename>all-packages-generic.nix</filename> and instantiates
it for Linux on the x86 platform.</para>
<para>Note that the <literal>hello</literal> argument here refers to
the symbolic name given to the Hello derivation (the
<varname>name</varname> attribute in <xref linkend='ex-hello-nix' />),
<emphasis>not</emphasis> the <varname>hello</varname> attribute in
<filename>all-packages-generic.nix</filename>.
<command>nix-env</command> simply walks through all derivations
defined in the latter file, looking for one with a
<varname>name</varname> attribute matching the command-line
argument.</para>
<para>You can test whether it works:
<screen>
$ hello
Hello, world!</screen>
</para>
<para>Generally, however, using <command>nix-env</command> is not the
best way to test components, since you may not want to install them
into your profile right away (they might not work properly, after
all). A better way is to write a short file containing the
following:
<programlisting>
(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 <link
linkend="sec-nix-build"><command>nix-build</command></link>:
<screen>
$ nix-build ./test.nix
...
/nix/store/632d2b22514dcebe704887c3da15448d-hello-2.1.1</screen>
<command>nix-build</command> will build the derivation and print the
output path. It also creates a symlink to the output path called
<filename>result</filename> in the current directory. This is
convenient for testing the component:
<screen>
$ ./result/bin/hello $ ./result/bin/hello
Hello, world!</screen> Hello, world!</screen>
</para> </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 <para>Nix has a transactional semantics. Once a build finishes
successfully, Nix makes a note of this in its database: it registers successfully, Nix makes a note of this in its database: it registers
that the path denoted by <envar>out</envar> is now that the path denoted by <envar>out</envar> is now
@ -492,14 +459,22 @@ error due to a syntax error in the source) and transient failures
simultaneously, and they try to build the same derivation, the first simultaneously, and they try to build the same derivation, the first
Nix instance that gets there will perform the build, while the others Nix instance that gets there will perform the build, while the others
block (or perform other derivations if available) until the build block (or perform other derivations if available) until the build
finishes. So it is always safe to run multiple instances of Nix in finishes:
parallel (contrary to, say, <command>make</command>).</para>
<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 isnt the case with, say, <command>make</command>).</para>
<para>If you have a system with multiple CPUs, you may want to have <para>If you have a system with multiple CPUs, you may want to have
Nix build different derivations in parallel (insofar as possible). Nix build different derivations in parallel (insofar as possible).
Just pass the option <option>-j <replaceable>N</replaceable></option>, Just pass the option <option linkend='opt-max-jobs'>-j
where <replaceable>N</replaceable> is the maximum number of jobs to be <replaceable>N</replaceable></option>, where
run in parallel. Typically this should be the number of CPUs.</para> <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> </section>
@ -794,7 +769,7 @@ evaluates to <literal>{x = 123; y = 456;}</literal>. (Note that this
works because <varname>x</varname> is added to the lexical scope by works because <varname>x</varname> is added to the lexical scope by
the <literal>let</literal> construct.) It is also possible to inherit the <literal>let</literal> construct.) It is also possible to inherit
attributes from another attribute set. For instance, in this fragment attributes from another attribute set. For instance, in this fragment
from <filename>all-packages-generic.nix</filename>, from <filename>all-packages.nix</filename>,
<programlisting> <programlisting>
graphviz = (import ../tools/graphics/graphviz) { graphviz = (import ../tools/graphics/graphviz) {
@ -1392,6 +1367,13 @@ builds for any type of component. It is advisable to use
are almost always useful such as unpacking of sources, patching of are almost always useful such as unpacking of sources, patching of
sources, nested logging, etc.</para> sources, nested logging, etc.</para>
<para>The definitive, up-to-date documentation of the generic builder
is the source itself, which resides in
<filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
<section><title>Customising the generic builder</title>
<para>The operation of the generic builder can be modified in many <para>The operation of the generic builder can be modified in many
places by setting certain variables. These <emphasis>hook places by setting certain variables. These <emphasis>hook
variables</emphasis> are typically set to the name of some shell variables</emphasis> are typically set to the name of some shell
@ -1519,6 +1501,11 @@ new phases, by setting the <varname>phases</varname> variable. The
default is <literal>patchPhase configurePhase buildPhase checkPhase default is <literal>patchPhase configurePhase buildPhase checkPhase
installPhase distPhase</literal>.</para> installPhase distPhase</literal>.</para>
</section>
<section><title>Debugging failed builds</title>
<para>At the beginning of each phase, the set of all shell variables <para>At the beginning of each phase, the set of all shell variables
is written to the file <filename>env-vars</filename> at the top-level is written to the file <filename>env-vars</filename> at the top-level
build directory. This is useful for debugging: it allows you to build directory. This is useful for debugging: it allows you to
@ -1543,9 +1530,8 @@ $ make
</para> </para>
<para>The definitive, up-to-date documentation of the generic builder </section>
is the source itself, which resides in
<filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
</section> </section>