diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 9 | ||||
| -rw-r--r-- | doc/manual/book.xml | 477 | ||||
| -rw-r--r-- | doc/manual/bugs.xml | 26 | ||||
| -rw-r--r-- | doc/manual/installation.xml | 79 | ||||
| -rw-r--r-- | doc/manual/introduction.xml | 98 | ||||
| -rw-r--r-- | doc/manual/nix-reference.xml | 213 | ||||
| -rw-r--r-- | doc/manual/troubleshooting.xml | 49 |
7 files changed, 481 insertions, 470 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index a4e3f24ceec8..a29592f1e1e9 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 3d54edfcb685..eb0475a62005 100644 --- a/doc/manual/book.xml +++ b/doc/manual/book.xml @@ -1,503 +1,46 @@ <?xml version="1.0"?> <!DOCTYPE book SYSTEM "/nix/current/xml/dtd/docbook/docbookx.dtd" [ +<!ENTITY introduction SYSTEM "introduction.xml"> +<!ENTITY installation SYSTEM "installation.xml"> +<!ENTITY nix-reference SYSTEM "nix-reference.xml"> +<!ENTITY troubleshooting SYSTEM "troubleshooting.xml"> +<!ENTITY bugs SYSTEM "bugs.xml"> ]> <book> <title>Nix: The Manual</title> - - <!--======================================================================--> - - <chapter> - <title>Introduction</title> - - <sect1> - <title>The problem space</title> - - <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 - 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> - </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 to deal - with several issues: - <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>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> - - </sect1> - - </chapter> - - - <!--======================================================================--> + &introduction; + &installation; <chapter> <title>A Guided Tour</title> - <para> Bla bla </para> </chapter> - - <!--======================================================================--> - <chapter> <title>Fix Language Reference</title> - <para> Bla bla </para> </chapter> - - <!--======================================================================--> - <chapter> <title>Nix Syntax and Semantics</title> - <para> Bla bla </para> </chapter> - - <!--======================================================================--> - - <chapter> - <title>Installation</title> - - <sect1> - <title>Prerequisites</title> - - <para> - Nix uses Sleepycat's Berkeley DB and CWI's ATerm library. However, - these are fetched automatically as part of the build process. - </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 - 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> - - <para> - Likewise, specific releases can be obtained from the <ulink - url='http://losser.st-lab.cs.uu.nl:12080/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. - </para> - - </sect1> - - <sect1> - <title>Building Nix</title> - - <para> - To build Nix, do the following: - </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 - <filename>/nix</filename>. You can change this to any location you - like. You should ensure that you have write permission to the - installation prefix. - </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. - </para> - </warning> - - </sect1> - - </chapter> - - - <!--======================================================================--> - <appendix> <title>Command Reference</title> - - <refentry> - <refnamediv> - <refname>nix</refname> - <refpurpose>manipulate or query the Nix store</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>nix</command> - <group choice='opt'> - <arg><option>--path</option></arg> - <arg><option>-p</option></arg> - </group> - <group choice='opt' rep='repeat'> - <arg><option>--verbose</option></arg> - <arg><option>-v</option></arg> - </group> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - The command <command>nix</command> 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. - </para> - - <para> - <command>nix</command> has many subcommands called - <emphasis>operations</emphasis>. These are individually documented - below. Exactly one operation must always be provided. - </para> - - </refsect1> - - <refsect1> - <title>Common Options</title> - - <para> - 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). - </para> - - <variablelist> - - <varlistentry> - <term><option>--path</option></term> - <listitem> - <para> - Indicates that any identifier arguments to the operation are - paths in the store rather than identifiers. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--verbose</option></term> - <listitem> - <para> - 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. - </para> - - <para> - This option may be specified repeatedly. Currently, the - following verbosity levels exist: - </para> - - <variablelist> - <varlistentry> - <term>0</term> - <listitem> - <para> - Print error messages only. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>1</term> - <listitem> - <para> - Print informational messages. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>2</term> - <listitem> - <para> - Print even more informational messages. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>3</term> - <listitem> - <para> - Print messages that should only be useful for debugging. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>4</term> - <listitem> - <para> - <quote>Vomit mode</quote>: print vast amounts of debug - information. - </para> - </listitem> - </varlistentry> - </variablelist> - - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - - <refsect1> - <title>Operation <option>--install</option></title> - - <refsect2> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix</command> - <group> - <arg><option>--install</option></arg> - <arg><option>-i</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg> - </cmdsynopsis> - </refsect2> - - <refsect2> - <title>Description</title> - - <para> - The operation <option>--install</option> realises the Nix - expressions identified by <replaceable>ids</replaceable> 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. - </para> - - <para> - The identifiers of the normal forms of the given Nix expressions - are printed on standard output. - </para> - - </refsect2> - - </refsect1> - - - <refsect1> - <title>Operation <option>--delete</option></title> - - <refsect2> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix</command> - <group> - <arg><option>--delete</option></arg> - <arg><option>-d</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> - </refsect2> - - <refsect2> - <title>Description</title> - - <para> - The operation <option>--delete</option> unconditionally deletes - the paths <replaceable>paths</replaceable> from the Nix store. - It is an error to attempt to delete paths outside of the store. - </para> - - <warning> - <para> - 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 <option>--delete</option> to delete - unreferenced paths). - </para> - </warning> - - </refsect2> - - </refsect1> - - - </refentry> - + &nix-reference; </appendix> - - <!--======================================================================--> - - <appendix> - <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> - Every time a Nix database transaction takes place, Nix writes a record - of this transaction to a <emphasis>log</emphasis> 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: - </para> - - <screen> -$ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen> - - </sect1> - - - </appendix> - - - <!--======================================================================--> - - <appendix> - <title>Bugs</title> - - <itemizedlist> - - <listitem> - <para> - Nix should automatically recover the Berkeley DB database. - </para> - </listitem> - - <listitem> - <para> - Nix should automatically remove Berkeley DB logfiles. - </para> - </listitem> - - </itemizedlist> - </appendix> + &troubleshooting; + &bugs; </book> diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml new file mode 100644 index 000000000000..33c6e767baca --- /dev/null +++ b/doc/manual/bugs.xml @@ -0,0 +1,26 @@ +<appendix> + <title>Bugs</title> + + <itemizedlist> + + <listitem> + <para> + Nix should automatically recover the Berkeley DB database. + </para> + </listitem> + + <listitem> + <para> + Nix should automatically remove Berkeley DB logfiles. + </para> + </listitem> + + </itemizedlist> + +</appendix> + +<!-- +local variables: +sgml-parent-document: ("book.xml" "appendix") +end: +--> diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml new file mode 100644 index 000000000000..7d8821d4700c --- /dev/null +++ b/doc/manual/installation.xml @@ -0,0 +1,79 @@ +<chapter> + <title>Installation</title> + + <sect1> + <title>Prerequisites</title> + + <para> + Nix uses Sleepycat's Berkeley DB and CWI's ATerm library. However, these + are fetched automatically as part of the build process. + </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 + 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> + + <para> + Likewise, specific releases can be obtained from the <ulink + url='http://losser.st-lab.cs.uu.nl:12080/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. + </para> + + </sect1> + + <sect1> + <title>Building Nix</title> + + <para> + To build Nix, do the following: + </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 + <filename>/nix</filename>. You can change this to any location you like. + You should ensure that you have write permission to the installation + prefix. + </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. + </para> + </warning> + + </sect1> + +</chapter> + +<!-- +local variables: +sgml-parent-document: ("book.xml" "chapter") +end: +--> diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml new file mode 100644 index 000000000000..77a5f917ee71 --- /dev/null +++ b/doc/manual/introduction.xml @@ -0,0 +1,98 @@ +<chapter> + <title>Introduction</title> + + <sect1> + <title>The problem space</title> + + <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 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> + </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 to deal with + several issues: + <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>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> + + </sect1> + +</chapter> + +<!-- +local variables: +sgml-parent-document: ("book.xml" "chapter") +end: +--> diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml new file mode 100644 index 000000000000..39c83518c3ba --- /dev/null +++ b/doc/manual/nix-reference.xml @@ -0,0 +1,213 @@ +<refentry> + <refnamediv> + <refname>nix</refname> + <refpurpose>manipulate or query the Nix store</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>nix</command> + <group choice='opt'> + <arg><option>--path</option></arg> + <arg><option>-p</option></arg> + </group> + <group choice='opt' rep='repeat'> + <arg><option>--verbose</option></arg> + <arg><option>-v</option></arg> + </group> + <arg choice='plain'><replaceable>operation</replaceable></arg> + <arg rep='repeat'><replaceable>options</replaceable></arg> + <arg rep='repeat'><replaceable>arguments</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The command <command>nix</command> 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. + </para> + + <para> + <command>nix</command> has many subcommands called + <emphasis>operations</emphasis>. These are individually documented + below. Exactly one operation must always be provided. + </para> + + </refsect1> + + <refsect1> + <title>Common Options</title> + + <para> + 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). + </para> + + <variablelist> + + <varlistentry> + <term><option>--path</option></term> + <listitem> + <para> + Indicates that any identifier arguments to the operation are paths + in the store rather than identifiers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--verbose</option></term> + <listitem> + <para> + 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. + </para> + + <para> + This option may be specified repeatedly. Currently, the following + verbosity levels exist: + </para> + + <variablelist> + <varlistentry> + <term>0</term> + <listitem> + <para> + Print error messages only. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>1</term> + <listitem> + <para> + Print informational messages. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>2</term> + <listitem> + <para> + Print even more informational messages. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>3</term> + <listitem> + <para> + Print messages that should only be useful for debugging. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>4</term> + <listitem> + <para> + <quote>Vomit mode</quote>: print vast amounts of debug + information. + </para> + </listitem> + </varlistentry> + </variablelist> + + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + + <refsect1> + <title>Operation <option>--install</option></title> + + <refsect2> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix</command> + <group> + <arg><option>--install</option></arg> + <arg><option>-i</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg> + </cmdsynopsis> + </refsect2> + + <refsect2> + <title>Description</title> + + <para> + The operation <option>--install</option> realises the Nix expressions + identified by <replaceable>ids</replaceable> 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. + </para> + + <para> + The identifiers of the normal forms of the given Nix expressions are + printed on standard output. + </para> + + </refsect2> + + </refsect1> + + + <refsect1> + <title>Operation <option>--delete</option></title> + + <refsect2> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix</command> + <group> + <arg><option>--delete</option></arg> + <arg><option>-d</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> + </cmdsynopsis> + </refsect2> + + <refsect2> + <title>Description</title> + + <para> + The operation <option>--delete</option> unconditionally deletes the + paths <replaceable>paths</replaceable> from the Nix store. It is an + error to attempt to delete paths outside of the store. + </para> + + <warning> + <para> + 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 <option>--delete</option> to delete + unreferenced paths). + + </para> + </warning> + + </refsect2> + + </refsect1> + + +</refentry> + + +<!-- +local variables: +sgml-parent-document: ("book.xml" "refentry") +end: +--> diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml new file mode 100644 index 000000000000..018b3555fc18 --- /dev/null +++ b/doc/manual/troubleshooting.xml @@ -0,0 +1,49 @@ +<appendix> + <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> + Every time a Nix database transaction takes place, Nix writes a record of + this transaction to a <emphasis>log</emphasis> 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: + </para> + + <screen> + $ rm `db_archive -a -h + <replaceable>prefix</replaceable>/var/nix/db`</screen> + + </sect1> + +</appendix> + +<!-- +local variables: +sgml-parent-document: ("book.xml" "appendix") +end: +--> |