* Split the book.xml into several xml files.

This commit is contained in:
Eelco Dolstra 2003-08-13 09:13:52 +00:00
parent 469f1eba56
commit b4f88d0ec3
7 changed files with 481 additions and 470 deletions

View file

@ -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

View file

@ -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>

26
doc/manual/bugs.xml Normal file
View file

@ -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:
-->

View file

@ -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:
-->

View file

@ -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:
-->

View file

@ -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:
-->

View file

@ -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:
-->