* Split the book.xml into several xml files.
This commit is contained in:
Eelco Dolstra
parent
469f1eba56
commit
b4f88d0ec3
|
|
@ -2,17 +2,20 @@ DOCBOOK_DTD = /nix/current/xml/dtd/docbook
|
||||||
DOCBOOK_XSL = /nix/current/xml/xsl/docbook
|
DOCBOOK_XSL = /nix/current/xml/xsl/docbook
|
||||||
XML = /usr/share/doc/packages/sp/html-xml/xml.soc
|
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 \
|
SP_CHARSET_FIXED=YES SP_ENCODING=XML \
|
||||||
nsgmls -wxml -c $(XML) -c $(DOCBOOK_DTD)/docbook.cat -ges $<
|
nsgmls -wxml -c $(XML) -c $(DOCBOOK_DTD)/docbook.cat -ges $<
|
||||||
touch $@
|
touch $@
|
||||||
|
|
||||||
man1_MANS = nix.1
|
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
|
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
|
xsltproc --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml
|
||||||
|
|
||||||
all-local: book.html
|
all-local: book.html
|
||||||
|
|
|
||||||
|
|
@ -1,503 +1,46 @@
|
||||||
<?xml version="1.0"?>
|
<?xml version="1.0"?>
|
||||||
<!DOCTYPE book SYSTEM "/nix/current/xml/dtd/docbook/docbookx.dtd"
|
<!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>
|
<book>
|
||||||
<title>Nix: The Manual</title>
|
<title>Nix: The Manual</title>
|
||||||
|
|
||||||
|
&introduction;
|
||||||
<!--======================================================================-->
|
&installation;
|
||||||
|
|
||||||
<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>
|
<chapter>
|
||||||
<title>A Guided Tour</title>
|
<title>A Guided Tour</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Bla bla
|
Bla bla
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
||||||
<!--======================================================================-->
|
|
||||||
|
|
||||||
<chapter>
|
<chapter>
|
||||||
<title>Fix Language Reference</title>
|
<title>Fix Language Reference</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Bla bla
|
Bla bla
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
||||||
<!--======================================================================-->
|
|
||||||
|
|
||||||
<chapter>
|
<chapter>
|
||||||
<title>Nix Syntax and Semantics</title>
|
<title>Nix Syntax and Semantics</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Bla bla
|
Bla bla
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</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>
|
<appendix>
|
||||||
<title>Command Reference</title>
|
<title>Command Reference</title>
|
||||||
|
&nix-reference;
|
||||||
<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>
|
||||||
|
|
||||||
|
&troubleshooting;
|
||||||
<!--======================================================================-->
|
&bugs;
|
||||||
|
|
||||||
<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>
|
</book>
|
||||||
|
|
|
||||||
26
doc/manual/bugs.xml
Normal file
26
doc/manual/bugs.xml
Normal 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:
|
||||||
|
-->
|
||||||
79
doc/manual/installation.xml
Normal file
79
doc/manual/installation.xml
Normal 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:
|
||||||
|
-->
|
||||||
98
doc/manual/introduction.xml
Normal file
98
doc/manual/introduction.xml
Normal 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:
|
||||||
|
-->
|
||||||
213
doc/manual/nix-reference.xml
Normal file
213
doc/manual/nix-reference.xml
Normal 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:
|
||||||
|
-->
|
||||||
49
doc/manual/troubleshooting.xml
Normal file
49
doc/manual/troubleshooting.xml
Normal 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:
|
||||||
|
-->
|
||||||
Loading…
Reference in a new issue