From dc05f29cf6e1c5ee557441951116ee3fb35e0e00 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 27 Nov 2003 14:58:32 +0000 Subject: [PATCH] * Manual updates. --- doc/manual/Makefile.am | 4 +- doc/manual/installation.xml | 2 +- doc/manual/overview.xml | 177 ++++++++++++++++++++++++++++++++++-- 3 files changed, 175 insertions(+), 8 deletions(-) diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 51ed7c05f..53a913ce6 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -1,7 +1,9 @@ ENV = SGML_CATALOG_FILES=$(docbookcatalog) XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs -XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs +XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ + --param section.autolabel 1 \ + --param section.label.includes.component.label 1 SOURCES = book.xml introduction.xml installation.xml \ overview.xml \ diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index 7d11fa43e..a9a30b09d 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -117,7 +117,7 @@ $ autoreconf -i To use Nix, some environment variables should be set. In particular, - PATH should contain the directories + PATH should contain the directories prefix/bin and prefix/var/nix/links/current/bin. The first directory contains the Nix tools themselves, while the second diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml index b26d28604..64368fe2d 100644 --- a/doc/manual/overview.xml +++ b/doc/manual/overview.xml @@ -14,10 +14,9 @@ installed or available for installation, and so on. These are operations on the user environment: the set of packages that a user sees. In a command line Unix environment, this means - the set of programs that are available through the - PATH environment variable. (In other environments it - might mean the set of programs available on the desktop, through the - start menu, and so on.) + the set of programs that are available through the PATH + environment variable. (In other environments it might mean the set of + programs available on the desktop, through the start menu, and so on.) @@ -183,8 +182,8 @@ obtaining list of Nix archives at http://losser.st-lab.cs.uu.nl/~eelco/nix-dist. Assuming that the pan installation produced no errors, it can be used immediately, that is, it now appears in a directory in the - PATH environment variable. Specifically, - PATH includes the entry + PATH environment variable. Specifically, + PATH includes the entry prefix/var/nix/links/current/bin, where prefix/var/nix/links/current @@ -239,6 +238,172 @@ $ nix-env -u pan-0.14.2 + + + Writing Nix expressions + + + A simple Nix expression + + + This section shows how to write simple Nix expressions—the things + that describe how to build a package. + + + + Nix expression for GNU Hello + +{stdenv, fetchurl, perl}: + +derivation { + name = "hello-2.1.1"; + system = stdenv.system; + builder = ./builder.sh; + src = fetchurl { + url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; + }; + stdenv = stdenv; + perl = perl; +} + + + + + A simple Nix expression is shown in . It + describes how to the build the GNU Hello + package. This package has several dependencies. First, it + requires a number of other packages, such as a C compiler, standard + Unix shell tools, and Perl. Rather than have this Nix expression refer + to and use specific versions of these packages, it should be generic; + that is, it should be a function that takes the + required packages as inputs and yield a build of the GNU Hello package + as a result. This Nix expression defines a function with three + arguments , namely: + + stdenv, which should be a + standard environment package. The standard + environment is a set of tools and other components that would be + expected in a fairly minimal Unix-like environment: a C compiler + and linker, Unix shell tools, and so on. + + fetchurl, which should be a + function that given parameters url and + md5, will fetch a file from the specified + location and check that this file has the given MD5 hash code. + The hash is required because build operations must be + pure: given the same inputs they should + always yield the same output. Since network resources can change + at any time, we must in some way guarantee what the result will + be. + + perl, which should be a Perl + interpreter. + + + + + + The remainder of the file is the body of the function, which happens to + be a derivation , which is the built-in function + derivation applied to a set of attributes that + encode all the necessary information for building the GNU Hello + package. + + + + Build script (<filename>builder.sh</filename>) for GNU + Hello + +#! /bin/sh + +buildinputs="$perl" +. $stdenv/setup || exit 1 + +tar xvfz $src || exit 1 +cd hello-* || exit 1 +./configure --prefix=$out || exit 1 +make || exit 1 +make install || exit 1 + + + + + + + A more complex Nix expression + + + Nix expression for Subversion + +{ localServer ? false +, httpServer ? false +, sslSupport ? false +, swigBindings ? false +, stdenv, fetchurl +, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null +}: + +assert !isNull expat; +assert localServer -> !isNull db4; +assert httpServer -> !isNull httpd && httpd.expat == expat; +assert sslSupport -> !isNull openssl && (httpServer -> httpd.openssl == openssl); +assert swigBindings -> !isNull swig; + +derivation { + name = "subversion-0.32.1"; + system = stdenv.system; + + builder = ./builder.sh; + src = fetchurl { + url = http://svn.collab.net/tarballs/subversion-0.32.1.tar.gz; + md5 = "b06717a8ef50db4b5c4d380af00bd901"; + }; + + localServer = localServer; + httpServer = httpServer; + sslSupport = sslSupport; + swigBindings = swigBindings; + + stdenv = stdenv; + openssl = if sslSupport then openssl else null; + httpd = if httpServer then httpd else null; + expat = expat; + db4 = if localServer then db4 else null; + swig = if swigBindings then swig else null; +} + + + + + This example shows several features. Default parameters can be used to simplify call sites: if an + argument that has a default is omitted, its default value is used. + + + + You can use assertions to test whether arguments + satisfy certain constraints. The simple assertion tests whether the + expat argument is not a null value. The more + complex assertion says that if + Subversion is built with Apache support, then httpd + (the Apache package) must not be null and it must have been built using + the same instance of the expat library as was passed + to the Subversion expression. This is since the Subversion code is + dynamically linked against the Apache code and they both use Expat, + they must be linked against the same instance—otherwise a + conflict might occur. + + + + + + + +