From f6a30ab264506ca966180666dff45310d176659d Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 26 Nov 2003 12:30:16 +0000 Subject: [PATCH] * Updates. --- doc/manual/book.xml | 2 +- doc/manual/bugs.xml | 39 ++-- doc/manual/installation.xml | 100 +++++++--- doc/manual/introduction.xml | 343 +++++++-------------------------- doc/manual/troubleshooting.xml | 21 -- 5 files changed, 169 insertions(+), 336 deletions(-) diff --git a/doc/manual/book.xml b/doc/manual/book.xml index 1dc69d004..710246ca1 100644 --- a/doc/manual/book.xml +++ b/doc/manual/book.xml @@ -12,7 +12,7 @@ ]> - Nix: The Manual + Nix: A System for Software Deployment diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 548ce1cab..fcb69c364 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -1,34 +1,43 @@ - Bugs + Bugs / To-Do - Nix should automatically recover the Berkeley DB database. + Nix should automatically remove Berkeley DB logfiles. - Nix should automatically remove Berkeley DB logfiles. + Unify the concepts of successors and substitutes into a general notion + of equivalent expressions. Expressions are + equivalent if they have the same target paths with the same + identifiers. However, even though they are functionally equivalent, + they may differ stronly with respect to their performance + characteristics. For example, realising a slice is more + efficient that realising the derivation from which that slice was + produced. On the other hand, distributing sources may be more + efficient (storage- or bandwidth-wise) than distributing binaries. So + we need to be able to attach weigths or priorities or performance + annotations to expressions; Nix can then choose the most efficient + expression dependent on the context. - Unify the concepts of successors and substitutes into a general notion - of equivalent expressions. Expressions are - equivalent if they have the same target paths with the same - identifiers. However, even though they are functionally equivalent, - they may differ stronly with respect to their performance - characteristics. For example, realising a slice is more - efficient that realising the derivation from which that slice was - produced. On the other hand, distributing sources may be more - efficient (storage- or bandwidth-wise) than distributing binaries. So - we need to be able to attach weigths or priorities or performance - annotations to expressions; Nix can then choose the most efficient - expression dependent on the context. + Build management. In principle it 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 + build files. diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index f9bd0a742..3872a7fb8 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -1,74 +1,114 @@ Installation - - Prerequisites - - - Nix uses Sleepycat's Berkeley DB and CWI's ATerm library. However, these - are fetched automatically as part of the build process. - - - - Other than that, you need a good C++ compiler. GCC 2.95 does not appear - to work; please use GCC 3.x. - - - Obtaining Nix - Nix can be obtained from its Subversion + The easiest way to obtain Nix is to download a source + distribution. + + + + 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: -$ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix +$ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix Likewise, specific releases can be obtained from the tags + url='https://svn.cs.uu.nl:12443/repos/trace/nix/tags'>tags directory of the repository. If you don't have Subversion, you - can download a compressed - tar-file of the latest revision of the repository. + can also download an automatically generated compressed + tar-file of the head revision of the trunk. + + Prerequisites + + + A fairly recent version of GCC/G++ is required. Version 2.95 and higher + should work. + + + + To rebuild this manual and the man-pages you need the + xmllint and xsltproc, 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 + modify the manual sources or when you are building from the Subversion + repository. + + + + Nix uses Sleepycat's Berkeley DB, CWI's ATerm library, and SDF parser + library. These are included in the Nix source distribution. If you + build from the Subversion repository, you must download them yourself and + place them in the externals/ directory. See + externals/Makefile.am for the precise URLs of these + packages. + + + Building Nix - To build Nix, do the following: + After unpacking or checking out the Nix sources, issue the following + commands: -$ autoreconf -i $ ./configure options... $ make $ make install - Currently, the only useful switch for configure is - to specify - where Nix is to be installed. The default installation directory is + When building from the Subversion repository, these should be preceded by + the command: + + + +$ autoreconf -i + + + The installation path can be specified by passing the + to + configure. The default installation directory is /nix. You can change this to any location you like. - You should ensure that you have write permission to the installation - prefix. + You must have write permission to the prefix + path. It is advisable not to change the installation - prefix, since doing so will in all likelihood make it impossible to use - derivates built on other systems. + prefix from its default, since doing so will in all likelihood make it + impossible to use derivations built on other systems. + + If you want to rebuilt the documentation, pass the full path to the + DocBook XML catalog file (docbook.cat) and to the + DocBook XSL stylesheets using the + + and + options. + + diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index feabeef9c..48e29c0d8 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction.xml @@ -1,289 +1,94 @@ Introduction - - The problem space + + Nix is a system for software deployment. It supports the + creation and distribution of software packages, as well as the installation + and subsequent management of these on target machines (i.e., it is also a + package manager). + - - Nix is a system for controlling the automatic creation and distribution - of data, such as computer programs and other software artifacts. This is - a very general problem, and there are many applications that fall under - this description. - + + Nix solves some large problems that exist in most current deployment and + package management systems. Dependency determination + is a big one: the correct installation of a software component requires + that all dependencies of that component (i.e., other components used by it) + are also installed. Most systems have no way to verify that the specified + dependencies of a component are actually sufficient. + - - Build management + + Another big problem is the lack of support for concurrent availability of + multiple variants of a component. It must be possible + to have several versions of a component installed at the same time, or + several instances of the same version built with different parameters. + Unfortunately, components are in general not properly isolated from each + other. For instance, upgrading a component that is a dependency for some + other component might break the latter. + - - Build management tools are used to perform software - builds, that is, the construction of derived products - (derivates)) such as executable programs from - source code. A commonly used build tool is Make, which is a standard - tool on Unix systems. These tools have to deal with several issues: - + + Nix solves these problems by building and storing packages in paths that + are infeasible to predict in advance. For example, the artifacts of a + package X might be stored in + /nix/store/d58a0606ed616820de291d594602665d-X, rather + than in, say, /usr/lib. The path component + d58a... is actually a cryptographic hash of all the + inputs (i.e., sources, requisites, and build flags) used in building + X, and as such is very fragile: any change to the inputs + will change the hash. Therefore it is not sensible to + hard-code such a path into the build scripts of a + package Y that uses X (as does happen + with fixed paths such as /usr/lib). + Rather, the build script of package Y is parameterised + with the actual location of X, which is supplied by the + Nix system. + - - - Efficiency. Since building large systems - can take a substantial amount of time, it is desirable that build - steps that have been performed in the past are not repeated - unnecessarily, i.e., if a new build differs from a previous build - only with respect to certain sources, then only the build steps - that (directly or indirectly) depend on - those sources should be redone. - - + + As stated above, the path name of a file system object contain a + cryptographic hash of all inputs involved in building it. A change to any + of the inputs will cause the hash to change--and by extension, the path + name. These inputs include both sources (variation in time) and + configuration options (variation in space). Therefore variants of the same + package don't clash---they can co-exist peacefully within the same file + system. + - - - Correctness is this context means that the - derivates produced by a build are always consistent with the - sources, that is, they are equal to what we would get if we were - to build the derivates from those sources. This requirement is - trivially met when we do a full, unconditional build, but is far - from trivial under the requirement of efficiency, since it is not - easy to determine which derivates are affected by a change to a - source. - - + + Other features: + - - - Variability is the property that a software - system can be built in a (potentially large) number of variants. - Variation exists both in time---the - evolution of different versions of an artifact---and in - space---the artifact might have - configuration options that lead to variants that differ in the - features they support (for example, a system might be built with - or without debugging information). - + + Transparent source/binary deployment. + - - Build managers historically have had good support for variation - in time (rebuilding the system in an intelligent way when sources - change is one of the primary reasons to use a build manager), but - not always for variation in space. For example, - make will not automatically ensure that - variant builds are properly isolated from each other (they will - in fact overwrite each other unless special precautions are - taken). - - + + Unambiguous identification of configuration. + - - - High-level system modelling language. The - language in which one describes what and how derivates are to be - produced should have sufficient abstraction facilities to make it - easy to specify the derivation of even very large systems. Also, - the language should be modular to enable - components from possible different sources to be easily combined. - - + + Automatic storage management. + - - + + Atomic upgrades and rollbacks. + - + + Support for many simultaneous configurations. + - - Package management - - - After software has been built, is must also be - deployed in the intended target environment, e.g., - the user's workstation. Examples include the Red Hat package manager - (RPM), Microsoft's MSI, and so on. Here also we have several issues to - contend with: - - - - The creation of packages from some formal - description of what artifacts should be distributed in the - package. - - - - - The deployment of packages, that is, the - mechanism by which we get them onto the intended target - environment. This can be as simple as copying a file, but - complexity comes from the wide range of possible installation - media (such as a network install), and the scalability of the - process (if a program must be installed on a thousand systems, we - do not want to visit each system and perform some manual steps to - install the program on that system; that is, the complexity for - the system administrator should be constant, not linear). - - - - - - - - - - - - - What Nix provides - - - Here is a summary of Nix's main features: - - - - - - - Reliable dependencies. Builds of file system - objects depend on other file system object, such as source files, - tools, and so on. We would like to ensure that a build does not - refer to any objects that have not been declared as inputs for that - build. This is important for several reasons. First, if any of the - inputs change, we need to rebuild the things that depend on them to - maintain consistency between sources and derivates. Second, when we - deploy file system objects (that is, copy them - to a different system), we want to be certain that we copy everything - that we need. - - - - Nix ensures this by building and storing file system objects in paths - that are infeasible to predict in advance. For example, the - artifacts of a package X might be stored in - /nix/store/d58a0606ed616820de291d594602665d-X, - rather than in, say, /usr/lib. The path - component d58a... is actually a cryptographic - hash of all the inputs (i.e., sources, requisites, and build flags) - used in building X, and as such is very fragile: - any change to the inputs will change the hash. Therefore it is not - sensible to hard-code such a path into the build - scripts of a package Y that uses - X (as does happen with fixed paths - such as /usr/lib). Rather, the build script of - package Y is parameterised with the actual - location of X, which is supplied by the Nix - system. - - - - - - Support for variability. - - - - As stated above, the path name of a file system object contain a - cryptographic hash of all inputs involved in building it. A change to - any of the inputs will cause the hash to change--and by extension, - the path name. These inputs include both sources (variation in time) - and configuration options (variation in space). Therefore variants - of the same package don't clash---they can co-exist peacefully within - the same file system. So thanks to Nix's mechanism for reliably - dealing with dependencies, we obtain management of variants for free - (or, to quote Simon Peyton-Jone, it's not free, but it has already - been paid for). - - - - - - - Transparent source/binary deployment. - - - - - - Easy configuration duplication. - - - - - - Automatic storage management. - - - - - - Atomic upgrades and rollbacks. - - - - - - Support for many simultaneous configurations. - - - - - - Portability. Nix is quite portable. Contrary - to build systems like those in, e.g., Vesta and ClearCase [sic?], it - does not rely on operating system extensions. - - - - - - - Here is what Nix doesn't yet provide, but will: - - - - - - - Build management. In principle it is already - possible to do build management using Fix (by writing builders that - perform appropriate build steps), but the Fix language is not yet - powerful enough to make this pleasant. The Maak build manager - should be retargeted to produce Nix expressions, or alternatively, - extend Fix with Maak's semantics and concrete syntax (since Fix needs - a concrete syntax anyway). Another interesting idea is to write a - make implementation that uses Nix as a back-end to - support legacy - build files. - - - - - - - - - - - - The Nix system - - - ... - - - - Existing tools in this field generally both a underlying model (such as - the derivation graph of build tools, or the versioning scheme that - determines when two packages are compatible in a package - management system) and a formalism that allows ... - - - - Following the principle of separation of mechanism and policy, the Nix - system separates the low-level aspect of file system - object management form the high-level aspect of the - ... - - - + + Portability. Nix is quite portable. Contrary to + build systems like those in, e.g., Vesta and ClearCase, it does not rely on + operating system extensions. + + +