From f316b6c1a91e596b2717bc4db76c6513e3ef5f85 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 2 Oct 2006 11:50:55 +0000 Subject: * Manual updates (especially how nix-build makes testing packages much easier; no longer need a helper expression). --- doc/manual/writing-nix-expressions.xml | 118 +++++++++++++++------------------ 1 file changed, 52 insertions(+), 66 deletions(-) (limited to 'doc/manual/writing-nix-expressions.xml') diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 0bdb00b04..ea719190f 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -35,7 +35,7 @@ need to do three things: the inputs. Add the component to the file - pkgs/system/all-packages-generic.nix. The Nix + pkgs/top-level/all-packages.nix. The Nix expression written in the first step is a function; 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.
Composition Composing GNU Hello -(<filename>all-packages-generic.nix</filename>) +(all-packages.nix) ... @@ -336,11 +336,11 @@ rec { The Nix expression in 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 -pkgs/system/all-packages-generic.nix, where all +pkgs/top-level/all-packages.nix, where all Nix expressions for components are imported and called with the appropriate arguments. shows some fragments of -all-packages-generic.nix. +all-packages.nix. @@ -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 in - all-packages-generic.nix at this point. That + all-packages.nix at this point. That would be completely equivalent, but it would make the file rather bulky. @@ -406,71 +406,38 @@ some fragments of
Testing -You can now try to build Hello. The simplest way to do that is -by using nix-env: +You can now try to build Hello. Of course, you could do +nix-env -f pkgs/top-level/all-packages.nix -i hello, +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 nix-build, which builds a Nix +expression and creates a symlink named result in +the current directory: -$ 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 ... - -This will build Hello and install it into your profile. The file -i686-linux is just a simple Nix expression that -imports all-packages-generic.nix and instantiates -it for Linux on the x86 platform. +$ ls -l result +lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 -Note that the hello argument here refers to -the symbolic name given to the Hello derivation (the -name attribute in ), -not the hello attribute in -all-packages-generic.nix. -nix-env simply walks through all derivations -defined in the latter file, looking for one with a -name attribute matching the command-line -argument. - -You can test whether it works: - - -$ hello -Hello, world! - - - -Generally, however, using nix-env 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: - - -(import pkgs/system/i686-linux.nix).hello - -Call it test.nix. You can then build it without -installing it using the command nix-build: - - -$ nix-build ./test.nix -... -/nix/store/632d2b22514dcebe704887c3da15448d-hello-2.1.1 - -nix-build will build the derivation and print the -output path. It also creates a symlink to the output path called -result in the current directory. This is -convenient for testing the component: - - $ ./result/bin/hello Hello, world! +nix-build registers the +./result symlink as a garbage collection root, so +unless and until you delete the ./result symlink, +the output of the build will be safely kept on your system. You can +use nix-build’s switch to give the symlink another +name. + 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 out 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, make). +finishes: + + +$ nix-build pkgs/top-level/all-packages.nix -A hello +waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x' + +So it is always safe to run multiple instances of Nix in parallel +(which isn’t the case with, say, make). 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 , -where N is the maximum number of jobs to be -run in parallel. Typically this should be the number of CPUs. +Just pass the option , where +N is the maximum number of jobs to be run +in parallel, or set. Typically this should be the number of +CPUs.
@@ -794,7 +769,7 @@ evaluates to {x = 123; y = 456;}. (Note that this works because x is added to the lexical scope by the let construct.) It is also possible to inherit attributes from another attribute set. For instance, in this fragment -from all-packages-generic.nix, +from all-packages.nix, 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. +The definitive, up-to-date documentation of the generic builder +is the source itself, which resides in +pkgs/stdenv/generic/setup.sh. + + +
Customising the generic builder + The operation of the generic builder can be modified in many places by setting certain variables. These hook variables are typically set to the name of some shell @@ -1519,6 +1501,11 @@ new phases, by setting the phases variable. The default is patchPhase configurePhase buildPhase checkPhase installPhase distPhase. +
+ + +
Debugging failed builds + At the beginning of each phase, the set of all shell variables is written to the file env-vars at the top-level build directory. This is useful for debugging: it allows you to @@ -1543,9 +1530,8 @@ $ make -The definitive, up-to-date documentation of the generic builder -is the source itself, which resides in -pkgs/stdenv/generic/setup.sh. +
+
-- cgit v1.2.3