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