* doc/guix.texi: Set @documentlanguage. (Installation): Add reference to `INSTALL' and `README'. (Requirements): Mention store sharing with Nix. (Defining Packages): Update example to include `use-modules' clauses and to use (guix licenses).
878 lines
33 KiB
Plaintext
878 lines
33 KiB
Plaintext
\input texinfo
|
||
@c -*-texinfo-*-
|
||
|
||
@c %**start of header
|
||
@setfilename guix.info
|
||
@documentencoding UTF-8
|
||
@documentlanguage en
|
||
@settitle GNU Guix Reference Manual
|
||
@c %**end of header
|
||
|
||
@include version.texi
|
||
@set YEARS 2012, 2013
|
||
|
||
@dircategory Package management
|
||
@direntry
|
||
* guix: (guix). Guix, the functional package manager.
|
||
* guix-package: (guix)Invoking guix-package
|
||
Managing packages with Guix.
|
||
* guix-build: (guix)Invoking guix-build
|
||
Building packages with Guix.
|
||
@end direntry
|
||
|
||
@titlepage
|
||
@title{GNU Guix Reference Manual}
|
||
@subtitle{Using the GNU Guix Functional Package Manager}
|
||
@author Ludovic Courtès
|
||
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
Edition @value{EDITION} @*
|
||
@value{UPDATED} @*
|
||
|
||
Copyright @copyright{} @value{YEARS} Ludovic Court@`es
|
||
|
||
@quotation
|
||
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
|
||
@end titlepage
|
||
|
||
@copying
|
||
This manual documents GNU Guix version @value{VERSION}.
|
||
|
||
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 copying
|
||
|
||
@contents
|
||
|
||
@c *********************************************************************
|
||
@node Top
|
||
@top GNU Guix
|
||
|
||
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.
|
||
|
||
* Acknowledgments:: Thanks!
|
||
* GNU Free Documentation License:: The license of this manual.
|
||
* Concept Index:: Concepts.
|
||
* Function Index:: Functions.
|
||
@end menu
|
||
|
||
@c *********************************************************************
|
||
@node Introduction
|
||
@chapter Introduction
|
||
|
||
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
|
||
using the international phonetic alphabet (IPA).} is a functional
|
||
package management tool for the GNU system. Package management consists
|
||
in all the activities that relate to building packages from source,
|
||
honoring the build-time and run-time dependencies on packages,
|
||
installing packages in user environments, upgrading installed packages
|
||
to new versions or rolling back to a previous set, removing unused
|
||
software packages, etc.
|
||
|
||
@cindex functional package management
|
||
The term @dfn{functional} refers to a specific package management
|
||
discipline. In Guix, the package build and installation process is seen
|
||
as a function, in the mathematical sense: that function takes inputs,
|
||
such as build scripts, a compiler, and libraries depended on, and
|
||
returns the installed package. As a pure function, its result depends
|
||
solely on its inputs---for instance, it cannot refer to software or
|
||
scripts that were not explicitly passed as inputs. A build function
|
||
always produces the same result when passed a given set of inputs. Last
|
||
but not least, a build function cannot alter the system's environment in
|
||
any way; for instance, it cannot create, modify, or delete files outside
|
||
of its build and installation directories. This is achieved by running
|
||
build processes in dedicated ``chroots'', where only their explicit
|
||
inputs are visible.
|
||
|
||
@cindex package store
|
||
The result of package build functions is @dfn{cached} in the file
|
||
system, in a special directory called the @dfn{package store}. In
|
||
practice, each package is installed in a directory of its own, in the
|
||
store---by default under @file{/nix/store}. The directory name contains
|
||
a hash of all the inputs used to build that package; thus, changing an
|
||
input yields a different directory name.
|
||
|
||
This approach is the foundation of Guix's salient features: support for
|
||
transactional package upgrades and rollback, per-user installation, and
|
||
garbage collection of packages (@pxref{Features}).
|
||
|
||
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.
|
||
|
||
The build procedure for Guix is the same as for other GNU software, and
|
||
are not covered here. Please see the files @file{README} and
|
||
@file{INSTALL} in the Guix source tree for additional details.
|
||
|
||
@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.
|
||
|
||
Guix is compatible with Nix, so it is possible to share the same store
|
||
between both. To do so, you must pass @command{configure} not only the
|
||
same @code{--with-store-dir} value, but also the same
|
||
@code{--localstatedir} value (the latter is essential because it
|
||
specifies where the database that store meta-data about the store is
|
||
located, among other things.) The default values are
|
||
@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
|
||
Note that @code{--disable-daemon} is orthogonal and is not required if
|
||
your goal is to share the same store as Nix.
|
||
|
||
@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
|
||
|
||
The purpose of GNU Guix is to allow users to easily install, upgrade, and
|
||
remove software packages, without having to know about their build
|
||
procedure or dependencies. Guix also goes beyond this obvious set of
|
||
features.
|
||
|
||
This chapter describes the main features of Guix, as well as the package
|
||
management tools it provides.
|
||
|
||
@menu
|
||
* Features:: How Guix will make your life brighter.
|
||
* Invoking guix-package:: Package installation, removal, etc.
|
||
* Invoking guix-gc:: Running the garbage collector.
|
||
@end menu
|
||
|
||
@node Features
|
||
@section Features
|
||
|
||
When using Guix, each package ends up in the @dfn{package store}, in its
|
||
own directory---something that resembles
|
||
@file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
|
||
|
||
Instead of referring to these directories, users have their own
|
||
@dfn{profile}, which points to the packages that they actually want to
|
||
use. That profile is normally stored in @code{$HOME/.guix-profile}, and
|
||
each user has its own profile.
|
||
|
||
For example, if @code{alice} installed GCC 4.7.2, then
|
||
@file{/home/alice/.guix-profile/bin/gcc} points to
|
||
@file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob}
|
||
may have installed GCC 4.8.0, in which case its profile refers to these
|
||
particular package installation. Both coexist, without any
|
||
interference.
|
||
|
||
The @command{guix-package} command is the central tool to manage
|
||
packages. It operates on those per-user profiles, and can be used
|
||
@emph{with normal user privileges}.
|
||
|
||
The command provides the obvious install, remove, and upgrade
|
||
operations. Each invocation is actually a @emph{transaction}: either
|
||
the specified operation succeeds, or nothing happens. Thus, if the
|
||
@command{guix-package} processed is terminated during the transaction,
|
||
or if a power outage occurs during the transaction, then the user's
|
||
profile remains in its previous state, and remains usable.
|
||
|
||
In addition, any package transaction may be @emph{rolled back}. So, if,
|
||
for example, an upgrade installs a new version of a package that turns
|
||
out to have a serious bug, users may roll back to the previous instance
|
||
of their profile, which was known to work well.
|
||
|
||
All those packages in the package store may be @emph{garbage-collected}.
|
||
Guix can determine which packages are still referenced by the user
|
||
profiles, and remove those that are provably no longer referenced
|
||
(@pxref{Invoking guix-gc}). Users may also explicitly remove old
|
||
generations of their profile so that the packages they refer to can be
|
||
collected.
|
||
|
||
Finally, Guix takes a @dfn{purely functional} approach to package
|
||
management, as described in the introduction (@pxref{Introduction}).
|
||
Each @file{/nix/store} package directory name contains a hash of all the
|
||
inputs that were used to build that package---compiler, libraries, build
|
||
scripts, etc. This direct correspondence allows users to make sure a
|
||
given package installation matches the current state of their
|
||
distribution.
|
||
|
||
This foundation allows Guix to support @dfn{transparent binary/source
|
||
deployment}. When a pre-built binary for a @file{/nix/store} path is
|
||
available from an external source, Guix just downloads it; otherwise, it
|
||
builds the package from source, locally.
|
||
|
||
@node Invoking guix-package
|
||
@section Invoking @command{guix-package}
|
||
|
||
The @command{guix-package} command is the tool that allows users to
|
||
install, upgrade, and remove packages, as well as rolling back to
|
||
previous configurations. It operates only on the user's own profile,
|
||
and works with normal user privileges (@pxref{Features}). Its syntax
|
||
is:
|
||
|
||
@example
|
||
guix-package @var{options}
|
||
@end example
|
||
|
||
Primarily, @var{options} specifies the operations to be performed during
|
||
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}
|
||
@itemx -i @var{package}
|
||
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.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}.
|
||
|
||
@item --remove=@var{package}
|
||
@itemx -r @var{package}
|
||
Remove @var{package}.
|
||
|
||
@item --upgrade=@var{regexp}
|
||
@itemx -u @var{regexp}
|
||
Upgrade all the installed packages matching @var{regexp}.
|
||
|
||
@item --profile=@var{profile}
|
||
@itemx -p @var{profile}
|
||
Use @var{profile} instead of the user's default profile.
|
||
|
||
@item --dry-run
|
||
@itemx -n
|
||
Show what would be done without actually doing it.
|
||
|
||
@item --verbose
|
||
Produce verbose output. In particular, emit the environment's build log
|
||
on the standard error port.
|
||
|
||
@item --bootstrap
|
||
Use the bootstrap Guile to build the profile. This option is only
|
||
useful to distribution developers.
|
||
|
||
@end table
|
||
|
||
In addition to these actions @command{guix-package} supports the
|
||
following options to query the current state of a profile, or the
|
||
availability of packages:
|
||
|
||
@table @option
|
||
|
||
@item --list-installed[=@var{regexp}]
|
||
@itemx -I [@var{regexp}]
|
||
List currently installed packages in the specified profile. When
|
||
@var{regexp} is specified, list only installed packages whose name
|
||
matches @var{regexp}.
|
||
|
||
For each installed package, print the following items, separated by
|
||
tabs: the package name, its version string, the part of the package that
|
||
is installed (for instance, @code{out} for the default output,
|
||
@code{include} for its headers, etc.), and the path of this package in
|
||
the store.
|
||
|
||
@item --list-available[=@var{regexp}]
|
||
@itemx -A [@var{regexp}]
|
||
List packages currently available in the software distribution. When
|
||
@var{regexp} is specified, list only installed packages whose name
|
||
matches @var{regexp}.
|
||
|
||
For each package, print the following items separated by tabs: its name,
|
||
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
|
||
|
||
|
||
@node Invoking guix-gc
|
||
@section Invoking @command{guix-gc}
|
||
|
||
@cindex garbage collector
|
||
Packages that are installed but not used may be @dfn{garbage-collected}.
|
||
The @command{guix-gc} command allows users to explicitly run the garbage
|
||
collector to reclaim space from the @file{/nix/store} directory.
|
||
|
||
The garbage collector has a set of known @dfn{roots}: any file under
|
||
@file{/nix/store} reachable from a root is considered @dfn{live} and
|
||
cannot be deleted; any other file is considered @dfn{dead} and may be
|
||
deleted. The set of garbage collector roots includes default user
|
||
profiles, and may be augmented with @command{guix-build --root}, for
|
||
example (@pxref{Invoking guix-build}).
|
||
|
||
The @command{guix-gc} command has three mode of operations: it can be
|
||
used to garbage-collect any dead files (the default), to delete specific
|
||
files (the @code{--delete} option), or to print garbage-collector
|
||
information. The available options are listed below:
|
||
|
||
@table @code
|
||
@item --collect-garbage[=@var{min}]
|
||
@itemx -C [@var{min}]
|
||
Collect garbage---i.e., unreachable @file{/nix/store} files and
|
||
sub-directories. This is the default operation when no option is
|
||
specified.
|
||
|
||
When @var{min} is given, stop once @var{min} bytes have been collected.
|
||
@var{min} may be a number of bytes, or it may include a unit as a
|
||
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
|
||
|
||
When @var{min} is omitted, collect all the garbage.
|
||
|
||
@item --delete
|
||
@itemx -d
|
||
Attempt to delete all the store files and directories specified as
|
||
arguments. This fails if some of the files are not in the store, or if
|
||
they are still live.
|
||
|
||
@item --list-dead
|
||
Show the list of dead files and directories still present in the
|
||
store---i.e., files and directories no longer reachable from any root.
|
||
|
||
@item --list-live
|
||
Show the list of live store files and directories.
|
||
@end table
|
||
|
||
|
||
@c *********************************************************************
|
||
@node Programming Interface
|
||
@chapter Programming Interface
|
||
|
||
GNU Guix provides several Scheme programming interfaces (APIs) to
|
||
define, build, and query packages. The first interface allows users to
|
||
write high-level package definitions. These definitions refer to
|
||
familiar packaging concepts, such as the name and version of a package,
|
||
its build system, and its dependencies. These definitions can then be
|
||
turned into concrete build actions.
|
||
|
||
Build actions are performed by the Guix daemon, on behalf of users. In a
|
||
standard setup, the daemon has write access to the store---the
|
||
@file{/nix/store} directory---whereas users do not. The recommended
|
||
setup also has the daemon perform builds in chroots, under a specific
|
||
build users, to minimize interference with the rest of the system.
|
||
|
||
@cindex derivation
|
||
Lower-level APIs are available to interact with the daemon and the
|
||
store. To instruct the daemon to perform a build action, users actually
|
||
provide it with a @dfn{derivation}. A derivation is a low-level
|
||
representation of the build actions to be taken, and the environment in
|
||
which they should occur---derivations are to package definitions what
|
||
assembly is to C programs.
|
||
|
||
This chapter describes all these APIs in turn, starting from high-level
|
||
package definitions.
|
||
|
||
@menu
|
||
* Defining Packages:: Defining new packages.
|
||
* The Store:: Manipulating the package store.
|
||
* Derivations:: Low-level interface to package derivations.
|
||
@end menu
|
||
|
||
@node Defining Packages
|
||
@section Defining Packages
|
||
|
||
The high-level interface to package definitions is implemented in the
|
||
@code{(guix packages)} and @code{(guix build-system)} modules. As an
|
||
example, the package definition, or @dfn{recipe}, for the GNU Hello
|
||
package looks like this:
|
||
|
||
@example
|
||
(use-modules (guix packages)
|
||
(guix download)
|
||
(guix build-system gnu)
|
||
(guix licenses))
|
||
|
||
(define hello
|
||
(package
|
||
(name "hello")
|
||
(version "2.8")
|
||
(source (origin
|
||
(method url-fetch)
|
||
(uri (string-append "mirror://gnu/hello/hello-" version
|
||
".tar.gz"))
|
||
(sha256
|
||
(base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
|
||
(build-system gnu-build-system)
|
||
(inputs `(("gawk" ,gawk)))
|
||
(synopsis "GNU Hello")
|
||
(description "Yeah...")
|
||
(home-page "http://www.gnu.org/software/hello/")
|
||
(license gpl3+)))
|
||
@end example
|
||
|
||
@noindent
|
||
Without being a Scheme expert, the reader may have guessed the meaning
|
||
of the various fields here. This expression binds variable @var{hello}
|
||
to a @code{<package>} object, which is essentially a record
|
||
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
|
||
This package object can be inspected using procedures found in the
|
||
@code{(guix packages)} module; for instance, @code{(package-name hello)}
|
||
returns---surprise!---@code{"hello"}.
|
||
|
||
There are a few points worth noting in the above package definition:
|
||
|
||
@itemize
|
||
@item
|
||
The @code{source} field of the package is an @code{<origin>} object.
|
||
Here, the @code{url-fetch} method from @code{(guix download)} is used,
|
||
meaning that the source is a file to be downloaded over FTP or HTTP.
|
||
|
||
The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
|
||
the GNU mirrors defined in @code{(guix download)}.
|
||
|
||
The @code{sha256} field specifies the expected SHA256 hash of the file
|
||
being downloaded. It is mandatory, and allows Guix to check the
|
||
integrity of the file. The @code{(base32 @dots{})} form introduces the
|
||
base32 representation of the hash. A convenient way to obtain this
|
||
information is with the @code{guix-download} tool.
|
||
|
||
@item
|
||
@cindex GNU Build System
|
||
The @code{build-system} field is set to @var{gnu-build-system}. The
|
||
@var{gnu-build-system} variable is defined in the @code{(guix
|
||
build-system gnu)} module, and is bound to a @code{<build-system>}
|
||
object.
|
||
|
||
Naturally, @var{gnu-build-system} represents the familiar GNU Build
|
||
System, and variants thereof (@pxref{Configuration, configuration and
|
||
makefile conventions,, standards, GNU Coding Standards}). In a
|
||
nutshell, packages using the GNU Build System may be configured, built,
|
||
and installed with the usual @code{./configure && make && make check &&
|
||
make install} command sequence. This is what @var{gnu-build-system}
|
||
does.
|
||
|
||
In addition, @var{gnu-build-system} ensures that the ``standard''
|
||
environment for GNU packages is available. This includes tools such as
|
||
GCC, Coreutils, Bash, Make, Diffutils, and Patch.
|
||
|
||
@item
|
||
The @code{inputs} field specifies inputs to the build process---i.e.,
|
||
build-time or run-time dependencies of the package. Here, we define an
|
||
input called @code{"gawk"} whose value is that of the @var{gawk}
|
||
variable; @var{gawk} is itself bound to a @code{<package>} object.
|
||
|
||
Note that GCC, Coreutils, Bash, and other essential tools do not need to
|
||
be specified as inputs here. Instead, @var{gnu-build-system} takes care
|
||
of ensuring that they are present.
|
||
|
||
However, any other dependencies need to be specified in the
|
||
@code{inputs} field. Any dependency not specified here will simply be
|
||
unavailable to the build process, possibly leading to a build failure.
|
||
@end itemize
|
||
|
||
There are other fields that package definitions may provide. Of
|
||
particular interest is the @code{arguments} field. When specified, it
|
||
must be bound to a list of additional arguments to be passed to the
|
||
build system. For instance, the above definition could be augmented
|
||
with the following field initializer:
|
||
|
||
@example
|
||
(arguments `(#:tests? #f
|
||
#:configure-flags '("--enable-silent-rules")))
|
||
@end example
|
||
|
||
@noindent
|
||
These are keyword arguments (@pxref{Optional Arguments, keyword
|
||
arguments in Guile,, guile, GNU Guile Reference Manual}). They are
|
||
passed to @var{gnu-build-system}, which interprets them as meaning ``do
|
||
not run @code{make check}'', and ``run @file{configure} with the
|
||
@code{--enable-silent-rules} flag''.
|
||
|
||
Once a package definition is in place@footnote{Simple package
|
||
definitions like the one above may be automatically converted from the
|
||
Nixpkgs distribution using the @command{guix-import} command.}, the
|
||
package may actually be built using the @code{guix-build} command-line
|
||
tool (@pxref{Invoking guix-build}).
|
||
|
||
Behind the scenes, a derivation corresponding to the @code{<package>}
|
||
object is first computed by the @code{package-derivation} procedure.
|
||
That derivation is stored in a @code{.drv} file under @file{/nix/store}.
|
||
The build actions it prescribes may then be realized by using the
|
||
@code{build-derivations} procedure (@pxref{The Store}).
|
||
|
||
@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
|
||
Return the derivation of @var{package} for @var{system}. The result is
|
||
the file name of the derivation---i.e., a @code{.drv} file under
|
||
@code{/nix/store}.
|
||
|
||
@var{package} must be a valid @code{<package>} object, and @var{system}
|
||
must be a string denoting the target system type---e.g.,
|
||
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
|
||
must be a connection to the daemon, which operates on the store
|
||
(@pxref{The Store}).
|
||
@end deffn
|
||
|
||
@node The Store
|
||
@section The Store
|
||
|
||
@code{(guix store)}
|
||
|
||
@node Derivations
|
||
@section Derivations
|
||
|
||
@code{(guix derivations)}
|
||
|
||
@c *********************************************************************
|
||
@node Utilities
|
||
@chapter Utilities
|
||
|
||
@menu
|
||
* Invoking guix-build:: Building packages from the command line.
|
||
@end menu
|
||
|
||
@node Invoking guix-build
|
||
@section Invoking @command{guix-build}
|
||
|
||
The @command{guix-build} command builds packages or derivations and
|
||
their dependencies, and prints the resulting store paths. It is mainly
|
||
useful for distribution developers. The general syntax is:
|
||
|
||
@example
|
||
guix-build @var{options} @var{package-or-derivation}@dots{}
|
||
@end example
|
||
|
||
@var{package-or-derivation} may be either the name of a package found in
|
||
the software distribution such as @code{coreutils}, or a derivation such
|
||
as @file{/nix/store/xxx-coreutils-8.19.drv}. Alternatively, the
|
||
@code{--expression} option may be used to specify a Scheme expression
|
||
that evaluates to a package; this is useful when disambiguation among
|
||
several same-named packages or package variants is needed.
|
||
|
||
The @var{options} may be zero or more of the following:
|
||
|
||
@table @code
|
||
|
||
@item --expression=@var{expr}
|
||
@itemx -e @var{expr}
|
||
Build the package @var{expr} evaluates to.
|
||
|
||
For example, @var{expr} may be @code{(@@ (distro packages guile)
|
||
guile-1.8)}, which unambiguously designates this specific variant of
|
||
version 1.8 of Guile.
|
||
|
||
@item --source
|
||
@itemx -S
|
||
Build the packages' source derivations, rather than the packages
|
||
themselves.
|
||
|
||
For instance, @code{guix-build -S gcc} returns something like
|
||
@file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
|
||
|
||
@item --system=@var{system}
|
||
@itemx -s @var{system}
|
||
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
|
||
the host's system type.
|
||
|
||
An example use of this is on Linux-based systems, which can emulate
|
||
different personalities. For instance, passing
|
||
@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
|
||
to build packages in a complete 32-bit environment.
|
||
|
||
@item --derivations
|
||
@itemx -d
|
||
Return the derivation paths, not the output paths, of the given
|
||
packages.
|
||
|
||
@item --keep-failed
|
||
@itemx -K
|
||
Keep the build tree of failed builds. Thus, if a build fail, its build
|
||
tree is kept under @file{/tmp}, in a directory whose name is shown at
|
||
the end of the build log. This is useful when debugging build issues.
|
||
|
||
@item --dry-run
|
||
@itemx -n
|
||
Do not build the derivations.
|
||
|
||
@item --no-substitutes
|
||
Build instead of resorting to pre-built substitutes.
|
||
|
||
@item --cores=@var{n}
|
||
@itemx -c @var{n}
|
||
Allow the use of up to @var{n} CPU cores for the build. The special
|
||
value @code{0} means to use as many CPU cores as available.
|
||
|
||
@item --root=@var{file}
|
||
@itemx -r @var{file}
|
||
Make @var{file} a symlink to the result, and register it as a garbage
|
||
collector root.
|
||
|
||
@item --verbosity=@var{level}
|
||
Use the given verbosity level. @var{level} must be an integer between 0
|
||
and 5; higher means more verbose output. Setting a level of 4 or more
|
||
may be helpful when debugging setup issues with the build daemon.
|
||
|
||
@end table
|
||
|
||
Behind the scenes, @command{guix-build} is essentially an interface to
|
||
the @code{package-derivation} procedure of the @code{(guix packages)}
|
||
module, and to the @code{build-derivations} procedure of the @code{(guix
|
||
store)} module.
|
||
|
||
|
||
@c *********************************************************************
|
||
@node Acknowledgments
|
||
@chapter Acknowledgments
|
||
|
||
Guix is based on the Nix package manager, which was designed and
|
||
implemented by Eelco Dolstra. Nix pioneered functional package
|
||
management, and promoted unprecedented features, such as transactional
|
||
package upgrades and rollbacks, per-user profiles, and referentially
|
||
transparent build processes. Without this work, Guix would not exist.
|
||
|
||
The Nix-based software distributions, Nixpkgs and NixOS, have also been
|
||
an inspiration for Guix.
|
||
|
||
@c *********************************************************************
|
||
@node GNU Free Documentation License
|
||
@appendix GNU Free Documentation License
|
||
|
||
@include fdl-1.3.texi
|
||
|
||
@c *********************************************************************
|
||
@node Concept Index
|
||
@unnumbered Concept Index
|
||
@printindex cp
|
||
|
||
@node Function Index
|
||
@unnumbered Function Index
|
||
@printindex fn
|
||
|
||
@bye
|
||
|
||
@c Local Variables:
|
||
@c ispell-local-dictionary: "american";
|
||
@c End:
|