diff options
| -rw-r--r-- | doc/manual/book.xml | 2 | ||||
| -rw-r--r-- | doc/manual/bugs.xml | 39 | ||||
| -rw-r--r-- | doc/manual/installation.xml | 96 | ||||
| -rw-r--r-- | doc/manual/introduction.xml | 363 | ||||
| -rw-r--r-- | doc/manual/troubleshooting.xml | 21 |
5 files changed, 177 insertions, 344 deletions
diff --git a/doc/manual/book.xml b/doc/manual/book.xml index 1dc69d0041a1..710246ca1bfa 100644 --- a/doc/manual/book.xml +++ b/doc/manual/book.xml @@ -12,7 +12,7 @@ ]> <book> - <title>Nix: The Manual</title> + <title>Nix: A System for Software Deployment</title> <bookinfo> <author> diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 548ce1cab830..fcb69c3641a5 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -1,34 +1,43 @@ <appendix> - <title>Bugs</title> + <title>Bugs / To-Do</title> <itemizedlist> <listitem> <para> - Nix should automatically recover the Berkeley DB database. + Nix should automatically remove Berkeley DB logfiles. </para> </listitem> <listitem> <para> - Nix should automatically remove Berkeley DB logfiles. + Unify the concepts of successors and substitutes into a general notion + of <emphasis>equivalent expressions</emphasis>. 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 <emphasis>performance + characteristics</emphasis>. 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. </para> </listitem> <listitem> <para> - Unify the concepts of successors and substitutes into a general notion - of <emphasis>equivalent expressions</emphasis>. 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 <emphasis>performance - characteristics</emphasis>. 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. + <emphasis>Build management.</emphasis> 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 <ulink + url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>. + Another interesting idea is to write a <command>make</command> + implementation that uses Nix as a back-end to support <ulink + url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink> + build files. </para> </listitem> diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index f9bd0a742fdf..3872a7fb8bf5 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -2,73 +2,113 @@ <title>Installation</title> <sect1> - <title>Prerequisites</title> + <title>Obtaining Nix</title> <para> - Nix uses Sleepycat's Berkeley DB and CWI's ATerm library. However, these - are fetched automatically as part of the build process. + The easiest way to obtain Nix is to download a <ulink + url='http://www.cs.uu.nl/groups/ST/Trace/Nix'>source + distribution.</ulink> </para> <para> - Other than that, you need a good C++ compiler. GCC 2.95 does not appear - to work; please use GCC 3.x. - </para> - </sect1> - - <sect1> - <title>Obtaining Nix</title> - - <para> - Nix can be obtained from its <ulink - url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion + Alternatively, the most recent sources of Nix can be obtained from its + <ulink url='https://svn.cs.uu.nl:12443/repos/trace/nix/trunk'>Subversion repository</ulink>. For example, the following command will check out the latest revision into a directory called <filename>nix</filename>: </para> <screen> -$ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</screen> +$ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix</screen> <para> Likewise, specific releases can be obtained from the <ulink - url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags + url='https://svn.cs.uu.nl:12443/repos/trace/nix/tags'>tags directory</ulink> of the repository. If you don't have Subversion, you - can download a <ulink - url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed - tar-file</ulink> of the latest revision of the repository. + can also download an automatically generated <ulink + url='https://svn.cs.uu.nl:12443/dist/trace/'>compressed + tar-file</ulink> of the head revision of the trunk. + </para> + + </sect1> + + <sect1> + <title>Prerequisites</title> + + <para> + A fairly recent version of GCC/G++ is required. Version 2.95 and higher + should work. + </para> + + <para> + To rebuild this manual and the man-pages you need the + <command>xmllint</command> and <command>xsltproc</command>, which are + part of the <literal>libxml2</literal> and <literal>libxslt</literal> + packages, respectively. You also need the <ulink + url='http://docbook.sourceforge.net/projects/xsl/'>DocBook XSL + stylesheets</ulink> and optionally the <ulink + url='http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip'> + DocBook XML 4.2 DTD</ulink>. Note that these are only required if you + modify the manual sources or when you are building from the Subversion + repository. </para> + <para> + 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 <filename>externals/</filename> directory. See + <filename>externals/Makefile.am</filename> for the precise URLs of these + packages. + </para> </sect1> <sect1> <title>Building Nix</title> <para> - To build Nix, do the following: + After unpacking or checking out the Nix sources, issue the following + commands: </para> <screen> -$ autoreconf -i $ ./configure <replaceable>options...</replaceable> $ make $ make install</screen> <para> - Currently, the only useful switch for <command>configure</command> is - <option>--prefix=<replaceable>prefix</replaceable></option> 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: + </para> + + <screen> +$ autoreconf -i</screen> + + <para> + The installation path can be specified by passing the + <option>--prefix=<replaceable>prefix</replaceable></option> to + <command>configure</command>. The default installation directory is <filename>/nix</filename>. 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 <replaceable>prefix</replaceable> + path. </para> <warning> <para> It is advisable <emphasis>not</emphasis> 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. </para> </warning> + <para> + If you want to rebuilt the documentation, pass the full path to the + DocBook XML catalog file (<filename>docbook.cat</filename>) and to the + DocBook XSL stylesheets using the + <option>--with-docbook-catalog=<replaceable>path</replaceable></option> + and <option>--with-docbook-xsl=<replaceable>path</replaceable></option> + options. + </para> + </sect1> </chapter> diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index feabeef9cdc2..48e29c0d8f93 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction.xml @@ -1,288 +1,93 @@ <chapter> <title>Introduction</title> - <sect1> - <title>The problem space</title> + <para> + 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). + </para> + + <para> + Nix solves some large problems that exist in most current deployment and + package management systems. <emphasis>Dependency determination</emphasis> + 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. + </para> + + <para> + Another big problem is the lack of support for concurrent availability of + multiple <emphasis>variants</emphasis> 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. + </para> + + <para> + 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 <literal>X</literal> might be stored in + <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>, rather + than in, say, <filename>/usr/lib</filename>. The path component + <filename>d58a...</filename> is actually a cryptographic hash of all the + inputs (i.e., sources, requisites, and build flags) used in building + <literal>X</literal>, and as such is very fragile: any change to the inputs + will change the hash. Therefore it is not sensible to + <emphasis>hard-code</emphasis> such a path into the build scripts of a + package <literal>Y</literal> that uses <literal>X</literal> (as does happen + with <quote>fixed</quote> paths such as <filename>/usr/lib</filename>). + Rather, the build script of package <literal>Y</literal> is parameterised + with the actual location of <literal>X</literal>, which is supplied by the + Nix system. + </para> + + <para> + 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. + </para> + + <para> + Other features: + </para> + + <para> + <emphasis>Transparent source/binary deployment.</emphasis> + </para> + + <para> + <emphasis>Unambiguous identification of configuration.</emphasis> + </para> + + <para> + <emphasis>Automatic storage management.</emphasis> + </para> + + <para> + <emphasis>Atomic upgrades and rollbacks.</emphasis> + </para> + + <para> + <emphasis>Support for many simultaneous configurations.</emphasis> + </para> + + <para> + <emphasis>Portability.</emphasis> Nix is quite portable. Contrary to + build systems like those in, e.g., Vesta and ClearCase, it does not rely on + operating system extensions. + </para> - <para> - 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. - </para> - - <sect2> - <title>Build management</title> - - <para> - Build management tools are used to perform <emphasis>software - builds</emphasis>, that is, the construction of derived products - (<emphasis>derivates)</emphasis>) 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: - <itemizedlist> - - <listitem> - <para> - <emphasis>Efficiency</emphasis>. 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) <emphasis>depend</emphasis> on - those sources should be redone. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Correctness</emphasis> 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. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Variability</emphasis> is the property that a software - system can be built in a (potentially large) number of variants. - Variation exists both in <emphasis>time</emphasis>---the - evolution of different versions of an artifact---and in - <emphasis>space</emphasis>---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). - </para> - - <para> - 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, - <command>make</command> 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). - </para> - </listitem> - - <listitem> - <para> - <emphasis>High-level system modelling language</emphasis>. 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 <emphasis>modular</emphasis> to enable - components from possible different sources to be easily combined. - </para> - </listitem> - - </itemizedlist> - </para> - - </sect2> - - <sect2> - <title>Package management</title> - - <para> - After software has been built, is must also be - <emphasis>deployed</emphasis> 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: - <itemizedlist> - <listitem> - <para> - The <emphasis>creation</emphasis> of packages from some formal - description of what artifacts should be distributed in the - package. - </para> - </listitem> - <listitem> - <para> - The <emphasis>deployment</emphasis> 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). - </para> - </listitem> - </itemizedlist> - </para> - </sect2> - - </sect1> - - - <!--######################################################################--> - - <sect1> - <title>What Nix provides</title> - - <para> - Here is a summary of Nix's main features: - </para> - - <itemizedlist> - - <listitem> - <para> - <emphasis>Reliable dependencies.</emphasis> 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 - <emphasis>deploy</emphasis> file system objects (that is, copy them - to a different system), we want to be certain that we copy everything - that we need. - </para> - - <para> - 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 <literal>X</literal> might be stored in - <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>, - rather than in, say, <filename>/usr/lib</filename>. The path - component <filename>d58a...</filename> is actually a cryptographic - hash of all the inputs (i.e., sources, requisites, and build flags) - used in building <literal>X</literal>, and as such is very fragile: - any change to the inputs will change the hash. Therefore it is not - sensible to <emphasis>hard-code</emphasis> such a path into the build - scripts of a package <literal>Y</literal> that uses - <literal>X</literal> (as does happen with <quote>fixed</quote> paths - such as <filename>/usr/lib</filename>). Rather, the build script of - package <literal>Y</literal> is parameterised with the actual - location of <literal>X</literal>, which is supplied by the Nix - system. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Support for variability.</emphasis> - </para> - - <para> - 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). - </para> - - </listitem> - - <listitem> - <para> - <emphasis>Transparent source/binary deployment.</emphasis> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Easy configuration duplication.</emphasis> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Automatic storage management.</emphasis> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Atomic upgrades and rollbacks.</emphasis> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Support for many simultaneous configurations.</emphasis> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Portability.</emphasis> 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. - </para> - </listitem> - - </itemizedlist> - - <para> - Here is what Nix doesn't yet provide, but will: - </para> - - <itemizedlist> - - <listitem> - <para> - <emphasis>Build management.</emphasis> 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 <ulink - url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink> - 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 - <command>make</command> implementation that uses Nix as a back-end to - support <ulink - url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink> - build files. - </para> - </listitem> - - </itemizedlist> - - </sect1> - - - <!--######################################################################--> - - <sect1> - <title>The Nix system</title> - - <para> - ... - </para> - - <para> - 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 <quote>compatible</quote> in a package - management system) and a formalism that allows ... - </para> - - <para> - Following the principle of separation of mechanism and policy, the Nix - system separates the <emphasis>low-level aspect</emphasis> of file system - object management form the <emphasis>high-level aspect</emphasis> of the - ... - </para> +</chapter> - </sect1> -</chapter> <!-- local variables: diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index 6c40775dbe69..1e35c6079538 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -2,27 +2,6 @@ <title>Troubleshooting</title> <sect1> - <title>Database hangs</title> - - <para> - If Nix or Fix appear to hang immediately after they are started, Nix's - database is probably <quote>wedged</quote>, i.e., some process died while - it held a lock on the database. The solution is to ensure that no other - processes are accessing the database and then run the following command: - </para> - - <screen> - $ db_recover -e -h <replaceable>prefix</replaceable>/var/nix/db</screen> - - <para> - Here, <replaceable>prefix</replaceable> should be replaced by Nix's - installation prefix. - </para> - - </sect1> - - - <sect1> <title>Database logfile removal</title> <para> |