lix/doc/manual/book.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>
	  <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>