diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 235 |
1 files changed, 231 insertions, 4 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index c7f6683677..2af0c88133 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -8,6 +8,7 @@ @c %**end of header @include version.texi +@set YEARS 2012, 2013 @dircategory Package management @direntry @@ -28,7 +29,7 @@ Edition @value{EDITION} @* @value{UPDATED} @* -Copyright @copyright{} 2012 Ludovic Court@`es +Copyright @copyright{} @value{YEARS} Ludovic Court@`es @quotation Permission is granted to copy, distribute and/or modify this document @@ -43,7 +44,7 @@ Documentation License''. @copying This manual documents GNU Guix version @value{VERSION}. -Copyright (C) 2012, 2013 Ludovic Courtès +Copyright @copyright{} @value{YEARS} Ludovic Courtès Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -62,8 +63,20 @@ Documentation License.'' This document describes GNU Guix version @value{VERSION}, a functional package management tool written for the GNU system. +@quotation +Copyright @copyright{} @value{YEARS} Ludovic Courtès + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License.'' +@end quotation + @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 +132,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 @@ -209,6 +428,12 @@ the transaction. Upon completion, a new profile is created, but previous generations of the profile remain available, should the user want to roll back. +For each user, a symlink to the user's default profile is automatically +created in @file{$HOME/.guix-profile}. This symlink always point to the +current generation of the user's default profile. Thus, users can add +@file{$HOME/.guix-profile/bin} to their @code{PATH} environment +variable, and so on. + @table @code @item --install=@var{package} @@ -217,7 +442,7 @@ Install @var{package}. @var{package} may specify either a simple package name, such as @code{guile}, or a package name followed by a hyphen and version number, -such as @code{guile-1.8}. In addition, @var{package} may contain a +such as @code{guile-1.8.8}. In addition, @var{package} may contain a colon, followed by the name of one of the outputs of the package, as in @code{gcc:doc} or @code{binutils-2.22:lib}. @@ -272,7 +497,9 @@ List packages currently available in the software distribution. When matches @var{regexp}. For each package, print the following items separated by tabs: its name, -its version string, and the source location of its definition. +its version string, the parts of the package (@code{out} for the main +files, @code{lib} for libraries and possibly headers, etc.), and the +source location of its definition. @end table |