<?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>
<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>
</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>
