doc: Documentation installation and the daemon.

* doc/guix.texi (Installation): New node.
master
Ludovic Courtès 2013-01-09 12:58:27 +01:00
parent 2498d43adb
commit bd5e766b87
1 changed files with 207 additions and 0 deletions

View File

@ -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.
@ -118,6 +119,212 @@ Guix has a command-line interface allowing users to build, install,
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