@c %**end of header
@include version.texi
-@set YEARS 2012, 2013
+
+@copying
+Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
+Copyright @copyright{} 2013, 2014 Andreas Enge@*
+Copyright @copyright{} 2013 Nikita Karetnikov
+
+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
@dircategory Package management
@direntry
Edition @value{EDITION} @*
@value{UPDATED} @*
-Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov
-
-@ifinfo
-@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 ifinfo
-
+@insertcopying
@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 *********************************************************************
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, Andreas Enge, Nikita Karetnikov
-
-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.
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 isolated environments (or @dfn{chroots}), where only their
+build processes in isolated environments (or @dfn{containers}), where only their
explicit inputs are visible.
@cindex store
The result of package build functions is @dfn{cached} in the file
system, in a special directory called @dfn{the store} (@pxref{The
Store}). Each package is installed in a directory of its own, in the
-store---by default under @file{/nix/store}. The directory name contains
+store---by default under @file{/gnu/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.
same @code{--with-store-dir} value, but also the same
@code{--localstatedir} value. The latter is essential because it
specifies where the database that stores metadata about the store is
-located, among other things. The default values are
+located, among other things. The default values for Nix are
@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
Note that @code{--disable-daemon} is not required if
your goal is to share the store with Nix.
@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
+are all performed by a specialized process, the @dfn{build 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.
+The following sections explain how to prepare the build daemon's
+environment.
+
+@menu
+* Build Environment Setup:: Preparing the isolated build environment.
+* Daemon Offload Setup:: Offloading builds to remote machines.
+@end menu
+
+@node Build Environment Setup
+@subsection Build Environment Setup
+
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
+administrator; @file{/gnu/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
do
useradd -g guix-builder -G guix-builder \
-d /var/empty -s `which nologin` \
- -c "Guix build user $i" guix-builder$i;
+ -c "Guix build user $i" --system \
+ guix-builder$i;
done
@end example
# guix-daemon --build-users-group=guix-builder
@end example
+@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
the @code{guix-builder} users. On GNU/Linux, by default, the chroot
-environment contains nothing but the @code{/dev} and @code{/proc}
-directories@footnote{On some systems @code{/dev/shm}, which supports
-shared memory, is a symlink to another directory such as
-@code{/run/shm}, that is @emph{not} is the chroot. When that is the
-case, shared memory support is unavailable in the chroot environment.
-The workaround is to make sure that @file{/dev/shm} is directly a
-@code{tmpfs} mount point.}.
-
-Guix may also be used in a single-user setup, with @command{guix-daemon}
-running as an 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
+environment contains nothing but:
+
+@c Keep this list in sync with libstore/build.cc! -----------------------
+@itemize
+@item
+a minimal @code{/dev} directory, created mostly independently from the
+host @code{/dev}@footnote{``Mostly'', because while the set of files
+that appear in the chroot's @code{/dev} is fixed, most of these files
+can only be created if the host has them.};
+
+@item
+the @code{/proc} directory; it only shows the container's processes
+since a separate PID name space is used;
+
+@item
+@file{/etc/passwd} with an entry for the current user and an entry for
+user @file{nobody};
+
+@item
+@file{/etc/group} with an entry for the user's group;
+
+@item
+@file{/etc/hosts} with an entry that maps @code{localhost} to
+@code{127.0.0.1};
+
+@item
+a writable @file{/tmp} directory.
+@end itemize
+
+If you are installing Guix as an unprivileged user, 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 Daemon Offload Setup
+@subsection Using the Offload Facility
+
+@cindex offloading
+@cindex build hook
+When desired, the build daemon can @dfn{offload}
+derivation builds to other machines
+running Guix, using the @code{offload} @dfn{build hook}. When that
+feature is enabled, a list of user-specified build machines is read from
+@file{/etc/guix/machines.scm}; anytime a build is requested, for
+instance via @code{guix build}, the daemon attempts to offload it to one
+of the machines that satisfies the derivation's constraints, in
+particular its system type---e.g., @file{x86_64-linux}. Missing
+prerequisites for the build are copied over SSH to the target machine,
+which then proceeds with the build; upon success the output(s) of the
+build are copied back to the initial machine.
+
+The @file{/etc/guix/machines.scm} file typically looks like this:
+
+@example
+(list (build-machine
+ (name "eightysix.example.org")
+ (system "x86_64-linux")
+ (user "bob")
+ (speed 2.)) ; incredibly fast!
+
+ (build-machine
+ (name "meeps.example.org")
+ (system "mips64el-linux")
+ (user "alice")
+ (private-key
+ (string-append (getenv "HOME")
+ "/.ssh/id-rsa-for-guix"))))
+@end example
+
+@noindent
+In the example above we specify a list of two build machines, one for
+the @code{x86_64} architecture and one for the @code{mips64el}
+architecture.
+
+In fact, this file is---not surprisingly!---a Scheme file that is
+evaluated when the @code{offload} hook is started. Its return value
+must be a list of @code{build-machine} objects. While this example
+shows a fixed list of build machines, one could imagine, say, using
+DNS-SD to return a list of potential build machines discovered in the
+local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
+Avahi in Guile Scheme Programs}).
+
+The compulsory fields for a @code{build-machine} declaration are:
+
+@table @code
+
+@item name
+The remote machine's host name.
+
+@item system
+The remote machine's system type.
+
+@item user
+The user account to use when connecting to the remote machine over SSH.
+Note that the SSH key pair must @emph{not} be passphrase-protected, to
+allow non-interactive logins.
+
+@end table
+
+@noindent
+A number of optional fields may be specified:
+
+@table @code
+
+@item port
+Port number of the machine's SSH server (default: 22).
+
+@item private-key
+The SSH private key file to use when connecting to the machine.
+
+@item parallel-builds
+The number of builds that may run in parallel on the machine (1 by
+default.)
+
+@item speed
+A ``relative speed factor''. The offload scheduler will tend to prefer
+machines with a higher speed factor.
+
+@item features
+A list of strings denoting specific features supported by the machine.
+An example is @code{"kvm"} for machines that have the KVM Linux modules
+and corresponding hardware support. Derivations can request features by
+name, and they will be scheduled on matching build machines.
+
+@end table
+
+The @code{guix} command must be in the search path on the build
+machines, since offloading works by invoking the @code{guix archive} and
+@code{guix build} commands.
+
+There's one last thing to do once @file{machines.scm} is in place. As
+explained above, when offloading, files are transferred back and forth
+between the machine stores. For this to work, you need to generate a
+key pair to allow the daemon to export signed archives of files from the
+store (@pxref{Invoking guix archive}):
+
+@example
+# guix archive --generate-key
+@end example
+
+@noindent
+Thus, when receiving files, a machine's build daemon can make sure they
+are genuine, have not been tampered with, and that they are signed by an
+authorized key.
+
+
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
@noindent
For details on how to set it up, @ref{Setting Up the Daemon}.
+@cindex chroot
+@cindex container, build environment
+@cindex build environment
+@cindex reproducible builds
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
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}.
+@file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
+@dfn{container}: in addition to having its own file system tree, it has
+a separate mount name space, its own PID name space, network name space,
+etc. This helps achieve reproducible builds (@pxref{Features}).
The following command-line options are supported:
the Daemon, build users}).
@item --no-substitutes
+@cindex substitutes
Do not use substitutes for build products. That is, always build things
-locally instead of allowing downloads of pre-built binaries.
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
+
+By default substitutes are used, unless the client---such as the
+@command{guix package} command---is explicitly invoked with
+@code{--no-substitutes}.
+
+When the daemon runs with @code{--no-substitutes}, clients can still
+explicitly enable substitution @i{via} the @code{set-build-options}
+remote procedure call (@pxref{The Store}).
+
+@cindex build hook
+@item --no-build-hook
+Do not use the @dfn{build hook}.
+
+The build hook is a helper program that the daemon can start and to
+which it submits build requests. This mechanism is used to offload
+builds to other machines (@pxref{Daemon Offload Setup}).
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
slightly increases the input/output load at the end of a build process.
This option disables this.
+@item --gc-keep-outputs[=yes|no]
+Tell whether the garbage collector (GC) must keep outputs of live
+derivations.
+
+When set to ``yes'', the GC will keep the outputs of any live derivation
+available in the store---the @code{.drv} files. The default is ``no'',
+meaning that derivation outputs are kept only if they are GC roots.
+
+@item --gc-keep-derivations[=yes|no]
+Tell whether the garbage collector (GC) must keep derivations
+corresponding to live outputs.
+
+When set to ``yes'', as is the case by default, the GC keeps
+derivations---i.e., @code{.drv} files---as long as at least one of their
+outputs is live. This allows users to keep track of the origins of
+items in their store. Setting it to ``no'' saves a bit of disk space.
+
+Note that when both @code{--gc-keep-derivations} and
+@code{--gc-keep-outputs} are used, the effect is to keep all the build
+prerequisites (the sources, compiler, libraries, and other build-time
+tools) of live objects in the store, regardless of whether these
+prerequisites are live. This is convenient for developers since it
+saves rebuilds or downloads.
+
@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.
@menu
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
-* Packages with Multiple Outputs:: Single source package, multiple outputs.
+* Substitutes:: Downloading pre-built binaries.
+* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
+* Invoking guix archive:: Exporting and importing store files.
@end menu
@node 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.
+@file{/gnu/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
For example, @code{alice} installs GCC 4.7.2. As a result,
@file{/home/alice/.guix-profile/bin/gcc} points to
-@file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
+@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
@code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
simply continues to point to
-@file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
+@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
coexist on the same system without any interference.
The @command{guix package} command is the central tool to manage
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.
+of their profile, which was known to work well. Similarly, the global
+system configuration is subject to transactional upgrades and roll-back
+(@pxref{Using the Configuration System}).
All those packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by the user
generations of their profile so that the packages they refer to can be
collected.
+@cindex reproducibility
+@cindex reproducible builds
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
+Each @file{/gnu/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, and helps maximize @dfn{reproducibility}.
+distribution. It also helps maximize @dfn{build reproducibility}:
+thanks to the isolated build environments that are used, a given build
+is likely to yield bit-identical files when performed on different
+machines (@pxref{Invoking guix-daemon, container}).
+@cindex substitutes
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.
+deployment}. When a pre-built binary for a @file{/gnu/store} item is
+available from an external source---a @dfn{substitute}, Guix just
+downloads it and unpacks it;
+otherwise, it builds the package from source, locally
+(@pxref{Substitutes}).
@node Invoking guix package
@section Invoking @command{guix package}
previous generations of the profile remain available, should the user
want to roll back.
+For example, to remove @code{lua} and install @code{guile} and
+@code{guile-cairo} in a single transaction:
+
+@example
+guix package -r lua -i guile guile-cairo
+@end example
+
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
@table @code
-@item --install=@var{package}
-@itemx -i @var{package}
-Install @var{package}.
+@item --install=@var{package} @dots{}
+@itemx -i @var{package} @dots{}
+Install the specified @var{package}s.
-@var{package} may specify either a simple package name, such as
+Each @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}. If no version number is specified, the
newest available version will be selected. 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}
-(@pxref{Packages with Multiple Outputs}).
+(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
+name (and optionally version) are searched for among the GNU
+distribution modules (@pxref{Package Modules}).
@cindex propagated inputs
Sometimes packages have @dfn{propagated inputs}: these are dependencies
in the profile; removing MPC also removes MPFR and GMP---unless they had
also been explicitly installed independently.
-Besides, packages sometime rely on the definition of environment
+Besides, packages sometimes rely on the definition of environment
variables for their search paths (see explanation of
-@code{--search-paths} below.) Any missing or possibly incorrect
+@code{--search-paths} below). Any missing or possibly incorrect
environment variable definitions are reported here.
@c XXX: keep me up-to-date
package, which may be insufficient when needing a specific output of a
multiple-output package.
-@item --remove=@var{package}
-@itemx -r @var{package}
-Remove @var{package}.
+@item --remove=@var{package} @dots{}
+@itemx -r @var{package} @dots{}
+Remove the specified @var{package}s.
+
+As for @code{--install}, each @var{package} may specify a version number
+and/or output name in addition to the package name. For instance,
+@code{-r glibc:debug} would remove the @code{debug} output of
+@code{glibc}.
-@item --upgrade[=@var{regexp}]
-@itemx -u [@var{regexp}]
-Upgrade all the installed packages. When @var{regexp} is specified, upgrade
-only installed packages whose name matches @var{regexp}.
+@item --upgrade[=@var{regexp} @dots{}]
+@itemx -u [@var{regexp} @dots{}]
+Upgrade all the installed packages. If one or more @var{regexp}s are
+specified, upgrade only installed packages whose name matches a
+@var{regexp}.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
before any other actions.
When rolling back from the first generation that actually contains
-installed packages, the profile is made to point to the @dfn{empty
-profile}, also known as @dfn{profile zero}---i.e., it contains no files
-apart from its own meta-data.
+installed packages, the profile is made to point to the @dfn{zeroth
+generation}, which contains no files apart from its own meta-data.
Installing, removing, or upgrading packages from a generation that has
been rolled back to overwrites previous future generations. Thus, the
@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 --fallback
-When substituting a pre-built binary fails, fall back to building
-packages locally.
-
-@item --no-substitutes
-@itemx --max-silent-time=@var{seconds}
-Same as for @command{guix build} (@pxref{Invoking guix build}).
-
@item --verbose
Produce verbose output. In particular, emit the environment's build log
on the standard error port.
version: 7.2alpha6
@end example
+Similarly, to show the name of all the packages available under the
+terms of the GNU@tie{}LGPL version 3:
+
+@example
+$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
+name: elfutils
+
+name: gmp
+@dots{}
+@end example
+
@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}.
+List the currently installed packages in the specified profile, with the
+most recently installed packages shown last. 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
its version string, the parts of the package (@pxref{Packages with
Multiple Outputs}), and the source location of its definition.
+@item --list-generations[=@var{pattern}]
+@itemx -l [@var{pattern}]
+Return a list of generations along with their creation dates; for each
+generation, show the installed packages, with the most recently
+installed packages shown last. Note that the zeroth generation is never
+shown.
+
+For each installed package, print the following items, separated by
+tabs: the name of a package, its version string, the part of the package
+that is installed (@pxref{Packages with Multiple Outputs}), and the
+location of this package in the store.
+
+When @var{pattern} is used, the command returns only matching
+generations. Valid patterns include:
+
+@itemize
+@item @emph{Integers and comma-separated integers}. Both patterns denote
+generation numbers. For instance, @code{--list-generations=1} returns
+the first one.
+
+And @code{--list-generations=1,8,2} outputs three generations in the
+specified order. Neither spaces nor trailing commas are allowed.
+
+@item @emph{Ranges}. @code{--list-generations=2..9} prints the
+specified generations and everything in between. Note that the start of
+a range must be lesser than its end.
+
+It is also possible to omit the endpoint. For example,
+@code{--list-generations=2..}, returns all generations starting from the
+second one.
+
+@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
+or months by passing an integer along with the first letter of the
+duration. For example, @code{--list-generations=20d} lists generations
+that are up to 20 days old.
+@end itemize
+
+@item --delete-generations[=@var{pattern}]
+@itemx -d [@var{pattern}]
+When @var{pattern} is omitted, delete all generations except the current
+one.
+
+This command accepts the same patterns as @option{--list-generations}.
+When @var{pattern} is specified, delete the matching generations. When
+@var{pattern} specifies a duration, generations @emph{older} than the
+specified duration match. For instance, @code{--delete-generations=1m}
+deletes generations that are more than one month old.
+
+If the current generation matches, it is deleted atomically---i.e., by
+switching to the previous available generation. Note that the zeroth
+generation is never deleted.
+
+Note that deleting generations prevents roll-back to them.
+Consequently, this command must be used with care.
+
@end table
+Finally, since @command{guix package} may actually start build
+processes, it supports all the common build options that @command{guix
+build} supports (@pxref{Invoking guix build, common build options}).
+
+@node Substitutes
+@section Substitutes
+
+@cindex substitutes
+@cindex pre-built binaries
+Guix supports transparent source/binary deployment, which means that it
+can either build things locally, or download pre-built items from a
+server. We call these pre-built items @dfn{substitutes}---they are
+substitutes for local build results. In many cases, downloading a
+substitute is much faster than building things locally.
+
+Substitutes can be anything resulting from a derivation build
+(@pxref{Derivations}). Of course, in the common case, they are
+pre-built package binaries, but source tarballs, for instance, which
+also result from derivation builds, can be available as substitutes.
+
+The @code{hydra.gnu.org} server is a front-end to a build farm that
+builds packages from the GNU distribution continuously for some
+architectures, and makes them available as substitutes.
+
+@cindex security
+@cindex digital signatures
+To allow Guix to download substitutes from @code{hydra.gnu.org}, you
+must add its public key to the access control list (ACL) of archive
+imports, using the @command{guix archive} command (@pxref{Invoking guix
+archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
+be compromised and to serve genuine substitutes.
+
+This public key is installed along with Guix, in
+@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
+the installation prefix of Guix. If you installed Guix from source,
+make sure you checked the GPG signature of
+@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
+Then, you can run something like this:
+
+@example
+# guix archive --authorize < hydra.gnu.org.pub
+@end example
+
+Once this is in place, the output of a command like @code{guix build}
+should change from something like:
+
+@example
+$ guix build emacs --dry-run
+The following derivations would be built:
+ /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
+ /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
+ /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
+ /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
+@dots{}
+@end example
+
+@noindent
+to something like:
+
+@example
+$ guix build emacs --dry-run
+The following files would be downloaded:
+ /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
+ /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
+ /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
+ /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
+@dots{}
+@end example
+
+@noindent
+This indicates that substitutes from @code{hydra.gnu.org} are usable and
+will be downloaded, when possible, for future builds.
+
+Guix ignores substitutes that are not signed, or that are not signed by
+one of the keys listed in the ACL. It also detects and raises an error
+when attempting to use a substitute that has been tampered with.
+
+The substitute mechanism can be disabled globally by running
+@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
+guix-daemon}). It can also be disabled temporarily by passing the
+@code{--no-substitutes} option to @command{guix package}, @command{guix
+build}, and other command-line tools.
+
+
+Today, each individual's control over their own computing is at the
+mercy of institutions, corporations, and groups with enough power and
+determination to subvert the computing infrastructure and exploit its
+weaknesses. While using @code{hydra.gnu.org} substitutes can be
+convenient, we encourage users to also build on their own, or even run
+their own build farm, such that @code{hydra.gnu.org} is less of an
+interesting target.
+
+Guix has the foundations to maximize build reproducibility
+(@pxref{Features}). In most cases, independent builds of a given
+package or derivation should yield bit-identical results. Thus, through
+a diverse set of independent package builds, we can strengthen the
+integrity of our systems.
+
+In the future, we want Guix to have support to publish and retrieve
+binaries to/from other users, in a peer-to-peer fashion. If you would
+like to discuss this project, join us on @email{guix-devel@@gnu.org}.
+
+
@node Packages with Multiple Outputs
@section Packages with Multiple Outputs
@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.
+collector to reclaim space from the @file{/gnu/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
+@file{/gnu/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}).
+Prior to running @code{guix gc --collect-garbage} to make space, it is
+often useful to remove old generations from user profiles; that way, old
+package builds referenced by those generations can be reclaimed. This
+is achieved by running @code{guix package --delete-generations}
+(@pxref{Invoking guix package}).
+
The @command{guix gc} command has three modes of operation: 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
@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
-Collect garbage---i.e., unreachable @file{/nix/store} files and
+Collect garbage---i.e., unreachable @file{/gnu/store} files and
sub-directories. This is the default operation when no option is
specified.
@item --verbose
Produce verbose output, writing build logs to the standard error output.
+@item --url=@var{url}
+Download the source tarball of Guix from @var{url}.
+
+By default, the tarball is taken from its canonical address at
+@code{gnu.org}, for the stable branch of Guix.
+
@item --bootstrap
Use the bootstrap Guile to build the latest Guix. This option is only
useful to Guix developers.
@end table
+
+@node Invoking guix archive
+@section Invoking @command{guix archive}
+
+The @command{guix archive} command allows users to @dfn{export} files
+from the store into a single archive, and to later @dfn{import} them.
+In particular, it allows store files to be transferred from one machine
+to another machine's store. For example, to transfer the @code{emacs}
+package to a machine connected over SSH, one would run:
+
+@example
+guix archive --export emacs | ssh the-machine guix archive --import
+@end example
+
+@noindent
+However, note that, in this example, all of @code{emacs} and its
+dependencies are transferred, regardless of what is already available in
+the target machine's store. The @code{--missing} option can help figure
+out which items are missing from the target's store.
+
+Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
+comparable in spirit to `tar', but with a few noteworthy differences
+that make it more appropriate for our purposes. First, rather than
+recording all Unix meta-data for each file, the Nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed. Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order. This makes archive production fully
+deterministic.
+
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended. When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
+@c FIXME: Add xref to daemon doc about signatures.
+
+The main options are:
+
+@table @code
+@item --export
+Export the specified store files or packages (see below.) Write the
+resulting archive to the standard output.
+
+@item --import
+Read an archive from the standard input, and import the files listed
+therein into the store. Abort if the archive has an invalid digital
+signature, or if it is signed by a public key not among the authorized
+keys (see @code{--authorize} below.)
+
+@item --missing
+Read a list of store file names from the standard input, one per line,
+and write on the standard output the subset of these files missing from
+the store.
+
+@item --generate-key[=@var{parameters}]
+@cindex signing, archives
+Generate a new key pair for the daemons. This is a prerequisite before
+archives can be exported with @code{--export}. Note that this operation
+usually takes time, because it needs to gather enough entropy to
+generate the key pair.
+
+The generated key pair is typically stored under @file{/etc/guix}, in
+@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
+key, which must be kept secret.) When @var{parameters} is omitted, it
+is a 4096-bit RSA key. Alternately, @var{parameters} can specify
+@code{genkey} parameters suitable for Libgcrypt (@pxref{General
+public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
+Libgcrypt Reference Manual}).
+
+@item --authorize
+@cindex authorizing, archives
+Authorize imports signed by the public key passed on standard input.
+The public key must be in ``s-expression advanced format''---i.e., the
+same format as the @file{signing-key.pub} file.
+
+The list of authorized keys is kept in the human-editable file
+@file{/etc/guix/acl}. The file contains
+@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+s-expressions''} and is structured as an access-control list in the
+@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+(SPKI)}.
+@end table
+
+To export store files as an archive to the standard output, run:
+
+@example
+guix archive --export @var{options} @var{specifications}...
+@end example
+
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}). For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
+
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
+
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them. The build process may be controlled with the
+same options that can be passed to the @command{guix build} command
+(@pxref{Invoking guix build, common build options}).
+
+
@c *********************************************************************
@node Programming Interface
@chapter Programming Interface
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
+@file{/gnu/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.
package definitions.
@menu
-* Defining Packages:: Defining new packages.
-* The Store:: Manipulating the package store.
-* Derivations:: Low-level interface to package derivations.
+* Defining Packages:: Defining new packages.
+* Build Systems:: Specifying how packages are built.
+* The Store:: Manipulating the package store.
+* Derivations:: Low-level interface to package derivations.
+* The Store Monad:: Purely functional interface to the store.
+* G-Expressions:: Manipulating build expressions.
@end menu
@node Defining Packages
package looks like this:
@example
-(use-modules (guix packages)
- (guix download)
- (guix build-system gnu)
- (guix licenses))
+(define-module (gnu packages hello)
+ #:use-module (guix packages)
+ #:use-module (guix download)
+ #:use-module (guix build-system gnu)
+ #:use-module (guix licenses))
(define hello
(package
(sha256
(base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
(build-system gnu-build-system)
+ (arguments `(#:configure-flags '("--enable-silent-rules")))
(inputs `(("gawk" ,gawk)))
- (synopsis "GNU Hello")
- (description "Yeah...")
+ (synopsis "Hello, GNU world: An example GNU package")
+ (description "Guess what GNU Hello prints!")
(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}
+of the various fields here. This expression binds variable @code{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"}.
+In the example above, @var{hello} is defined into a module of its own,
+@code{(gnu packages hello)}. Technically, this is not strictly
+necessary, but it is convenient to do so: all the packages defined in
+modules under @code{(gnu packages @dots{})} are automatically known to
+the command-line tools (@pxref{Package Modules}).
+
There are a few points worth noting in the above package definition:
@itemize
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).
+@cindex patches
+When needed, the @code{origin} form can also have a @code{patches} field
+listing patches to be applied, and a @code{snippet} field giving a
+Scheme expression to modify the source code.
+
@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.
+The @code{build-system} field specifies the procedure to build the
+package (@pxref{Build Systems}). Here, @var{gnu-build-system}
+represents the familiar GNU Build System, where packages may be
+configured, built, and installed with the usual @code{./configure &&
+make && make check && make install} command sequence.
+
+@item
+The @code{arguments} field specifies options for the build system
+(@pxref{Build Systems}). Here it is interpreted by
+@var{gnu-build-system} as a request run @file{configure} with the
+@code{--enable-silent-rules} flag.
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
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.
+of ensuring that they are present (@pxref{Build Systems}).
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''. The value of these keyword
-parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
-Guile process launched by the daemon (@pxref{Derivations}).
-
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}). Eventually, updating the package
-definition to a new upstream version can be partly automated by the
-@command{guix refresh} command (@pxref{Invoking guix refresh}).
+tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
+more information on how to test package definitions.
+
+Eventually, updating the package definition to a new upstream version
+can be partly automated by the @command{guix refresh} command
+(@pxref{Invoking guix refresh}).
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}.
+That derivation is stored in a @code{.drv} file under @file{/gnu/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 path and corresponding @code{<derivation>} object
-of @var{package} for @var{system} (@pxref{Derivations}).
+Return the @code{<derivation>} object of @var{package} for @var{system}
+(@pxref{Derivations}).
@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@deffn {Scheme Procedure} package-cross-derivation @var{store} @
@var{package} @var{target} [@var{system}]
-Return the derivation path and corresponding @code{<derivation>} object
-of @var{package} cross-built from @var{system} to @var{target}.
+Return the @code{<derivation>} object of @var{package} cross-built from
+@var{system} to @var{target}.
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
@end deffn
+@node Build Systems
+@section Build Systems
+
+@cindex build system
+Each package definition specifies a @dfn{build system} and arguments for
+that build system (@pxref{Defining Packages}). This @code{build-system}
+field represents the build procedure of the package, as well implicit
+dependencies of that build procedure.
+
+Build systems are @code{<build-system>} objects. The interface to
+create and manipulate them is provided by the @code{(guix build-system)}
+module, and actual build systems are exported by specific modules.
+
+Build systems accept an optional list of @dfn{arguments}. In package
+definitions, these are passed @i{via} the @code{arguments} field
+(@pxref{Defining Packages}). They are typically keyword arguments
+(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
+Guile Reference Manual}). The value of these arguments is usually
+evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
+by the daemon (@pxref{Derivations}).
+
+The main build system is @var{gnu-build-system}, which implements the
+standard build procedure for GNU packages and many other packages. It
+is provided by the @code{(guix build-system gnu)} module.
+
+@defvr {Scheme Variable} gnu-build-system
+@var{gnu-build-system} represents the GNU Build System, and variants
+thereof (@pxref{Configuration, configuration and makefile conventions,,
+standards, GNU Coding Standards}).
+
+@cindex build phases
+In a nutshell, packages using it configured, built, and installed with
+the usual @code{./configure && make && make check && make install}
+command sequence. In practice, a few additional steps are often needed.
+All these steps are split up in separate @dfn{phases},
+notably@footnote{Please see the @code{(guix build gnu-build-system)}
+modules for more details about the build phases.}:
+
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree. If the source is actually a directory, copy it
+to the build tree, and enter that directory.
+
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names. For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
+is false), copying them to the @code{debug} output when available
+(@pxref{Installing Debugging Files}).
+@end table
+
+@vindex %standard-phases
+The build-side module @code{(guix build gnu-build-system)} defines
+@var{%standard-phases} as the default list of build phases.
+@var{%standard-phases} is a list of symbol/procedure pairs, where the
+procedure implements the actual phase.
+
+The list of phases used for a particular package can be changed with the
+@code{#:phases} parameter. For instance, passing:
+
+@example
+#:phases (alist-delete 'configure %standard-phases)
+@end example
+
+means that all the phases described above will be used, except the
+@code{configure} phase.
+
+In addition, this build system ensures that the ``standard'' environment
+for GNU packages is available. This includes tools such as GCC, libc,
+Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
+build-system gnu)} module for a complete list.) We call these the
+@dfn{implicit inputs} of a package, because package definitions don't
+have to mention them.
+@end defvr
+
+Other @code{<build-system>} objects are defined to support other
+conventions and tools used by free software packages. They inherit most
+of @var{gnu-build-system}, and differ mainly in the set of inputs
+implicitly added to the build process, and in the list of phases
+executed. Some of these build systems are listed below.
+
+@defvr {Scheme Variable} cmake-build-system
+This variable is exported by @code{(guix build-system cmake)}. It
+implements the build procedure for packages using the
+@url{http://www.cmake.org, CMake build tool}.
+
+It automatically adds the @code{cmake} package to the set of inputs.
+Which package is used can be specified with the @code{#:cmake}
+parameter.
+@end defvr
+
+@defvr {Scheme Variable} python-build-system
+This variable is exported by @code{(guix build-system python)}. It
+implements the more or less standard build procedure used by Python
+packages, which consists in running @code{python setup.py build} and
+then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
+
+For packages that install stand-alone Python programs under @code{bin/},
+it takes care of wrapping these programs so their @code{PYTHONPATH}
+environment variable points to all the Python libraries they depend on.
+
+Which Python package is used can be specified with the @code{#:python}
+parameter.
+@end defvr
+
+@defvr {Scheme Variable} perl-build-system
+This variable is exported by @code{(guix build-system perl)}. It
+implements the standard build procedure for Perl packages, which
+consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
+followed by @code{make} and @code{make install}.
+
+The initial @code{perl Makefile.PL} invocation passes flags specified by
+the @code{#:make-maker-flags} parameter.
+
+Which Perl package is used can be specified with @code{#:perl}.
+@end defvr
+
+
+Lastly, for packages that do not need anything as sophisticated, a
+``trivial'' build system is provided. It is trivial in the sense that
+it provides basically no support: it does not pull any implicit inputs,
+and does not have a notion of build phases.
+
+@defvr {Scheme Variable} trivial-build-system
+This variable is exported by @code{(guix build-system trivial)}.
+
+This build system requires a @code{#:builder} argument. This argument
+must be a Scheme expression that builds the package's output(s)---as
+with @code{build-expression->derivation} (@pxref{Derivations,
+@code{build-expression->derivation}}).
+@end defvr
+
@node The Store
@section The Store
@cindex store paths
Conceptually, the @dfn{store} is where derivations that have been
-successfully built are stored---by default, under @file{/nix/store}.
+successfully built are stored---by default, under @file{/gnu/store}.
Sub-directories in the store are referred to as @dfn{store paths}. The
store has an associated database that contains information such has the
store paths referred to by each store path, and the list of @emph{valid}
Return @code{#t} when @var{path} is a valid store path.
@end deffn
-@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
+@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
Add @var{text} under file @var{name} in the store, and return its store
path. @var{references} is the list of store paths referred to by the
resulting store path.
@end deffn
@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
-Build @var{derivations} (a list of derivation paths), and return when
-the worker is done building them. Return @code{#t} on success.
+Build @var{derivations} (a list of @code{<derivation>} objects or
+derivation paths), and return when the worker is done building them.
+Return @code{#t} on success.
@end deffn
+Note that the @code{(guix monads)} module provides a monad as well as
+monadic versions of the above procedures, with the goal of making it
+more convenient to work with code that accesses the store (@pxref{The
+Store Monad}).
+
@c FIXME
@i{This section is currently incomplete.}
otherwise manipulate derivations. The lowest-level primitive to create
a derivation is the @code{derivation} procedure:
-@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f]
-Build a derivation with the given arguments. Return the resulting store
-path and @code{<derivation>} object.
+@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
+ @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
+ [#:system (%current-system)] [#:references-graphs #f] @
+ [#:allowed-references #f] [#:local-build? #f]
+Build a derivation with the given arguments, and return the resulting
+@code{<derivation>} object.
-When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
+When @var{hash} and @var{hash-algo} are given, a
@dfn{fixed-output derivation} is created---i.e., one whose result is
-known in advance, such as a file download.
+known in advance, such as a file download. If, in addition,
+@var{recursive?} is true, then that fixed output may be an executable
+file or a directory and @var{hash} must be the hash of an archive
+containing this output.
When @var{references-graphs} is true, it must be a list of file
name/store path pairs. In that case, the reference graph of each store
path is exported in the build environment in the corresponding file, in
a simple text format.
+
+When @var{allowed-references} is true, it must be a list of store items
+or outputs that the derivation's output may refer to.
+
+When @var{local-build?} is true, declare that the derivation is not a
+good candidate for offloading and should rather be built locally
+(@pxref{Daemon Offload Setup}). This is the case for small derivations
+where the costs of data transfers would outweigh the benefits.
@end deffn
@noindent
(guix store)
(guix derivations))
-(call-with-values
- (lambda ()
- (let ((builder ; add the Bash script to the store
- (add-text-to-store store "my-builder.sh"
- "echo hello world > $out\n" '())))
- (derivation store "foo"
- bash `("-e" ,builder)
- #:env-vars '(("HOME" . "/homeless")))))
- list)
-@result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
+(let ((builder ; add the Bash script to the store
+ (add-text-to-store store "my-builder.sh"
+ "echo hello world > $out\n" '())))
+ (derivation store "foo"
+ bash `("-e" ,builder)
+ #:inputs `((,bash) (,builder))
+ #:env-vars '(("HOME" . "/homeless"))))
+@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
@end lisp
-As can be guessed, this primitive is cumbersome to use directly. An
-improved variant is @code{build-expression->derivation}, which allows
-the caller to directly pass a Guile expression as the build script:
-
-@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:references-graphs #f] [#:guile-for-build #f]
+As can be guessed, this primitive is cumbersome to use directly. A
+better approach is to write build scripts in Scheme, of course! The
+best course of action for that is to write the build code as a
+``G-expression'', and to pass it to @code{gexp->derivation}. For more
+information, @ref{G-Expressions}.
+
+Once upon a time, @code{gexp->derivation} did not exist and constructing
+derivations with build code written in Scheme was achieved with
+@code{build-expression->derivation}, documented below. This procedure
+is now deprecated in favor of the much nicer @code{gexp->derivation}.
+
+@deffn {Scheme Procedure} build-expression->derivation @var{store} @
+ @var{name} @var{exp} @
+ [#:system (%current-system)] [#:inputs '()] @
+ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
Return a derivation that executes Scheme expression @var{exp} as a
builder for derivation @var{name}. @var{inputs} must be a list of
@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
@var{guile-for-build} is omitted or is @code{#f}, the value of the
@code{%guile-for-build} fluid is used instead.
-See the @code{derivation} procedure for the meaning of @var{references-graphs}.
+See the @code{derivation} procedure for the meaning of @var{references-graphs}
+and @var{local-build?}.
@end deffn
@noindent
@lisp
(let ((builder '(let ((out (assoc-ref %outputs "out")))
- (mkdir out) ; create /nix/store/@dots{}-goo
+ (mkdir out) ; create /gnu/store/@dots{}-goo
(call-with-output-file (string-append out "/test")
(lambda (p)
(display '(hello guix) p))))))
- (build-expression->derivation store "goo" (%current-system)
- builder '()))
+ (build-expression->derivation store "goo" builder))
-@result{} "/nix/store/@dots{}-goo.drv"
-@result{} #<<derivation> @dots{}>
+@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
@end lisp
+
+@node The Store Monad
+@section The Store Monad
+
+@cindex monad
+
+The procedures that operate on the store described in the previous
+sections all take an open connection to the build daemon as their first
+argument. Although the underlying model is functional, they either have
+side effects or depend on the current state of the store.
+
+The former is inconvenient: the connection to the build daemon has to be
+carried around in all those functions, making it impossible to compose
+functions that do not take that parameter with functions that do. The
+latter can be problematic: since store operations have side effects
+and/or depend on external state, they have to be properly sequenced.
+
+@cindex monadic values
+@cindex monadic functions
+This is where the @code{(guix monads)} module comes in. This module
+provides a framework for working with @dfn{monads}, and a particularly
+useful monad for our uses, the @dfn{store monad}. Monads are a
+construct that allows two things: associating ``context'' with values
+(in our case, the context is the store), and building sequences of
+computations (here computations includes accesses to the store.) Values
+in a monad---values that carry this additional context---are called
+@dfn{monadic values}; procedures that return such values are called
+@dfn{monadic procedures}.
+
+Consider this ``normal'' procedure:
+
+@example
+(define (sh-symlink store)
+ ;; Return a derivation that symlinks the 'bash' executable.
+ (let* ((drv (package-derivation store bash))
+ (out (derivation->output-path drv))
+ (sh (string-append out "/bin/bash")))
+ (build-expression->derivation store "sh"
+ `(symlink ,sh %output))))
+@end example
+
+Using @code{(guix monads)}, it may be rewritten as a monadic function:
+
+@c FIXME: Find a better example, one that uses 'mlet'.
+@example
+(define (sh-symlink)
+ ;; Same, but return a monadic value.
+ (gexp->derivation "sh"
+ #~(symlink (string-append #$bash "/bin/bash") #$output)))
+@end example
+
+There are two things to note in the second version: the @code{store}
+parameter is now implicit, and the monadic value returned by
+@code{package-file}---a wrapper around @code{package-derivation} and
+@code{derivation->output-path}---is @dfn{bound} using @code{mlet}
+instead of plain @code{let}.
+
+Calling the monadic @code{profile.sh} has no effect. To get the desired
+effect, one must use @code{run-with-store}:
+
+@example
+(run-with-store (open-connection) (profile.sh))
+@result{} /gnu/store/...-profile.sh
+@end example
+
+The main syntactic forms to deal with monads in general are described
+below.
+
+@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
+Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
+in @var{monad}.
+@end deffn
+
+@deffn {Scheme Syntax} return @var{val}
+Return a monadic value that encapsulates @var{val}.
+@end deffn
+
+@deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
+@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
+procedure @var{mproc}@footnote{This operation is commonly referred to as
+``bind'', but that name denotes an unrelated procedure in Guile. Thus
+we use this somewhat cryptic symbol inherited from the Haskell
+language.}.
+@end deffn
+
+@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
+@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
+Bind the variables @var{var} to the monadic values @var{mval} in
+@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
+``normal'' value @var{val}, as per @code{let}.
+
+@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
+(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
+@end deffn
+
+The interface to the store monad provided by @code{(guix monads)} is as
+follows.
+
+@defvr {Scheme Variable} %store-monad
+The store monad. Values in the store monad encapsulate accesses to the
+store. When its effect is needed, a value of the store monad must be
+``evaluated'' by passing it to the @code{run-with-store} procedure (see
+below.)
+@end defvr
+
+@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
+Run @var{mval}, a monadic value in the store monad, in @var{store}, an
+open store connection.
+@end deffn
+
+@deffn {Monadic Procedure} text-file @var{name} @var{text}
+Return as a monadic value the absolute file name in the store of the file
+containing @var{text}, a string.
+@end deffn
+
+@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
+Return as a monadic value a derivation that builds a text file
+containing all of @var{text}. @var{text} may list, in addition to
+strings, packages, derivations, and store file names; the resulting
+store file holds references to all these.
+
+This variant should be preferred over @code{text-file} anytime the file
+to create will reference items from the store. This is typically the
+case when building a configuration file that embeds store file names,
+like this:
+
+@example
+(define (profile.sh)
+ ;; Return the name of a shell script in the store that
+ ;; initializes the 'PATH' environment variable.
+ (text-file* "profile.sh"
+ "export PATH=" coreutils "/bin:"
+ grep "/bin:" sed "/bin\n"))
+@end example
+
+In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
+will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
+@end deffn
+
+@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
+ [#:system (%current-system)] [#:output "out"] Return as a monadic
+value in the absolute file name of @var{file} within the @var{output}
+directory of @var{package}. When @var{file} is omitted, return the name
+of the @var{output} directory of @var{package}.
+@end deffn
+
+@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
+Monadic version of @code{package-derivation} (@pxref{Defining
+Packages}).
+@end deffn
+
+
+@node G-Expressions
+@section G-Expressions
+
+@cindex G-expression
+@cindex build code quoting
+So we have ``derivations'', which represent a sequence of build actions
+to be performed to produce an item in the store (@pxref{Derivations}).
+Those build actions are performed when asking the daemon to actually
+build the derivations; they are run by the daemon in a container
+(@pxref{Invoking guix-daemon}).
+
@cindex strata of code
-Remember that the build expression passed to
-@code{build-expression->derivation} is run by a separate Guile process
-than the one that calls @code{build-expression->derivation}: it is run
-by a Guile process launched by the daemon, typically in a chroot. So,
-while there is a single language for both the @dfn{host} and the build
-side, there are really two @dfn{strata} of code: the host-side, and the
-build-side code@footnote{The term @dfn{stratum} in this context was
-coined by Manuel Serrano et al. in the context of their work on Hop.}.
-This distinction is important to keep in mind, notably when using
-higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
-Packages}). For this reason, Guix modules that are meant to be used in
-the build stratum are kept in the @code{(guix build @dots{})} name
-space.
+It should come as no surprise that we like to write those build actions
+in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
+code@footnote{The term @dfn{stratum} in this context was coined by
+Manuel Serrano et al.@: in the context of their work on Hop. Oleg
+Kiselyov, who has written insightful
+@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
+on this topic}, refers to this kind of code generation as
+@dfn{staging}.}: the ``host code''---code that defines packages, talks
+to the daemon, etc.---and the ``build code''---code that actually
+performs build actions, such as making directories, invoking
+@command{make}, etc.
+
+To describe a derivation and its build actions, one typically needs to
+embed build code inside host code. It boils down to manipulating build
+code as data, and Scheme's homoiconicity---code has a direct
+representation as data---comes in handy for that. But we need more than
+Scheme's normal @code{quasiquote} mechanism to construct build
+expressions.
+
+The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
+S-expressions adapted to build expressions. G-expressions, or
+@dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
+@code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
+@code{#$}, and @code{#$@@}), which are comparable respectively to
+@code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
+(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
+Reference Manual}). However, there are major differences:
+
+@itemize
+@item
+Gexps are meant to be written to a file and run or manipulated by other
+processes.
+
+@item
+When a package or derivation is unquoted inside a gexp, the result is as
+if its output file name had been introduced.
+
+@item
+Gexps carry information about the packages or derivations they refer to,
+and these dependencies are automatically added as inputs to the build
+processes that use them.
+@end itemize
+
+To illustrate the idea, here is an example of a gexp:
+
+@example
+(define build-exp
+ #~(begin
+ (mkdir #$output)
+ (chdir #$output)
+ (symlink (string-append #$coreutils "/bin/ls")
+ "list-files")))
+@end example
+
+This gexp can be passed to @code{gexp->derivation}; we obtain a
+derivation that builds a directory containing exactly one symlink to
+@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
+
+@example
+(gexp->derivation "the-thing" build-exp)
+@end example
+
+As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
+substituted to the reference to the @var{coreutils} package in the
+actual build code, and @var{coreutils} is automatically made an input to
+the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
+output)}) is replaced by a string containing the derivation's output
+directory name. The syntactic form to construct gexps is summarized
+below.
+
+@deffn {Scheme Syntax} #~@var{exp}
+@deffnx {Scheme Syntax} (gexp @var{exp})
+Return a G-expression containing @var{exp}. @var{exp} may contain one
+or more of the following forms:
+
+@table @code
+@item #$@var{obj}
+@itemx (ungexp @var{obj})
+Introduce a reference to @var{obj}. @var{obj} may be a package or a
+derivation, in which case the @code{ungexp} form is replaced by its
+output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
+
+If @var{obj} is a list, it is traversed and any package or derivation
+references are substituted similarly.
+
+If @var{obj} is another gexp, its contents are inserted and its
+dependencies are added to those of the containing gexp.
+
+If @var{obj} is another kind of object, it is inserted as is.
+
+@item #$@var{package-or-derivation}:@var{output}
+@itemx (ungexp @var{package-or-derivation} @var{output})
+This is like the form above, but referring explicitly to the
+@var{output} of @var{package-or-derivation}---this is useful when
+@var{package-or-derivation} produces multiple outputs (@pxref{Packages
+with Multiple Outputs}).
+
+@item #$output[:@var{output}]
+@itemx (ungexp output [@var{output}])
+Insert a reference to derivation output @var{output}, or to the main
+output when @var{output} is omitted.
+
+This only makes sense for gexps passed to @code{gexp->derivation}.
+
+@item #$@@@var{lst}
+@itemx (ungexp-splicing @var{lst})
+Like the above, but splices the contents of @var{lst} inside the
+containing list.
+
+@end table
+
+G-expressions created by @code{gexp} or @code{#~} are run-time objects
+of the @code{gexp?} type (see below.)
+@end deffn
+
+@deffn {Scheme Procedure} gexp? @var{obj}
+Return @code{#t} if @var{obj} is a G-expression.
+@end deffn
+
+G-expressions are meant to be written to disk, either as code building
+some derivation, or as plain files in the store. The monadic procedures
+below allow you to do that (@pxref{The Store Monad}, for more
+information about monads.)
+
+@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
+ [#:system (%current-system)] [#:inputs '()] @
+ [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:references-graphs #f] [#:local-build? #f] @
+ [#:guile-for-build #f]
+Return a derivation @var{name} that runs @var{exp} (a gexp) with
+@var{guile-for-build} (a derivation) on @var{system}.
+
+Make @var{modules} available in the evaluation context of @var{EXP};
+@var{MODULES} is a list of names of Guile modules from the current
+search path to be copied in the store, compiled, and made available in
+the load path during the execution of @var{exp}---e.g., @code{((guix
+build utils) (guix build gnu-build-system))}.
+
+The other arguments are as for @code{derivation} (@pxref{Derivations}).
+@end deffn
+
+@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
+Return an executable script @var{name} that runs @var{exp} using
+@var{guile} with @var{modules} in its search path.
+
+The example below builds a script that simply invokes the @command{ls}
+command:
+
+@example
+(use-modules (guix gexp) (gnu packages base))
+
+(gexp->script "list-files"
+ #~(execl (string-append #$coreutils "/bin/ls")
+ "ls"))
+@end example
+
+When ``running'' it through the store (@pxref{The Store Monad,
+@code{run-with-store}}), we obtain a derivation that produces an
+executable file @file{/gnu/store/@dots{}-list-files} along these lines:
+
+@example
+#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
+!#
+(execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
+ "ls")
+@end example
+@end deffn
+
+@deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
+Return a derivation that builds a file @var{name} containing @var{exp}.
+
+The resulting file holds references to all the dependencies of @var{exp}
+or a subset thereof.
+@end deffn
+
+Of course, in addition to gexps embedded in ``host'' code, there are
+also modules containing build tools. To make it clear that they are
+meant to be used in the build stratum, these modules are kept in the
+@code{(guix build @dots{})} name space.
+
@c *********************************************************************
@node Utilities
@var{package-or-derivation} may be either the name of a package found in
the software distribution such as @code{coreutils} or
@code{coreutils-8.20}, or a derivation such as
-@file{/nix/store/@dots{}-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.
+@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
+package with the corresponding name (and optionally version) is searched
+for among the GNU distribution modules (@pxref{Package Modules}).
+
+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:
@item --expression=@var{expr}
@itemx -e @var{expr}
-Build the package @var{expr} evaluates to.
+Build the package or derivation @var{expr} evaluates to.
For example, @var{expr} may be @code{(@@ (gnu packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.
+Alternately, @var{expr} may refer to a zero-argument monadic procedure
+(@pxref{The Store Monad}). The procedure must return a derivation as a
+monadic value, which is then passed through @code{run-with-store}.
+
@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/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
+@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
+
+The returned source tarball is the result of applying any patches and
+code snippets specified in the package's @code{origin} (@pxref{Defining
+Packages}).
@item --system=@var{system}
@itemx -s @var{system}
as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
configuration triplets,, configure, GNU Configure and Build System}).
+@item --with-source=@var{source}
+Use @var{source} as the source of the corresponding package.
+@var{source} must be a file name or a URL, as for @command{guix
+download} (@pxref{Invoking guix download}).
+
+The ``corresponding package'' is taken to be one specified on the
+command line whose name matches the base of @var{source}---e.g., if
+@var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
+package is @code{guile}. Likewise, the version string is inferred from
+@var{source}; in the previous example, it's @code{2.0.10}.
+
+This option allows users to try out versions of packages other than the
+one provided by the distribution. The example below downloads
+@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
+the @code{ed} package:
+
+@example
+guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
+@end example
+
+As a developer, @code{--with-source} makes it easy to test release
+candidates:
+
+@example
+guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
+@end example
+
+
@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.
+@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 --log-file
+Return the build log file names for the given
+@var{package-or-derivation}s, or raise an error if build logs are
+missing.
+
+This works regardless of how packages or derivations are specified. For
+instance, the following invocations are equivalent:
+
+@example
+guix build --log-file `guix build -d guile`
+guix build --log-file `guix build guile`
+guix build --log-file guile
+guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
+@end example
+
+
+@end table
+
+@cindex common build options
+In addition, a number of options that control the build process are
+common to @command{guix build} and other commands that can spawn builds,
+such as @command{guix package} or @command{guix archive}. These are the
+following:
+
+@table @code
+
@item --keep-failed
@itemx -K
Keep the build tree of failed builds. Thus, if a build fail, its build
packages locally.
@item --no-substitutes
-Build instead of resorting to pre-built substitutes.
+Do not use substitutes for build products. That is, always build things
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
+
+@item --no-build-hook
+Do not attempt to offload builds @i{via} the daemon's ``build hook''
+(@pxref{Daemon Offload Setup}). That is, always build things locally
+instead of offloading builds to remote machines.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure.
-@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 --timeout=@var{seconds}
+Likewise, when the build or substitution process lasts for more than
+@var{seconds}, terminate it and report a build failure.
-@item --root=@var{file}
-@itemx -r @var{file}
-Make @var{file} a symlink to the result, and register it as a garbage
-collector root.
+By default there is no timeout. This behavior can be restored with
+@code{--timeout=0}.
@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.
+@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.
+
@end table
Behind the scenes, @command{guix build} is essentially an interface to
will output the hash in @code{nix-base32}. This representation is used
in the definitions of packages.
+@item --recursive
+@itemx -r
+Compute the hash on @var{file} recursively.
+
+In this case, the hash is computed on an archive containing @var{file},
+including its children if it is a directory. Some of @var{file}'s
+meta-data is part of the archive; for instance, when @var{file} is a
+regular file, the hash is different depending on whether @var{file} is
+executable or not. Meta-data such as time stamps has no impact on the
+hash (@pxref{Invoking guix archive}).
+@c FIXME: Replace xref above with xref to an ``Archive'' section when
+@c it exists.
+
@end table
@node Invoking guix refresh
Guix comes with a distribution of free software@footnote{The term
``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.} that form the basis of the GNU system. This
+users of that software}.} that forms the basis of the GNU system. This
includes core GNU packages such as GNU libc, GCC, and Binutils, as well
as many GNU and non-GNU applications. The complete list of available
-packages can be seen by running @command{guix package} (@pxref{Invoking
-guix package}):
+packages can be browsed
+@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
+running @command{guix package} (@pxref{Invoking guix package}):
@example
guix package --list-available
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
+The GNU distribution is currently available on the following platforms:
+
+@table @code
+
+@item x86_64-linux
+Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+
+@item i686-linux
+Intel 32-bit architecture (IA32), Linux-Libre kernel;
+
+@item mips64el-linux
+little-endian 64-bit MIPS processors, specifically the Loongson series,
+n32 application binary interface (ABI), and Linux-Libre kernel.
+
+@end table
+
+@noindent
+For information on porting to other architectures or kernels,
+@xref{Porting}.
+
@menu
* Installing Debugging Files:: Feeding the debugger.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
+* System Configuration:: Configuring a GNU system.
@end menu
Building this distribution is a cooperative effort, and you are invited
@node Installing Debugging Files
@section Installing Debugging Files
+@cindex debugging files
Program binaries, as produced by the GCC compilers for instance, are
typically written in the ELF format, with a section containing
@dfn{debugging information}. Debugging information is what allows the
Guile:
@example
-guix package -i glibc:debug -i guile:debug
+guix package -i glibc:debug guile:debug
@end example
GDB must then be told to look for debug files in the user's profile, by
From there on, GDB will pick up debugging information from the
@code{.debug} files under @file{~/.guix-profile/lib/debug}.
+In addition, you will most likely want GDB to be able to show the source
+code being debugged. To do that, you will have to unpack the source
+code of the package of interest (obtained with @code{guix build
+--source}, @pxref{Invoking guix build}), and to point GDB to that source
+directory using the @code{directory} command (@pxref{Source Path,
+@code{directory},, gdb, Debugging with GDB}).
+
@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
-@code{gnu-build-system} (@pxref{Defining Packages}). Currently, it is
+@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
opt-in---debugging information is available only for those packages
whose definition explicitly declares a @code{debug} output. This may be
changed to opt-out in the future, if our build farm servers can handle
@section Package Modules
From a programming viewpoint, the package definitions of the
-distribution are provided by Guile modules in the @code{(gnu packages
-...)} name space (@pxref{Modules, Guile modules,, guile, GNU Guile
+GNU distribution are provided by Guile modules in the @code{(gnu packages
+@dots{})} name space@footnote{Note that packages under the @code{(gnu
+packages @dots{})} module name space are not necessarily ``GNU
+packages''. This module naming scheme follows the usual Guile module
+naming convention: @code{gnu} means that these modules are distributed
+as part of the GNU system, and @code{packages} identifies modules that
+define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
Reference Manual}). For instance, the @code{(gnu packages emacs)}
module exports a variable named @code{emacs}, which is bound to a
-@code{<package>} object (@pxref{Defining Packages}). The @code{(gnu
-packages)} module provides facilities for searching for packages.
+@code{<package>} object (@pxref{Defining Packages}).
+
+The @code{(gnu packages @dots{})} module name space is special: it is
+automatically scanned for packages by the command-line tools. For
+instance, when running @code{guix package -i emacs}, all the @code{(gnu
+packages @dots{})} modules are scanned until one that exports a package
+object whose name is @code{emacs} is found. This package search
+facility is implemented in the @code{(gnu packages)} module.
+
+Users can store package definitions in modules with different
+names---e.g., @code{(my-packages emacs)}. In that case, commands such
+as @command{guix package} and @command{guix build} have to be used with
+the @code{-e} option so that they know where to find the package.
The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
each package is built based solely on other packages in the
The GNU distribution is nascent and may well lack some of your favorite
packages. This section describes how you can help make the distribution
-grow. @ref{Contributing}, for additional information on how you can
+grow. @xref{Contributing}, for additional information on how you can
help.
Free software packages are usually distributed in the form of
@end example
Using @code{--keep-failed} makes it easier to debug build failures since
-it provides access to the failed build tree.
+it provides access to the failed build tree. Another useful
+command-line option when debugging is @code{--log-file}, to access the
+build log.
+
+If the package is unknown to the @command{guix} command, it may be that
+the source file contains a syntax error, or lacks a @code{define-public}
+clause to export the package variable. To figure it out, you may load
+the module from Guile to get more information about the actual error:
+
+@example
+./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
+@end example
Once your package builds correctly, please send us a patch
(@pxref{Contributing}). Well, if you need help, we will be happy to
Users can obtain the new package definition simply by running
@command{guix pull} (@pxref{Invoking guix pull}). When
@code{hydra.gnu.org} is done building the package, installing the
-package automatically downloads binaries from there (except when using
-@code{--no-substitutes}). The only place where human intervention is
+package automatically downloads binaries from there
+(@pxref{Substitutes}). The only place where human intervention is
needed is to review and apply the patch.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Python Modules:: Taming the snake.
+* Perl Modules:: Little pearls.
@end menu
@node Software Freedom
reject non-free firmware, recommendations of non-free software, and
discuss ways to deal with trademarks and patents.
+Some packages contain a small and optional subset that violates the
+above guidelines, for instance because this subset is itself non-free
+code. When that happens, the offending items are removed with
+appropriate patches or code snippets in the package definition's
+@code{origin} form (@pxref{Defining Packages}). That way, @code{guix
+build --source} returns the ``freed'' source rather than the unmodified
+upstream source.
+
@node Package Naming
@subsection Package Naming
-A package has actually two names associated to it:
+A package has actually two names associated with it:
First, there is the name of the @emph{Scheme variable}, the one following
-@code{define-public}. By this name, the package can be made known in the
-Scheme code, for instance as input to another package.
-Second, there is the string in the @code{name} field of a package definition.
-This name is used by the package manager.
+@code{define-public}. By this name, the package can be made known in the
+Scheme code, for instance as input to another package. Second, there is
+the string in the @code{name} field of a package definition. This name
+is used by package management commands such as
+@command{guix package} and @command{guix build}.
+
+Both are usually the same and correspond to the lowercase conversion of
+the project name chosen upstream, with underscores replaced with
+hyphens. For instance, GNUnet is available as @code{gnunet}, and
+SDL_net as @code{sdl-net}.
-Both are usually the same and correspond to the lowercase conversion of the
-project name chosen by upstream. For instance, the GNUnet project is packaged
-as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
-unless these are already part of the official project name.
-But see @ref{Python Modules} for special rules concerning modules for
-the Python language.
+We do not add @code{lib} prefixes for library packages, unless these are
+already part of the official project name. But see @pxref{Python
+Modules} and @ref{Perl Modules} for special rules concerning modules for
+the Python and Perl languages.
@node Version Numbers
@subsection Version Numbers
We usually package only the latest version of a given free software
-project. But sometimes, for instance for incompatible library versions,
-two (or more) versions of the same package are needed. These require different
-Scheme variable names. We use the name as defined in @ref{Package Naming}
+project. But sometimes, for instance for incompatible library versions,
+two (or more) versions of the same package are needed. These require
+different Scheme variable names. We use the name as defined
+in @ref{Package Naming}
for the most recent version; previous versions use the same name, suffixed
by @code{-} and the smallest prefix of the version number that may
distinguish the two versions.
package and does not contain any version number.
For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
+
@example
(define-public gtk+
(package
To avoid confusion and naming clashes with other programming languages, it
seems desirable that the name of a package for a Python module contains
the word @code{python}.
+
Some modules are compatible with only one version of Python, others with both.
If the package Foo compiles only with Python 3, we name it
@code{python-foo}; if it compiles only with Python 2, we name it
@code{python-dateutil} and @code{python2-dateutil}.
+@node Perl Modules
+@subsection Perl Modules
+
+Perl programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+For Perl packages containing a single class, we use the lowercase class name,
+replace all occurrences of @code{::} by dashes and prepend the prefix
+@code{perl-}.
+So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
+Modules containing several classes keep their lowercase upstream name and
+are also prepended by @code{perl-}. Such modules tend to have the word
+@code{perl} somewhere in their name, which gets dropped in favor of the
+prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
@dfn{bootstrap binaries}.
These bootstrap binaries are ``taken for granted'', though we can also
-re-create them if needed (more on that later.)
+re-create them if needed (more on that later).
@unnumberedsubsec Preparing to Use the Bootstrap Binaries
Bootstrapping is complete when we have a full tool chain that does not
depend on the pre-built bootstrap tools discussed above. This
no-dependency requirement is verified by checking whether the files of
-the final tool chain contain references to the @file{/nix/store}
+the final tool chain contain references to the @file{/gnu/store}
directories of the bootstrap inputs. The process that leads to this
``final'' tool chain is described by the package definitions found in
the @code{(gnu packages base)} module.
guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
@end example
+Once these are built, the @code{(gnu packages bootstrap)} module needs
+to be updated to refer to these binaries on the target platform. In
+addition, the @code{glibc-dynamic-linker} procedure in that module must
+be augmented to return the right file name for libc's dynamic linker on
+that platform; likewise, @code{system->linux-architecture} in @code{(gnu
+packages linux)} must be taught about the new platform.
+
In practice, there may be some complications. First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
above) is not recognized by all the GNU tools. Typically, glibc
recognizes some of these, whereas GCC uses an extra @code{--with-abi}
-configure flag (see @code{gcc.scm} for examples of how to handle this.)
+configure flag (see @code{gcc.scm} for examples of how to handle this).
Second, some of the required packages could fail to build for that
platform. Lastly, the generated binaries could be broken for some
reason.
+@node System Configuration
+@section System Configuration
+
+@emph{This section documents work-in-progress. As such it may be
+incomplete, outdated, or open to discussions. Please discuss it on
+@email{guix-devel@@gnu.org}.}
+
+@cindex system configuration
+The GNU system supports a consistent whole-system configuration
+mechanism. By that we mean that all aspects of the global system
+configuration---such as the available system services, timezone and
+locale settings, user accounts---are declared in a single place. Such
+a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
+
+One of the advantages of putting all the system configuration under the
+control of Guix is that it supports transactional system upgrades, and
+makes it possible to roll-back to a previous system instantiation,
+should something go wrong with the new one (@pxref{Features}). Another
+one is that it makes it easy to replicate the exact same configuration
+across different machines, or at different points in time, without
+having to resort to additional administration tools layered on top of
+the system's own tools.
+@c Yes, we're talking of Puppet, Chef, & co. here. ↑
+
+This section describes this mechanism. First we focus on the system
+administrator's viewpoint---explaining how the system is configured and
+instantiated. Then we show how this mechanism can be extended, for
+instance to support new system services.
+
+@menu
+* Using the Configuration System:: Customizing your GNU system.
+* Invoking guix system:: Instantiating a system configuration.
+* Defining Services:: Adding new service definitions.
+@end menu
+
+@node Using the Configuration System
+@subsection Using the Configuration System
+
+The operating system is configured by filling in an
+@code{operating-system} structure, as defined by the @code{(gnu system)}
+module. A simple setup, with the default system services, the default
+Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
+
+@findex operating-system
+@lisp
+(use-modules (gnu) ; for 'user-account', '%base-services', etc.
+ (gnu packages emacs) ; for 'emacs'
+ (gnu services ssh)) ; for 'lsh-service'
+
+(define komputilo
+ (operating-system
+ (host-name "komputilo")
+ (timezone "Europe/Paris")
+ (locale "fr_FR.UTF-8")
+ (bootloader (grub-configuration
+ (device "/dev/sda")))
+ (file-systems (list (file-system
+ (device "/dev/sda1") ; or partition label
+ (mount-point "/")
+ (type "ext3"))))
+ (users (list (user-account
+ (name "alice")
+ (password "")
+ (uid 1000) (gid 100)
+ (comment "Bob's sister")
+ (home-directory "/home/alice"))))
+ (packages (cons emacs %base-packages))
+ (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
+ %base-services))))
+@end lisp
+
+This example should be self-describing. The @code{packages} field lists
+packages that will be globally visible on the system, for all user
+accounts---i.e., in every user's @code{PATH} environment variable---in
+addition to the per-user profiles (@pxref{Invoking guix package}). The
+@var{%base-packages} variables provides all the tools one would expect
+for basic user and administrator tasks---including the GNU Core
+Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
+editor, @command{find}, @command{grep}, etc. The example above adds
+Emacs to those, taken from the @code{(gnu packages emacs)} module
+(@pxref{Package Modules}).
+
+@vindex %base-services
+The @code{services} field lists @dfn{system services} to be made
+available when the system starts. The @var{%base-services} list,
+from the @code{(gnu services base)} module, provides the basic services one
+would expect from a GNU system: a login service (mingetty) on each tty,
+syslogd, libc's name service cache daemon (nscd), etc.
+
+The @code{operating-system} declaration above specifies that, in
+addition to those services, we want the @command{lshd} secure shell
+daemon listening on port 2222, and allowing remote @code{root} logins
+(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
+@code{lsh-service} arranges so that @code{lshd} is started with the
+right command-line options, possibly with supporting configuration files
+generated as needed (@pxref{Defining Services}).
+
+Assuming the above snippet is stored in the @file{my-system-config.scm}
+file, the @command{guix system boot my-system-config.scm} command
+instantiates that configuration, and makes it the default GRUB boot
+entry (@pxref{Invoking guix system}). The normal way to change the
+system's configuration is by updating this file and re-running the
+@command{guix system} command.
+
+At the Scheme level, the bulk of an @code{operating-system} declaration
+is instantiated with the following monadic procedure (@pxref{The Store
+Monad}):
+
+@deffn {Monadic Procedure} operating-system-derivation os
+Return a derivation that builds @var{os}, an @code{operating-system}
+object (@pxref{Derivations}).
+
+The output of the derivation is a single directory that refers to all
+the packages, configuration files, and other supporting files needed to
+instantiate @var{os}.
+@end deffn
+
+@node Invoking guix system
+@subsection Invoking @code{guix system}
+
+Once you have written an operating system declaration, as seen in the
+previous section, it can be @dfn{instantiated} using the @command{guix
+system} command. The synopsis is:
+
+@example
+guix system @var{options}@dots{} @var{action} @var{file}
+@end example
+
+@var{file} must be the name of a file containing an
+@code{operating-system} declaration. @var{action} specifies how the
+operating system is instantiate. Currently the following values are
+supported:
+
+@table @code
+@item build
+Build the operating system's derivation, which includes all the
+configuration files and programs needed to boot and run the system.
+This action does not actually install anything.
+
+@item init
+Populate the given directory with all the files necessary to run the
+operating system specified in @var{file}. This is useful for first-time
+installations of the GNU system. For instance:
+
+@example
+guix system init my-os-config.scm /mnt
+@end example
+
+copies to @file{/mnt} all the store items required by the configuration
+specified in @file{my-os-config.scm}. This includes configuration
+files, packages, and so on. It also creates other essential files
+needed for the system to operate correctly---e.g., the @file{/etc},
+@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
+
+This command also installs GRUB on the device specified in
+@file{my-os-config}, unless the @option{--no-grub} option was passed.
+
+@item vm
+@cindex virtual machine
+Build a virtual machine that contain the operating system declared in
+@var{file}, and return a script to run that virtual machine (VM).
+
+The VM shares its store with the host system.
+
+@item vm-image
+@itemx disk-image
+Return a virtual machine or disk image of the operating system declared
+in @var{file} that stands alone. Use the @option{--image-size} option
+to specify the size of the image.
+
+When using @code{vm-image}, the returned image is in qcow2 format, which
+the QEMU emulator can efficiently use.
+
+When using @code{disk-image}, a raw disk image is produced; it can be
+copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
+the device corresponding to a USB stick, one can copy the image on it
+using the following command:
+
+@example
+# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
+@end example
+
+@end table
+
+@var{options} can contain any of the common build options provided by
+@command{guix build} (@pxref{Invoking guix build}).
+
+
+@node Defining Services
+@subsection Defining Services
+
+The @code{(gnu services @dots{})} modules define several procedures that allow
+users to declare the operating system's services (@pxref{Using the
+Configuration System}). These procedures are @emph{monadic
+procedures}---i.e., procedures that return a monadic value in the store
+monad (@pxref{The Store Monad}). Examples of such procedures include:
+
+@table @code
+@item mingetty-service
+return the definition of a service that runs @command{mingetty} to
+offer a login service on the given console tty;
+
+@item nscd-service
+return a definition for libc's name service cache daemon (nscd);
+
+@item guix-service
+return a definition for a service that runs @command{guix-daemon}
+(@pxref{Invoking guix-daemon}).
+@end table
+
+@cindex service definition
+The monadic value returned by those procedures is a @dfn{service
+definition}---a structure as returned by the @code{service} form.
+Service definitions specifies the inputs the service depends on, and an
+expression to start and stop the service. Behind the scenes, service
+definitions are ``translated'' into the form suitable for the
+configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
+dmd Manual}).
+
+As an example, here is what the @code{nscd-service} procedure looks
+like:
+
+@lisp
+(define (nscd-service)
+ (with-monad %store-monad
+ (return (service
+ (documentation "Run libc's name service cache daemon.")
+ (provision '(nscd))
+ (activate #~(begin
+ (use-modules (guix build utils))
+ (mkdir-p "/var/run/nscd")))
+ (start #~(make-forkexec-constructor
+ (string-append #$glibc "/sbin/nscd")
+ "-f" "/dev/null" "--foreground"))
+ (stop #~(make-kill-destructor))
+ (respawn? #f)))))
+@end lisp
+
+@noindent
+The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
+(@pxref{G-Expressions}). The @code{activate} field contains a script to
+run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
+directory exists before @command{nscd} is started.
+
+The @code{start} and @code{stop} fields refer to dmd's facilities to
+start and stop processes (@pxref{Service De- and Constructors,,, dmd,
+GNU dmd Manual}). The @code{provision} field specifies the name under
+which this service is known to dmd, and @code{documentation} specifies
+on-line documentation. Thus, the commands @command{deco start ncsd},
+@command{deco stop nscd}, and @command{deco doc nscd} will do what you
+would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
+
+
@c *********************************************************************
@node Contributing
@chapter Contributing
This project is a cooperative effort, and we need your help to make it
-grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We
-welcome ideas, bug reports, patches, and anything that may be helpful to
-the project. We particularly welcome help on packaging
-(@pxref{Packaging Guidelines}).
+grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
+@code{#guix} on the Freenode IRC network. We welcome ideas, bug
+reports, patches, and anything that may be helpful to the project. We
+particularly welcome help on packaging (@pxref{Packaging Guidelines}).
Please see the
@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
HCoop / jackhill / guix / guix.git / blobdiff