doc: Documentation installation and the daemon.

* doc/guix.texi (Installation): New node.

1 files changed, 207 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 2ca1496bac..1bdb2df032 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -64,6 +64,7 @@ package management tool written for the GNU system.
 
 @menu
 * Introduction::                What is Guix about?
+* Installation::                Installing Guix.
 * Package Management::          Package installation, upgrade, etc.
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
@@ -119,6 +120,212 @@ upgrade, and remove packages, as well as a Scheme programming interface.
 The remainder of this manual describes them.
 
 @c *********************************************************************
+@node Installation
+@chapter Installation
+
+This section describes the software requirements of Guix, as well as how
+to install it and get ready to use it.
+
+@menu
+* Requirements::                Software needed to build and run Guix.
+* Setting Up the Daemon::       Preparing the build daemon's environment.
+* Invoking guix-daemon::        Running the build daemon.
+@end menu
+
+@node Requirements
+@section Requirements
+
+GNU Guix depends on the following packages:
+
+@itemize
+@item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x};
+@item @url{http://gnupg.org/, GNU libgcrypt}
+@end itemize
+
+Unless @code{--disable-daemon} was passed to @command{configure}, the
+following packages are also needed:
+
+@itemize
+@item @url{http://sqlite.org, SQLite 3}
+@item @url{http://www.bzip.org, libbz2}
+@item @url{http://gcc.gnu.org, GCC's g++}
+@end itemize
+
+When a working installation of the Nix package manager is available, you
+can instead configure Guix with @code{--disable-daemon}.  In that case,
+@url{http://nixos.org/nix/, Nix} replaces the three dependencies above.
+
+@node Setting Up the Daemon
+@section Setting Up the Daemon
+
+@cindex daemon
+Operations such as building a package or running the garbage collector
+are all performed by a specialized process, the @dfn{Guix daemon}, on
+behalf of clients.  Only the daemon may access the store and its
+associated database.  Thus, any operation that manipulates the store
+goes through the daemon.  For instance, command-line tools such as
+@command{guix-package} and @command{guix-build} communicate with the
+daemon (@i{via} remote procedure calls) to instruct it what to do.
+
+In a standard multi-user setup, Guix and its daemon---the
+@command{guix-daemon} program---are installed by the system
+administrator; @file{/nix/store} is owned by @code{root} and
+@command{guix-daemon} runs as @code{root}.  Unprivileged users may use
+Guix tools to build packages or otherwise access the store, and the
+daemon will do it on their behalf, ensuring that the store is kept in a
+consistent state, and allowing built packages to be shared among users.
+
+@cindex build users
+When @command{guix-daemon} runs as @code{root}, you may not want package
+build processes themselves to run as @code{root} too, for obvious
+security reasons.  To avoid that, a special pool of @dfn{build users}
+should be created for use by build processes started by the daemon.
+These build users need not have a shell and a home directory: they will
+just be used when the daemon drops @code{root} privileges in build
+processes.  Having several such users allows the daemon to launch
+distinct build processes under separate UIDs, which guarantees that they
+do not interfere with each other---an essential feature since builds are
+regarded as pure functions (@pxref{Introduction}).
+
+On a GNU/Linux system, a build user pool may be created like this (using
+Bash syntax and the @code{shadow} commands):
+
+@example
+# groupadd guix-builder
+# for i in `seq 1 10`;
+  do
+    useradd -g guix-builder -d /var/empty -s `which nologin` \
+            -m "Guix build user $i" guix-builder$i;
+  done
+@end example
+
+@noindent
+The @code{guix-daemon} program may then be run as @code{root} with:
+
+@example
+# guix-daemon --build-users-group=guix-builder
+@end example
+
+Guix may also be used in a single-user setup, with @command{guix-daemon}
+running as a unprivileged user.  However, to maximize non-interference
+of build processes, the daemon still needs to perform certain operations
+that are restricted to @code{root} on GNU/Linux: it should be able to
+run build processes in a chroot, and to run them under different UIDs.
+To that end, the @command{nix-setuid-helper} program is provided; it is
+a small C program (less than 300 lines) that, if it is made setuid
+@code{root}, can be executed by the daemon to perform these operations
+on its behalf.  The @code{root}-owned @file{/etc/nix-setuid.conf} file
+is read by @command{nix-setuid-helper}; it should contain exactly two
+words: the user name under which the authorized @command{guix-daemon}
+runs, and the name of the build users group.
+
+If you are installing Guix as an unprivileged user and do not have the
+ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
+possible to run @command{guix-daemon}.  However, build processes will
+not be isolated from one another, and not from the rest of the system.
+Thus, build processes may interfere with each other, and may access
+programs, libraries, and other files available on the system---making it
+much harder to view them as @emph{pure} functions.
+
+@node Invoking guix-daemon
+@section Invoking @command{guix-daemon}
+
+The @command{guix-daemon} program implements all the functionality to
+access the store.  This includes launching build processes, running the
+garbage collector, querying the availability of a build result, etc.  It
+is normally run as @code{root} like this:
+
+@example
+# guix-daemon --build-users-group=guix-builder
+@end example
+
+@noindent
+For details on how to set it up, @ref{Setting Up the Daemon}.
+
+By default, @command{guix-daemon} launches build processes under
+different UIDs, taken from the build group specified with
+@code{--build-users-group}.  In addition, each build process is run in a
+chroot environment that only contains the subset of the store that the
+build process depends on, as specified by its derivation
+(@pxref{Programming Interface, derivation}), plus a set of specific
+system directories.  By default, the latter contains @file{/dev} and
+@file{/dev/pts}.
+
+The following command-line options are supported:
+
+@table @code
+@item --build-users-group=@var{group}
+Take users from @var{group} to run build processes (@pxref{Setting Up
+the Daemon, build users}).
+
+@item --cache-failures
+Cache build failures.  By default, only successful builds are cached.
+
+@item --cores=@var{n}
+@itemx -c @var{n}
+Use @var{n} CPU cores to build each derivation; @code{0} means as many
+as available.
+
+The default value is @code{1}, but it may be overridden by clients, such
+as the @code{--cores} option of @command{guix-build} (@pxref{Invoking
+guix-build}).
+
+The effect is to define the @code{NIX_BUILD_CORES} environment variable
+in the build process, which can then use it to exploit internal
+parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
+
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel.  The default value is
+@code{1}.
+
+@item --debug
+Produce debugging output.
+
+This is useful to debug daemon start-up issues, but then it may be
+overridden by clients, for example the @code{--verbosity} option of
+@command{guix-build} (@pxref{Invoking guix-build}).
+
+@item --chroot-directory=@var{dir}
+Add @var{dir} to the build chroot.
+
+Doing this may change the result of build processes---for instance if
+they use optional dependencies found in @var{dir} when it is available,
+and not otherwise.  For that reason, it is not recommended to do so.
+Instead, make sure that each derivation declares all the inputs that it
+needs.
+
+@item --disable-chroot
+Disable chroot builds.
+
+Using this option is not recommended since, again, it would allow build
+processes to gain access to undeclared dependencies.
+
+@item --disable-log-compression
+Disable compression of the build logs.
+
+@item --disable-store-optimization
+Disable automatic file ``deduplication'' in the store.
+
+@item --impersonate-linux-2.6
+On Linux-based systems, impersonate Linux 2.6.  This means that the
+kernel's @code{uname} system call will report 2.6 as the release number.
+
+This might be helpful to build programs that (usually wrongfully) depend
+on the kernel version number.
+
+@item --lose-logs
+Do not keep build logs.  By default they are kept under
+@code{@var{localstatedir}/nix/log}.
+
+@item --system=@var{system}
+Assume @var{system} as the current system type.  By default it is the
+architecture/kernel pair found at configure time, such as
+@code{x86_64-linux}.
+@end table
+
+
+@c *********************************************************************
 @node Package Management
 @chapter Package Management