diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index a4e3f24ce..a29592f1e 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -2,17 +2,20 @@ DOCBOOK_DTD = /nix/current/xml/dtd/docbook DOCBOOK_XSL = /nix/current/xml/xsl/docbook XML = /usr/share/doc/packages/sp/html-xml/xml.soc -%.is-valid: %.xml +SOURCES = book.xml introduction.xml installation.xml nix-reference.xml \ + troubleshooting.xml bugs.xml + +book.is-valid: $(SOURCES) SP_CHARSET_FIXED=YES SP_ENCODING=XML \ nsgmls -wxml -c $(XML) -c $(DOCBOOK_DTD)/docbook.cat -ges $< touch $@ man1_MANS = nix.1 -man nix.1: book.is-valid +man nix.1: $(SOURCES) book.is-valid xsltproc $(DOCBOOK_XSL)/manpages/docbook.xsl book.xml -%.html: %.xml %.is-valid +book.html: $(SOURCES) book.is-valid xsltproc --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml all-local: book.html diff --git a/doc/manual/book.xml b/doc/manual/book.xml index 3d54edfcb..eb0475a62 100644 --- a/doc/manual/book.xml +++ b/doc/manual/book.xml @@ -1,503 +1,46 @@ + + + + ]> Nix: The Manual - - - - - Introduction - - - The problem space - - - 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. - - - - Build management - - - Build management tools are used to perform software - builds, that is, the construction of derived products - 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: - - - - - - - - - - - - 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 to deal - with several issues: - - - - 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). - - - - - - - - - - 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 ... - - - - - - - - + &introduction; + &installation; A Guided Tour - Bla bla - - - Fix Language Reference - Bla bla - - - Nix Syntax and Semantics - Bla bla - - - - - 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 - 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 - - - Likewise, specific releases can be obtained from the 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. - - - - - - Building Nix - - - To build Nix, do the following: - - - -$ 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 - /nix. You can change this to any location you - like. You should ensure that you have write permission to the - installation prefix. - - - - - 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. - - - - - - - - - - Command Reference - - - - nix - manipulate or query the Nix store - - - - - nix - - - - - - - - - operation - options - arguments - - - - - Description - - - The command nix provides access to the Nix store. - This is the (set of) path(s) where Nix expressions and the file - system objects built by them are stored. - - - - nix has many subcommands called - operations. These are individually documented - below. Exactly one operation must always be provided. - - - - - - Common Options - - - In this section the options that are common to all Nix operations are - listed. These options are allowed for every subcommand (although - they may not always have an effect). - - - - - - - - - Indicates that any identifier arguments to the operation are - paths in the store rather than identifiers. - - - - - - - - - Increases the level of verbosity of diagnostic messages printed - on standard error. For each Nix operation, the information - printed on standard output is well-defined and specified below - in the respective sections. Any diagnostic information is - printed on standard error, never on standard output. - - - - This option may be specified repeatedly. Currently, the - following verbosity levels exist: - - - - - 0 - - - Print error messages only. - - - - - 1 - - - Print informational messages. - - - - - 2 - - - Print even more informational messages. - - - - - 3 - - - Print messages that should only be useful for debugging. - - - - - 4 - - - Vomit mode: print vast amounts of debug - information. - - - - - - - - - - - - - - Operation <option>--install</option> - - - Synopsis - - nix - - - - - ids - - - - - Description - - - The operation realises the Nix - expressions identified by ids in the - file system. If these expressions are derivation expressions, they - are first normalised. That is, their target paths are are built, - unless a normal form is already known. - - - - The identifiers of the normal forms of the given Nix expressions - are printed on standard output. - - - - - - - - - Operation <option>--delete</option> - - - Synopsis - - nix - - - - - paths - - - - - Description - - - The operation unconditionally deletes - the paths paths from the Nix store. - It is an error to attempt to delete paths outside of the store. - - - - - This operation should almost never be called directly, since no - attempt is made to check whether any references exist to the - paths to be deleted. Therefore, an inconsistent system could be - the result. Deletion of paths in the store is done by the - garbage collector (which uses to delete - unreferenced paths). - - - - - - - - - - + &nix-reference; - - - - - Troubleshooting - - - Database hangs - - - If Nix or Fix appear to hang immediately after they are started, Nix's - database is probably wedged, 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: - - - -$ db_recover -e -h prefix/var/nix/db - - - Here, prefix should be replaced by Nix's - installation prefix. - - - - - - - Database logfile removal - - - Every time a Nix database transaction takes place, Nix writes a record - of this transaction to a log in its database - directory to ensure that the operation can be replayed in case of a - application or system crash. However, without manual intervention, - the log grows indefinitely. Hence, unused log files should be deleted - periodically. This can be accomplished using the following command: - - - -$ rm `db_archive -a -h prefix/var/nix/db` - - - - - - - - - - - Bugs - - - - - - Nix should automatically recover the Berkeley DB database. - - - - - - Nix should automatically remove Berkeley DB logfiles. - - - - - + &troubleshooting; + &bugs; diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml new file mode 100644 index 000000000..33c6e767b --- /dev/null +++ b/doc/manual/bugs.xml @@ -0,0 +1,26 @@ + + Bugs + + + + + + Nix should automatically recover the Berkeley DB database. + + + + + + Nix should automatically remove Berkeley DB logfiles. + + + + + + + + diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml new file mode 100644 index 000000000..7d8821d47 --- /dev/null +++ b/doc/manual/installation.xml @@ -0,0 +1,79 @@ + + 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 + 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 + + + Likewise, specific releases can be obtained from the 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. + + + + + + Building Nix + + + To build Nix, do the following: + + + + $ 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 + /nix. You can change this to any location you like. + You should ensure that you have write permission to the installation + prefix. + + + + + 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. + + + + + + + + diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml new file mode 100644 index 000000000..77a5f917e --- /dev/null +++ b/doc/manual/introduction.xml @@ -0,0 +1,98 @@ + + Introduction + + + The problem space + + + 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. + + + + Build management + + + Build management tools are used to perform software + builds, that is, the construction of derived products 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: + + + + + + + + + + + + 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 to deal with + several issues: + + + + 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). + + + + + + + + + + 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 + ... + + + + + + + diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml new file mode 100644 index 000000000..39c83518c --- /dev/null +++ b/doc/manual/nix-reference.xml @@ -0,0 +1,213 @@ + + + nix + manipulate or query the Nix store + + + + + nix + + + + + + + + + operation + options + arguments + + + + + Description + + + The command nix provides access to the Nix store. This + is the (set of) path(s) where Nix expressions and the file system objects + built by them are stored. + + + + nix has many subcommands called + operations. These are individually documented + below. Exactly one operation must always be provided. + + + + + + Common Options + + + In this section the options that are common to all Nix operations are + listed. These options are allowed for every subcommand (although they + may not always have an effect). + + + + + + + + + Indicates that any identifier arguments to the operation are paths + in the store rather than identifiers. + + + + + + + + + Increases the level of verbosity of diagnostic messages printed on + standard error. For each Nix operation, the information printed on + standard output is well-defined and specified below in the + respective sections. Any diagnostic information is printed on + standard error, never on standard output. + + + + This option may be specified repeatedly. Currently, the following + verbosity levels exist: + + + + + 0 + + + Print error messages only. + + + + + 1 + + + Print informational messages. + + + + + 2 + + + Print even more informational messages. + + + + + 3 + + + Print messages that should only be useful for debugging. + + + + + 4 + + + Vomit mode: print vast amounts of debug + information. + + + + + + + + + + + + + + Operation <option>--install</option> + + + Synopsis + + nix + + + + + ids + + + + + Description + + + The operation realises the Nix expressions + identified by ids in the file system. If + these expressions are derivation expressions, they are first + normalised. That is, their target paths are are built, unless a normal + form is already known. + + + + The identifiers of the normal forms of the given Nix expressions are + printed on standard output. + + + + + + + + + Operation <option>--delete</option> + + + Synopsis + + nix + + + + + paths + + + + + Description + + + The operation unconditionally deletes the + paths paths from the Nix store. It is an + error to attempt to delete paths outside of the store. + + + + + This operation should almost never be called directly, since no + attempt is made to verify that no references exist to the paths to + be deleted. Therefore, careless deletion can result in an + inconsistent system. Deletion of paths in the store is done by the + garbage collector (which uses to delete + unreferenced paths). + + + + + + + + + + + + + diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml new file mode 100644 index 000000000..018b3555f --- /dev/null +++ b/doc/manual/troubleshooting.xml @@ -0,0 +1,49 @@ + + Troubleshooting + + + Database hangs + + + If Nix or Fix appear to hang immediately after they are started, Nix's + database is probably wedged, 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: + + + + $ db_recover -e -h prefix/var/nix/db + + + Here, prefix should be replaced by Nix's + installation prefix. + + + + + + + Database logfile removal + + + Every time a Nix database transaction takes place, Nix writes a record of + this transaction to a log in its database directory + to ensure that the operation can be replayed in case of a application or + system crash. However, without manual intervention, the log grows + indefinitely. Hence, unused log files should be deleted periodically. + This can be accomplished using the following command: + + + + $ rm `db_archive -a -h + prefix/var/nix/db` + + + + + +