<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "/nix/current/xml/dtd/docbook/docbookx.dtd"
[
]>
<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>
<!--======================================================================-->
<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>
<arg>--verbose</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>
</refsect1>
<refsect1>
<title>Common Options</title>
<para>
<command>nix</command> has many subcommands. These are listed below.
In this section the common options are listed. These options are
allowed for every subcommand (although they may not always have an
effect).
</para>
</refsect1>
<refsect1>
<title>Subcommand <command>--install</command></title>
<refsect2>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix --install</command>
<arg rep='repeat'><replaceable>id</replaceable></arg>
</cmdsynopsis>
</refsect2>
<refsect2>
<title>Description</title>
<para>
<command>nix --install</command> realises the given Nix expressions
in the file system.
</para>
</refsect2>
</refsect1>
</refentry>
</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>
</book>
