forked from lix-project/lix
504 lines
13 KiB
XML
504 lines
13 KiB
XML
<?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>
|