doc: Documentation installation and the daemon.
* doc/guix.texi (Installation): New node.
This commit is contained in:
Ludovic Courtès
parent
2498d43adb
commit
bd5e766b87
1 changed files with 207 additions and 0 deletions
207
doc/guix.texi
207
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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Reference in a new issue