diff options
| -rw-r--r-- | doc/guix.texi | 207 |
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 |