* Split the book.xml into several xml files.
This commit is contained in:
Eelco Dolstra
parent
469f1eba56
commit
b4f88d0ec3
7 changed files with 481 additions and 470 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
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