forked from lix-project/lix
* Manual updates (especially how nix-build makes testing packages much
easier; no longer need a helper expression).
This commit is contained in:
Eelco Dolstra
parent
91a01e6fcf
commit
f316b6c1a9
|
|
@ -25,6 +25,7 @@ env-keep-derivations = false
|
|||
|
||||
<variablelist>
|
||||
|
||||
|
||||
<varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
|
||||
|
||||
<listitem><para>If <literal>true</literal>, the garbage collector
|
||||
|
|
@ -41,6 +42,7 @@ env-keep-derivations = false
|
|||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
|
||||
|
||||
<listitem><para>If <literal>true</literal> (default), the garbage
|
||||
|
|
@ -57,6 +59,7 @@ env-keep-derivations = false
|
|||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry xml:id="conf-gc-reserved-space"><term><literal>gc-reserved-space</literal></term>
|
||||
|
||||
<listitem><para>This option specifies how much space should be
|
||||
|
|
@ -77,6 +80,7 @@ env-keep-derivations = false
|
|||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry><term><literal>env-keep-derivations</literal></term>
|
||||
|
||||
<listitem><para>If <literal>false</literal> (default), derivations
|
||||
|
|
@ -100,6 +104,21 @@ env-keep-derivations = false
|
|||
|
||||
</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>
|
||||
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -10,7 +10,15 @@
|
|||
<cmdsynopsis>
|
||||
<command>nix-build</command>
|
||||
<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>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
|
@ -30,14 +38,13 @@ and so on).</para>
|
|||
<command>nix-build</command> will use <filename>default.nix</filename>
|
||||
in the current directory, if it exists.</para>
|
||||
|
||||
<note><para><command>nix-build</command> is essentially a wrapper
|
||||
around <link
|
||||
<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>
|
||||
--realise</command></link> (to build the store derivation).</para>
|
||||
|
||||
<warning><para>The result of the build is automatically registered as
|
||||
a root of the Nix garbage collector. This root disappears
|
||||
|
|
@ -62,7 +69,16 @@ or renamed. So don’t rename the symlink.</para></warning>
|
|||
|
||||
</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
|
||||
that as a result the output does not become a root of the garbage
|
||||
|
|
@ -71,6 +87,16 @@ or renamed. So don’t rename the symlink.</para></warning>
|
|||
|
||||
</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>
|
||||
|
||||
</refsection>
|
||||
|
|
|
|||
|
|
@ -514,8 +514,9 @@ then you should unsubscribe from the offending channel
|
|||
<replaceable>URL</replaceable></command>; leave out
|
||||
<literal>/MANIFEST</literal>), and subscribe to the same URL, with
|
||||
<literal>channels</literal> replaced by <literal>channels-v3</literal>
|
||||
(e.g.,
|
||||
http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable).</para>
|
||||
(e.g., <link
|
||||
xlink:href='http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable'
|
||||
/>).</para>
|
||||
|
||||
<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
|
||||
160 bits long, but encoded in base-32 so that they are still only 32
|
||||
characters long (e.g.,
|
||||
/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0). (This is
|
||||
actually a 160 bit truncation of a SHA-256 hash.)</para></listitem>
|
||||
<filename>/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</filename>).
|
||||
(This is actually a 160 bit truncation of a SHA-256
|
||||
hash.)</para></listitem>
|
||||
|
||||
<listitem><para>Big cleanups and simplifications of the basic store
|
||||
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
|
||||
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
|
||||
you have to do is associate
|
||||
- see, e.g., <link
|
||||
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
|
||||
<literal>application/nix-package</literal> (or the extension
|
||||
<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>
|
||||
|
||||
<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
|
||||
after builds: the last-modified timestamp is set to 0 (00:00:00
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ pre.programlisting
|
|||
Screen dumps:
|
||||
***************************************************************************/
|
||||
|
||||
pre.screen
|
||||
pre.screen, pre.programlisting
|
||||
{
|
||||
border: 1px solid #6185a0;
|
||||
padding: 3px 3px;
|
||||
|
|
@ -260,3 +260,8 @@ strong.command
|
|||
// font-weight: normal;
|
||||
color: #400000;
|
||||
}
|
||||
|
||||
div.calloutlist td
|
||||
{
|
||||
padding-bottom: 1em;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ need to do three things:
|
|||
the inputs.</para></listitem>
|
||||
|
||||
<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
|
||||
<emphasis>function</emphasis>; it requires other components in order
|
||||
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>
|
||||
|
||||
<example xml:id='ex-hello-composition'><title>Composing GNU Hello
|
||||
(<filename>all-packages-generic.nix</filename>)</title>
|
||||
(<filename>all-packages.nix</filename>)</title>
|
||||
<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
|
||||
function; it is missing some arguments that have to be filled in
|
||||
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
|
||||
appropriate arguments. <xref linkend='ex-hello-composition' /> shows
|
||||
some fragments of
|
||||
<filename>all-packages-generic.nix</filename>.</para>
|
||||
<filename>all-packages.nix</filename>.</para>
|
||||
|
||||
<calloutlist>
|
||||
|
||||
|
|
@ -361,7 +361,7 @@ some fragments of
|
|||
GNU Hello. The import operation just loads and returns the
|
||||
specified Nix expression. In fact, we could just have put the
|
||||
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
|
||||
bulky.</para>
|
||||
|
||||
|
|
@ -406,71 +406,38 @@ some fragments of
|
|||
|
||||
<section><title>Testing</title>
|
||||
|
||||
<para>You can now try to build Hello. The simplest way to do that is
|
||||
by using <command>nix-env</command>:
|
||||
<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-env -f pkgs/system/i686-linux.nix -i hello
|
||||
installing `hello-2.1.1'
|
||||
building path `/nix/store/632d2b22514dcebe704887c3da15448d-hello-2.1.1'
|
||||
$ 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>
|
||||
</screen>
|
||||
|
||||
This will build Hello and install it into your profile. The file
|
||||
<filename>i686-linux</filename> is just a simple Nix expression that
|
||||
imports <filename>all-packages-generic.nix</filename> and instantiates
|
||||
it for Linux on the x86 platform.</para>
|
||||
$ ls -l result
|
||||
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
|
||||
|
||||
<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
|
||||
Hello, world!</screen>
|
||||
|
||||
</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
|
||||
|
|
@ -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
|
||||
Nix instance that gets there will perform the build, while the others
|
||||
block (or perform other derivations if available) until the build
|
||||
finishes. So it is always safe to run multiple instances of Nix in
|
||||
parallel (contrary to, say, <command>make</command>).</para>
|
||||
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 <option>-j <replaceable>N</replaceable></option>,
|
||||
where <replaceable>N</replaceable> is the maximum number of jobs to be
|
||||
run in parallel. Typically this should be the number of CPUs.</para>
|
||||
Just pass the option <option linkend='opt-max-jobs'>-j
|
||||
<replaceable>N</replaceable></option>, 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>
|
||||
|
||||
|
|
@ -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
|
||||
the <literal>let</literal> construct.) It is also possible to inherit
|
||||
attributes from another attribute set. For instance, in this fragment
|
||||
from <filename>all-packages-generic.nix</filename>,
|
||||
from <filename>all-packages.nix</filename>,
|
||||
|
||||
<programlisting>
|
||||
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
|
||||
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
|
||||
places by setting certain variables. These <emphasis>hook
|
||||
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
|
||||
installPhase distPhase</literal>.</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section><title>Debugging failed builds</title>
|
||||
|
||||
<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
|
||||
build directory. This is useful for debugging: it allows you to
|
||||
|
|
@ -1543,9 +1530,8 @@ $ make
|
|||
|
||||
</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>
|
||||
|
||||
|
||||
</section>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue