From 1a9a1f2768bac5defe4c2e39e5a9ccdee0e05d55 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 21 Aug 2006 16:05:11 +0000 Subject: * Convert to DocBook 5. * Use Jing for RelaxNG validation, xmllint seems buggy. --- doc/manual/Makefile.am | 13 ++-- doc/manual/bugs.xml | 17 +++-- doc/manual/build-farm.xml | 19 ++++-- doc/manual/conf-file.xml | 18 +++-- doc/manual/env-common.xml | 12 +++- doc/manual/glossary.xml | 24 ++++--- doc/manual/installation.xml | 99 ++++++++++++++------------- doc/manual/introduction.xml | 38 ++++++----- doc/manual/manual.xml | 118 ++++++++++++++++----------------- doc/manual/nix-build.xml | 5 +- doc/manual/nix-channel.xml | 3 +- doc/manual/nix-collect-garbage.xml | 3 +- doc/manual/nix-env.xml | 7 +- doc/manual/nix-instantiate.xml | 3 +- doc/manual/nix-pull.xml | 78 +++++++++++----------- doc/manual/nix-push.xml | 10 +-- doc/manual/nix-store.xml | 23 ++++--- doc/manual/opt-common.xml | 11 +-- doc/manual/package-management.xml | 47 +++++++------ doc/manual/quick-start.xml | 10 ++- doc/manual/release-notes.xml | 20 +++--- doc/manual/troubleshooting.xml | 6 +- doc/manual/writing-nix-expressions.xml | 79 +++++++++++----------- 23 files changed, 364 insertions(+), 299 deletions(-) (limited to 'doc') diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 079872f64431..e06fbf5cd323 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -1,7 +1,5 @@ -ENV = SGML_CATALOG_FILES=$(docbookcatalog) - -XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs -XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ +XMLLINT = $(xmllint) $(xmlflags) +XSLTPROC = $(xsltproc) $(xmlflags) \ --param section.autolabel 1 \ --param section.label.includes.component.label 1 \ --param html.stylesheet \'style.css\' \ @@ -24,7 +22,12 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \ style.css images manual.is-valid: $(MANUAL_SRCS) version.txt - $(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --valid - +# $(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --relaxng $(docbookrng)/docbook.rng - + if test "$(jing)" != "false"; then \ + $(XMLLINT) --xinclude $< | $(jing) $(docbookrng)/docbook.rng /dev/stdin; \ + else \ + echo "Not validating."; \ + fi touch $@ version.txt: diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 9f8faae96ba8..d21603559ddc 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -1,4 +1,8 @@ -Bugs / To-Do + + +Bugs / To-Do + @@ -15,11 +19,12 @@ implemented; generations form a linear sequence. is already possible to do build management using Nix (by writing builders that perform appropriate build steps), but the Nix expression language is not yet powerful enough to make this pleasant (?). The -language should be extended with features from the Maak build manager. -Another interesting idea is to write a make -implementation that uses Nix as a back-end to support legacy +language should be extended with features from the Maak build +manager. Another interesting idea is to write a +make implementation that uses Nix as a back-end to +support legacy build files. For security, nix-push manifests diff --git a/doc/manual/build-farm.xml b/doc/manual/build-farm.xml index c86e19cdf3b9..cfca63f360cd 100644 --- a/doc/manual/build-farm.xml +++ b/doc/manual/build-farm.xml @@ -1,4 +1,9 @@ -Setting up a Build Farm + + +Setting up a Build Farm + This chapter provides some sketchy information on how to set up a Nix-based build farm. Nix is particularly suited as a basis for a @@ -50,13 +55,13 @@ build farm, since: TODO -The sources of the Nix build farm are at . +The sources of the Nix build farm are at . -
Setting up distributed builds +
Setting up distributed builds You can enable distributed builds by setting the environment variable NIX_BUILD_HOOK to point to a program that Nix @@ -70,7 +75,7 @@ the documentation of the NIX_BUILD_HOOK variable. -Remote machine configuration: +<example xml:id='ex-remote-systems'><title>Remote machine configuration: <filename>remote-systems.conf</filename> nix@mcflurry.labs.cs.uu.nl powerpc-darwin /home/nix/.ssh/id_quarterpounder_auto 2 @@ -79,8 +84,8 @@ nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto An example build hook can be found in the Nix build farm -sources: . It should be suitable for most purposes, with maybe some minor adjustments. It uses ssh and rsync to copy the build inputs and outputs and diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml index 9ff34324f20f..61b096520b4b 100644 --- a/doc/manual/conf-file.xml +++ b/doc/manual/conf-file.xml @@ -1,4 +1,9 @@ -Nix configuration file +
+ +Nix configuration file + A number of persistent settings of Nix are stored in the file prefix/etc/nix/nix.conf. @@ -7,7 +12,7 @@ This file is a list of name = Comments start with a # character. An example configuration file is shown in . -Nix configuration file +Nix configuration file gc-keep-outputs = true # Nice for developers @@ -20,7 +25,7 @@ env-keep-derivations = false - gc-keep-outputs + gc-keep-outputs If true, the garbage collector will keep the outputs of non-garbage derivations. If @@ -36,7 +41,7 @@ env-keep-derivations = false - gc-keep-derivations + gc-keep-derivations If true (default), the garbage collector will keep the derivations from which non-garbage store @@ -52,7 +57,7 @@ env-keep-derivations = false - gc-reserved-space + gc-reserved-space This option specifies how much space should be reserved in normal use so that the garbage collector can run @@ -99,4 +104,5 @@ env-keep-derivations = false - + +
diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml index 2d25d3b283da..75ce39f40654 100644 --- a/doc/manual/env-common.xml +++ b/doc/manual/env-common.xml @@ -1,4 +1,9 @@ -Common environment variables +
+ +Common environment variables + Most Nix commands interpret the following environment variables: @@ -118,7 +123,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix -NIX_BUILD_HOOK +NIX_BUILD_HOOK @@ -271,4 +276,5 @@ $ mount -o bind /mnt/otherdisk/nix /nix - + +
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml index a659e7e4a90b..e76f99a2616f 100644 --- a/doc/manual/glossary.xml +++ b/doc/manual/glossary.xml @@ -1,9 +1,13 @@ -Glossary + + +Glossary + -derivation +derivation A description of a build action. The result of a derivation is a store object. Derivations are typically specified @@ -46,7 +50,7 @@ -substitute +substitute A substitute is a command invocation stored in the Nix database that describes how to build a store object, bypassing @@ -79,7 +83,7 @@ -reference +reference A store path P is said to have a reference to a store path Q if the store object @@ -92,7 +96,7 @@ -closure +closure The closure of a store path is the set of store paths that are directly or indirectly “reachable” from that store @@ -108,14 +112,14 @@ -output path +output path A store path produced by a derivation. -deriver +deriver The deriver of an output path is the store @@ -124,7 +128,7 @@ -validity +validity A store path is considered valid if it exists in the file system, is @@ -134,7 +138,7 @@ -user environment +user environment An automatically generated store object that consists of a set of symlinks to “active” applications, i.e., other @@ -147,7 +151,7 @@ -profile +profile A symlink to the current user environment of a user, e.g., diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index 491d044cde8a..483c24e98715 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -1,33 +1,38 @@ -Installation + + +Installation -Obtaining Nix -The easiest way to obtain Nix is to download a source -distribution. RPMs for Red Hat, SuSE, and Fedore Core are +
Obtaining Nix + +The easiest way to obtain Nix is to download a source +distribution. RPMs for Red Hat, SuSE, and Fedore Core are also available. Alternatively, the most recent sources of Nix can be obtained -from its Subversion -repository. For example, the following command will check out -the latest revision into a directory called nix: +from its Subversion +repository. For example, the following command will check out +the latest revision into a directory called +nix: $ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix -Likewise, specific releases can be obtained from the tags -directory of the repository. If you don't have Subversion, -you can also download an automatically generated compressed -tar-file of the head revision of the trunk. +Likewise, specific releases can be obtained from the tags +directory of the repository. If you don't have Subversion, you +can also download an automatically generated compressed +tar-file of the head revision of the trunk. - +
-Prerequisites +
Prerequisites The following prerequisites only apply when you build from source. Binary releases (e.g., RPMs) have no prerequisites. @@ -39,10 +44,11 @@ and higher should work. xmllint and xsltproc programs, which are part of the libxml2 and libxslt packages, respectively. You also need the -DocBook XSL -stylesheets and optionally the -DocBook XML 4.2 DTD. Note that these are only required if you +DocBook XSL +stylesheets and optionally the +DocBook XML 4.2 DTD. Note that these are only required if you modify the manual sources or when you are building from the Subversion repository. @@ -50,11 +56,11 @@ repository. of Bison and Flex are required. (This is because Nix needs GLR support in Bison and reentrancy support in Flex.) For Bison, you need version 1.875c or higher (1.875 does not work), -which can be obtained from the GNU FTP server. For -Flex, you need version 2.5.31, which is available on SourceForge. Slightly older -versions may also work, but ancient versions like the ubiquitous +which can be obtained from the GNU FTP server. +For Flex, you need version 2.5.31, which is available on SourceForge. Slightly +older versions may also work, but ancient versions like the ubiquitous 2.5.4a won't. Note that these are only required if you modify the parser or when you are building from the Subversion repository. @@ -69,10 +75,10 @@ and options to point to their respective locations. Note that Berkeley DB must be version 4.4; other versions may not have compatible database formats. - +
-Building Nix from source +
Building Nix from source After unpacking or checking out the Nix sources, issue the following commands: @@ -110,17 +116,17 @@ and options. - +
-Installing from RPMs +
Installing from RPMs -RPM packages of Nix can be downloaded from . These RPMs should -work for most fairly recent releases of SuSE and Red Hat Linux. They -have been known to work work on SuSE Linux 8.1 and 9.0, and Red Hat -9.0. In fact, it should work on any RPM-based Linux distribution -based on glibc 2.3 or later. +RPM packages of Nix can be downloaded from http://www.cs.uu.nl/groups/ST/Trace/Nix. +These RPMs should work for most fairly recent releases of SuSE and Red +Hat Linux. They have been known to work work on SuSE Linux 8.1 and +9.0, and Red Hat 9.0. In fact, it should work on any RPM-based Linux +distribution based on glibc 2.3 or later. Once downloaded, the RPMs can be installed or upgraded using rpm -U. For example, @@ -137,28 +143,27 @@ auxiliary data: $ rm -rf /nix/store $ rm -rf /nix/var - +
-Permissions +
Permissions All Nix operations must be performed under the user ID that owns the Nix store and database (prefix/store and prefix/var/nix/db, respectively). When installed from the RPM packages, these -directories are owned by root. +directories are owned by root. -Setuid installation +
Setuid installation As a somewhat ad hoc hack, you can also install the Nix binaries setuid so that a Nix store can be shared among several users. To do this, configure Nix with the --enable-setuid option. Nix will be installed as owned by a user and group specified by the - and - +user and +group options. E.g., @@ -184,12 +189,12 @@ on systems that have the setresuid() system call (such as Linux and FreeBSD), so on those systems the binaries are simply owned by the Nix user. - +
- +
-Using Nix +
Using Nix To use Nix, some environment variables should be set. In particular, PATH should contain the directories @@ -206,7 +211,7 @@ in your ~/.bashrc (or similar), like this: source prefix/etc/profile.d/nix.sh - +
 diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index fb6e79fcb59f..644e62e3c08e 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction.xml @@ -1,4 +1,7 @@ -Introduction + + +Introduction - - - - + + + - + Nix Release Notes + diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index 0462401bcabb..03d0d97fe99b 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -1,5 +1,6 @@ - - + + nix-build build a Nix expression diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml index 059832a86c1d..f3fb7c1f6d43 100644 --- a/doc/manual/nix-channel.xml +++ b/doc/manual/nix-channel.xml @@ -1,4 +1,5 @@ - + nix-channel diff --git a/doc/manual/nix-collect-garbage.xml b/doc/manual/nix-collect-garbage.xml index 3e4ab092588d..73739182d491 100644 --- a/doc/manual/nix-collect-garbage.xml +++ b/doc/manual/nix-collect-garbage.xml @@ -1,4 +1,5 @@ - + nix-collect-garbage diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml index 6fb894e2be5f..ee228f37425e 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/nix-env.xml @@ -1,4 +1,5 @@ - + nix-env @@ -172,7 +173,7 @@ linkend="sec-common-options" />. -Operation <option>--install</option> +Operation <option>--install</option> Synopsis @@ -725,7 +726,7 @@ $ nix-env -qas (show status of available derivations)(installed and by definition present) ... -$ nix-env -f ./foo.nix -qa (show available derivations in the Nix expression foo.nix) +$ nix-env -f ./foo.nix -qa (show available derivations in the Nix expression foo.nix) foo-1.2.3 $ nix-env -qc (compare installed versions to what’s available) diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml index ffee27beb8de..230f03682523 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/nix-instantiate.xml @@ -1,4 +1,5 @@ - + nix-instantiate diff --git a/doc/manual/nix-pull.xml b/doc/manual/nix-pull.xml index 448ab0065eee..28b5e354bb66 100644 --- a/doc/manual/nix-pull.xml +++ b/doc/manual/nix-pull.xml @@ -1,43 +1,41 @@ - - - nix-pull - pull substitutes from a network cache - - - - - nix-pull - url - - - - - Description - - - The command nix-pull obtains a list of - pre-built store paths from the URL - url, and for each of these store - paths, registers a substitute derivation that downloads and - unpacks it into the Nix store. This is used to speed up - installations: if you attempt to install something that has - already been built and stored into the network cache, Nix can - transparently re-use the pre-built store paths. - - - - The file at url must be compatible - with the files created by nix-push. - - - - - - Examples - - + + + + nix-pull + pull substitutes from a network cache + + + + + nix-pull + url + + + + +Description + +The command nix-pull obtains a list of +pre-built store paths from the URL url, and +for each of these store paths, registers a substitute derivation that +downloads and unpacks it into the Nix store. This is used to speed up +installations: if you attempt to install something that has already +been built and stored into the network cache, Nix can transparently +re-use the pre-built store paths. + +The file at url must be compatible +with the files created by nix-push. + + + + +Examples + + $ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST - - + + + diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml index f683784ada91..0b2a368e9f02 100644 --- a/doc/manual/nix-push.xml +++ b/doc/manual/nix-push.xml @@ -1,4 +1,5 @@ - + nix-push @@ -62,14 +63,15 @@ machines using the nix-pull command. specified by archivesPutURL. HTTP PUT requests are used to do this. However, before a file x is uploaded to - archivesPutURL/x, + archivesPutURL/x, nix-push first determines whether this upload is unnecessary by issuing a HTTP HEAD request on - archivesGetURL/x. + archivesGetURL/x. This allows a cache to be shared between many partially overlapping nix-push invocations. (We use two URLs because the upload URL typically refers to a CGI script, while the download - URL just refers to a file system directory on the server.) + URL just refers to a file system directory on the + server.) The manifest is uploaded using an HTTP PUT request to manifestPutURL. The corresponding diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index cd7de90fd687..b8ee297242d9 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -1,4 +1,5 @@ - + nix-store @@ -43,7 +44,7 @@ linkend="sec-common-options" /> for a list of common options. - path + path Causes the result of a realisation ( and ) @@ -108,7 +109,7 @@ lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134 -Operation +<refsection xml:id='rsec-nix-store-realise'><title>Operation <option>--realise</option> Synopsis @@ -183,7 +184,7 @@ linkend="sec-nix-build">nix-build does. -Operation <option>--gc</option> +Operation <option>--gc</option> Synopsis @@ -353,7 +354,7 @@ query is applied to the target of the symlink. -Queries +Queries @@ -448,11 +449,11 @@ query is applied to the target of the symlink. Prints the references graph of the store paths paths in the format of the - dot tool of AT&T's Graphviz package. This can - be used to visualise dependency graphs. To obtain a build-time - dependency graph, apply this to a store derivation. To obtain a - runtime dependency graph, apply it to an output + dot tool of AT&T's Graphviz package. + This can be used to visualise dependency graphs. To obtain a + build-time dependency graph, apply this to a store derivation. To + obtain a runtime dependency graph, apply it to an output path. @@ -575,7 +576,7 @@ $ gv graph.ps A performance issue has been fixed with the referer table, which stores the inverse of the diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index ebd454a97266..3787ddcd93f5 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -1,4 +1,8 @@ -Troubleshooting + + +Troubleshooting + This section provides solutions for some common problems. diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 56adacba4309..5b522ea1d1f9 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -1,4 +1,9 @@ -Writing Nix Expressions + + +Writing Nix Expressions + This chapter shows you how to write Nix expressions, which are the things that tell Nix how to build components. It starts with a @@ -8,9 +13,9 @@ on to a more in-depth look at the Nix expression language. A simple Nix expression -This section shows how to add and test the GNU Hello -package to the Nix Packages collection. Hello is a program +This section shows how to add and test the GNU Hello +package to the Nix Packages collection. Hello is a program that prints out the text Hello, world!. To add a component to the Nix Packages collection, you generally @@ -44,19 +49,19 @@ need to do three things: The Nix expression -Nix expression for GNU Hello +<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello (<filename>default.nix</filename>) -{stdenv, fetchurl, perl}: +{stdenv, fetchurl, perl}: -stdenv.mkDerivation { - name = "hello-2.1.1"; - builder = ./builder.sh; - src = fetchurl { +stdenv.mkDerivation { + name = "hello-2.1.1"; + builder = ./builder.sh; + src = fetchurl { url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz; md5 = "70c9ccf9fac07f762c24f2df2290784d"; }; - inherit perl; + inherit perl; } @@ -188,17 +193,17 @@ perl = perl; The builder -Build script for GNU Hello +<example xml:id='ex-hello-builder'><title>Build script for GNU Hello (<filename>builder.sh</filename>) -source $stdenv/setup +source $stdenv/setup -PATH=$perl/bin:$PATH +PATH=$perl/bin:$PATH -tar xvfz $src +tar xvfz $src cd hello-* -./configure --prefix=$out -make +./configure --prefix=$out +make make install @@ -303,18 +308,18 @@ error check. Composition -Composing GNU Hello +<example xml:id='ex-hello-composition'><title>Composing GNU Hello (<filename>all-packages-generic.nix</filename>) ... -rec { +rec { - hello = (import ../applications/misc/hello/ex-1 ) { + hello = (import ../applications/misc/hello/ex-1 ) { inherit fetchurl stdenv perl; }; - perl = (import ../development/interpreters/perl) { + perl = (import ../development/interpreters/perl) { inherit fetchurl stdenv; }; @@ -519,14 +524,14 @@ functions that automate the build process. A builder using the generic build facilities in shown in . -Build script using the generic +<example xml:id='ex-hello-builder2'><title>Build script using the generic build functions -buildInputs="$perl" +buildInputs="$perl" -source $stdenv/setup +source $stdenv/setup -genericBuild +genericBuild @@ -619,8 +624,8 @@ language. 123. URIs as defined in appendix B - of RFC - 2396, e.g., + of RFC + 2396, e.g., https://svn.cs.uu.nl:12443/dist/trace/trace-nix-trunk.tar.bz2. Paths, e.g., @@ -818,7 +823,7 @@ set. -Functions +Functions Functions have the following form: @@ -903,7 +908,7 @@ evaluate to a boolean value. If it evaluates to true, e2 is returned; otherwise expression evaluation is aborted and a backtrace is printed. -Nix expression for Subversion +Nix expression for Subversion { localServer ? false , httpServer ? false @@ -915,9 +920,9 @@ otherwise expression evaluation is aborted and a backtrace is printed. , openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null }: -assert localServer -> db4 != null; -assert httpServer -> httpd != null && httpd.expat == expat; -assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); +assert localServer -> db4 != null; +assert httpServer -> httpd != null && httpd.expat == expat; +assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); assert pythonBindings -> swig != null && swig.pythonSupport; assert javaSwigBindings -> swig != null && swig.javaSupport; assert javahlBindings -> j2sdk != null; @@ -925,7 +930,7 @@ assert javahlBindings -> j2sdk != null; stdenv.mkDerivation { name = "subversion-1.1.1"; ... - openssl = if sslSupport then openssl else null; + openssl = if sslSupport then openssl else null; ... } @@ -1019,7 +1024,7 @@ locally in a rec-expression. Nix expression language, in order of precedence (from strongest to weakest binding). - +
Operators @@ -1109,7 +1114,7 @@ weakest binding). -Derivations +Derivations The most important built-in function is derivation, which is used to describe a @@ -1118,7 +1123,7 @@ set, the attributes of which specify the inputs of the build. - There must be an attribute named + There must be an attribute named system whose value must be a string specifying a Nix platform identifier, such as "i686-linux" or "powerpc-darwin"To figure out @@ -1297,7 +1302,7 @@ character, or inline/multi-line, enclosed within /* -The standard environment +The standard environment The standard build environment in the Nix Packages collection provides a basic environment for building Unix packages. It consists -- cgit 1.4.1