Mirror of GNU Guix
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

24421 lines
885 KiB

\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@settitle GNU Guix Reference Manual
@c %**end of header
@include version.texi
@c Identifier of the OpenPGP key used to sign tarballs and such.
@set KEY-SERVER pool.sks-keyservers.net
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nils Gillmann@*
Copyright @copyright{} 2016, 2017, 2018 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017, 2018 Clément Lassieur@*
Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
Copyright @copyright{} 2017, 2018 Marius Bakke@*
Copyright @copyright{} 2017 Hartmut Goebel@*
Copyright @copyright{} 2017 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018 Gábor Boskovits@*
Copyright @copyright{} 2018 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
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 System administration
* Guix: (guix). Manage installed software and system configuration.
* guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull. Update the list of available packages.
* guix system: (guix)Invoking guix system. Manage the operating system configuration.
@end direntry
@dircategory Software development
* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
* guix build: (guix)Invoking guix build. Building packages.
* guix pack: (guix)Invoking guix pack. Creating binary bundles.
@end direntry
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author The GNU Guix Developers
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*
@end titlepage
@c *********************************************************************
@node Top
@top GNU Guix
This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
zu GNU Guix}). If you would like to translate it in your native language,
consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* GNU Distribution:: Software for your friendly GNU system.
* Contributing:: Your help needed!
* Acknowledgments:: Thanks!
* GNU Free Documentation License:: The license of this manual.
* Concept Index:: Concepts.
* Programming Index:: Data types, functions, and variables.
--- The Detailed Node Listing ---
* Binary Installation:: Getting Guix running in no time!
* Requirements:: Software needed to build and run Guix.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
Setting Up the Daemon
* Build Environment Setup:: Preparing the isolated build environment.
* Daemon Offload Setup:: Offloading builds to remote machines.
* SELinux Support:: Using an SELinux policy for the daemon.
Package Management
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
* 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.
* Channels:: Customizing the package collection.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
* Official Substitute Server:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Substitute Authentication:: How Guix verifies substitutes.
* Proxy Settings:: How to get substitutes via proxy.
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
Programming Interface
* 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.
* Invoking guix repl:: Fiddling with Guix interactively.
Defining Packages
* package Reference:: The package data type.
* origin Reference:: The origin data type.
* Invoking guix build:: Building packages from the command line.
* Invoking guix edit:: Editing package definitions.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
* Invoking guix challenge:: Challenging substitute servers.
* Invoking guix copy:: Copying to and from a remote store.
* Invoking guix container:: Process isolation.
* Invoking guix weather:: Assessing substitute availability.
* Invoking guix processes:: Listing client processes.
Invoking @command{guix build}
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
GNU Distribution
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* 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 Installation
* Limitations:: What you can expect.
* Hardware Considerations:: Supported hardware.
* USB Stick and DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
* Installing GuixSD in a VM:: GuixSD playground.
* Building the Installation Image:: How this comes to be.
System Configuration
* Using the Configuration System:: Customizing your GNU system.
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions.
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
* Telephony Services:: Telephony services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
* Miscellaneous Services:: Other services.
Defining Services
* Service Composition:: The model for composing services.
* Service Types and Services:: Types and services.
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
Packaging Guidelines
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: A touch of British comedy.
* Perl Modules:: Little pearls.
* Java Packages:: Coffee break.
* Fonts:: Fond of fonts.
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
Coding Style
* Programming Paradigm:: How to compose your elements.
* Modules:: Where to store your code?
* Data Types and Pattern Matching:: Implementing data structures.
* Formatting Code:: Writing conventions.
@end detailmenu
@end menu
@c *********************************************************************
@node Introduction
@chapter Introduction
@cindex purpose
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
using the international phonetic alphabet (IPA).} is a package
management tool for the GNU system. Guix makes it easy for unprivileged
users to install, upgrade, or remove packages, to roll back to a
previous package set, to build packages from source, and generally
assists with the creation and maintenance of software environments.
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Invoking guix package}), a set of command-line utilities
(@pxref{Utilities}), as well as Scheme programming interfaces
(@pxref{Programming Interface}).
@cindex build daemon
Its @dfn{build daemon} is responsible for building packages on behalf of
users (@pxref{Setting Up the Daemon}) and for downloading pre-built
binaries from authorized sources (@pxref{Substitutes}).
@cindex extensibility of the distribution
@cindex customization, of packages
Guix includes package definitions for many GNU and non-GNU packages, all
of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
user's computing freedom}. It is @emph{extensible}: users can write
their own package definitions (@pxref{Defining Packages}) and make them
available as independent package modules (@pxref{Package Modules}). It
is also @emph{customizable}: users can @emph{derive} specialized package
definitions from existing ones, including from the command line
(@pxref{Package Transformation Options}).
@cindex Guix System Distribution
@cindex GuixSD
You can install GNU@tie{}Guix on top of an existing GNU/Linux system
where it complements the available tools without interference
(@pxref{Installation}), or you can use it as part of the standalone
@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
system configuration and Guix takes care of instantiating the
configuration in a transactional, reproducible, and stateless fashion
(@pxref{System Configuration}).
@cindex functional package management
@cindex isolation
Under the hood, Guix implements the @dfn{functional package management}
discipline pioneered by Nix (@pxref{Acknowledgments}).
In Guix, the package build and installation process is seen
as a @emph{function}, in the mathematical sense. That function takes inputs,
such as build scripts, a compiler, and libraries, and
returns an installed package. As a pure function, its result depends
solely on its inputs---for instance, it cannot refer to software or
scripts that were not explicitly passed as inputs. A build function
always produces the same result when passed a given set of inputs. It
cannot alter the environment of the running system 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{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{/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.
This approach is the foundation for the salient features of Guix: support
for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
@c *********************************************************************
@node Installation
@chapter Installation
@cindex installing Guix
@cindex official website
GNU Guix is available for download from its website at
@url{http://www.gnu.org/software/guix/}. This section describes the
software requirements of Guix, as well as how to install it and get
ready to use it.
Note that this section is concerned with the installation of the package
manager, which can be done on top of a running GNU/Linux system. If,
instead, you want to install the complete GNU operating system,
@pxref{System Installation}.
@cindex foreign distro
@cindex directories related to foreign distro
When installed on a running GNU/Linux system---thereafter called a
@dfn{foreign distro}---GNU@tie{}Guix complements the available tools
without interference. Its data lives exclusively in two directories,
usually @file{/gnu/store} and @file{/var/guix}; other files on your
system, such as @file{/etc}, are left untouched.
Once installed, Guix can be updated by running @command{guix pull}
(@pxref{Invoking guix pull}).
* Binary Installation:: Getting Guix running in no time!
* Requirements:: Software needed to build and run Guix.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
@end menu
@node Binary Installation
@section Binary Installation
@cindex installing Guix from binaries
@cindex installer script
This section describes how to install Guix on an arbitrary system from a
self-contained tarball providing binaries for Guix and for all its
dependencies. This is often quicker than installing from source, which
is described in the next sections. The only requirement is to have
GNU@tie{}tar and Xz.
We provide a
shell installer script}, which automates the download, installation, and
initial configuration of Guix. It should be run as the root user.
Installing goes along these lines:
@cindex downloading Guix binary
Download the binary tarball from
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
@c The following is somewhat duplicated in ``System Installation''.
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the tarball against it, along these lines:
$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
@end example
If that command fails because you do not have the required public key,
then run this command to import it:
$ gpg --keyserver @value{KEY-SERVER} \
--recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
and rerun the @code{gpg --verify} command.
@c end authentication part
Now, you need to become the @code{root} user. Depending on your distribution,
you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
# cd /tmp
# tar --warning=no-timestamp -xf \
# mv var/guix /var/ && mv gnu /
@end example
This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
The latter contains a ready-to-use profile for @code{root} (see next
Do @emph{not} unpack the tarball on a working Guix system since that
would overwrite its own essential files.
The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
not emit warnings about ``implausibly old time stamps'' (such
warnings were triggered by GNU@tie{}tar 1.26 and older; recent
versions are fine.)
They stem from the fact that all the
files in the archive have their modification time set to zero (which
means January 1st, 1970.) This is done on purpose to make sure the
archive content is independent of its creation time, thus making it
Make the profile available under @file{~root/.config/guix/current}, which is
where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
# mkdir -p ~root/.config/guix
# ln -sf /var/guix/profiles/per-user/root/current-guix \
@end example
Source @file{etc/profile} to augment @code{PATH} and other relevant
environment variables:
# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
source $GUIX_PROFILE/etc/profile
@end example
Create the group and user accounts for build users as explained below
(@pxref{Build Environment Setup}).
Run the daemon, and set it to automatically start on boot.
If your host distro uses the systemd init system, this can be achieved
with these commands:
@c Versions of systemd that supported symlinked service files are not
@c yet widely deployed, so we should suggest that users copy the service
@c files into place.
@c See this thread for more information:
@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
# systemctl start guix-daemon && systemctl enable guix-daemon
@end example
If your host distro uses the Upstart init system:
# initctl reload-configuration
# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
# start guix-daemon
@end example
Otherwise, you can still start the daemon manually with:
# ~root/.config/guix/current/bin/guix-daemon \
@end example
Make the @command{guix} command available to other users on the machine,
for instance with:
# mkdir -p /usr/local/bin
# cd /usr/local/bin
# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
@end example
It is also a good idea to make the Info version of this manual available
# mkdir -p /usr/local/share/info
# cd /usr/local/share/info
# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
do ln -s $i ; done
@end example
That way, assuming @file{/usr/local/share/info} is in the search path,
running @command{info guix} will open this manual (@pxref{Other Info
Directories,,, texinfo, GNU Texinfo}, for more details on changing the
Info search path.)
@cindex substitutes, authorization thereof
To use substitutes from @code{hydra.gnu.org} or one of its mirrors
(@pxref{Substitutes}), authorize them:
# guix archive --authorize < \
@end example
Each user may need to perform a few additional steps to make their Guix
environment ready for use, @pxref{Application Setup}.
@end enumerate
Voilà, the installation is complete!
You can confirm that Guix is working by installing a sample package into
the root profile:
# guix package -i hello
@end example
The @code{guix} package must remain available in @code{root}'s profile,
or it would become subject to garbage collection---in which case you
would find yourself badly handicapped by the lack of the @command{guix}
command. In other words, do not remove @code{guix} by running
@code{guix package -r guix}.
The binary installation tarball can be (re)produced and verified simply
by running the following command in the Guix source tree:
make guix-binary.@var{system}.tar.xz
@end example
... which, in turn, runs:
guix pack -s @var{system} --localstatedir \
--profile-name=current-guix guix
@end example
@xref{Invoking guix pack}, for more info on this handy tool.
@node Requirements
@section Requirements
This section lists requirements when building Guix from source. The
build procedure for Guix is the same as for other GNU software, and is
not covered here. Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.
GNU Guix depends on the following packages:
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or
later, including 2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
@c FIXME: Specify a version number once a release has been made.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
2017 or later;
@item @url{http://zlib.net, zlib};
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
allow you to use the @command{guix import pypi} command (@pxref{Invoking
guix import}). It is of
interest primarily for developers and not for casual users.
@c Note: We need at least 0.10.2 for 'channel-send-eof'.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
version 0.10.2 or later.
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:
@item @url{http://gnupg.org/, GNU libgcrypt};
@item @url{http://sqlite.org, SQLite 3};
@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
@cindex state directory
When configuring Guix on a system that already has a Guix installation,
be sure to specify the same state directory as the existing installation
using the @code{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
GNU Coding Standards}). The @command{configure} script protects against
unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).
@cindex Nix, compatibility
When a working installation of @url{http://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nix replaces the three dependencies above.
Guix is compatible with Nix, so it is possible to share the same store
between both. To do so, you must pass @command{configure} not only the
same @code{--with-store-dir} value, but also the same
@code{--localstatedir} value. The latter is essential because it
specifies where the database that stores metadata about the store is
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.
@node Running the Test Suite
@section Running the Test Suite
@cindex test suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite. It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software. To run the test
suite, type:
make check
@end example
Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up. The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
that is created for test purposes will already have various things in
It is also possible to run a subset of the tests by defining the
@code{TESTS} makefile variable as in this example:
make check TESTS="tests/store.scm tests/cpio.scm"
@end example
By default, tests results are displayed at a file level. In order to
see the details of every individual test cases, it is possible to define
the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
@end example
Upon failure, please email @email{bug-guix@@gnu.org} and attach the
@file{test-suite.log} file. Please specify the Guix version being used
as well as version numbers of the dependencies (@pxref{Requirements}) in
your message.
Guix also comes with a whole-system test suite that tests complete
GuixSD operating system instances. It can only run on systems where
Guix is already installed, using:
make check-system
@end example
or, again, by defining @code{TESTS} to select a subset of tests to run:
make check-system TESTS="basic mcron"
@end example
These system tests are defined in the @code{(gnu tests @dots{})}
modules. They work by running the operating systems under test with
lightweight instrumentation in a virtual machine (VM). They can be
computationally intensive or rather cheap, depending on whether
substitutes are available for their dependencies (@pxref{Substitutes}).
Some of them require a lot of storage space to hold VM images.
Again in case of test failures, please send @email{bug-guix@@gnu.org}
all the details.
@node Setting Up the Daemon
@section Setting Up the Daemon
@cindex daemon
Operations such as building a package or running the garbage collector
are all performed by a specialized process, the @dfn{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. See also @ref{Substitutes}, for information on how to allow
the daemon to download pre-built binaries.
* Build Environment Setup:: Preparing the isolated build environment.
* Daemon Offload Setup:: Offloading builds to remote machines.
* SELinux Support:: Using an SELinux policy for the daemon.
@end menu
@node Build Environment Setup
@subsection Build Environment Setup
@cindex build environment
In a standard multi-user setup, Guix and its daemon---the
@command{guix-daemon} program---are installed by the system
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
consistent state, and allowing built packages to be shared among users.
@cindex build users
When @command{guix-daemon} runs as @code{root}, you may not want package
build processes themselves to run as @code{root} too, for obvious
security reasons. To avoid that, a special pool of @dfn{build users}
should be created for use by build processes started by the daemon.
These build users need not have a shell and a home directory: they will
just be used when the daemon drops @code{root} privileges in build
processes. Having several such users allows the daemon to launch
distinct build processes under separate UIDs, which guarantees that they
do not interfere with each other---an essential feature since builds are
regarded as pure functions (@pxref{Introduction}).
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
# groupadd --system guixbuild
# for i in `seq -w 1 10`;
useradd -g guixbuild -G guixbuild \
-d /var/empty -s `which nologin` \
-c "Guix build user $i" --system \
@end example
The number of build users determines how many build jobs may run in
parallel, as specified by the @option{--max-jobs} option
(@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
@command{guix system vm} and related commands, you may need to add the
build users to the @code{kvm} group so they can access @file{/dev/kvm},
using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
(@pxref{Invoking guix system}).
The @code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
file in @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started. Similarly, if your
machine uses the Upstart init system, drop the
file in @file{/etc/init}.}:
# guix-daemon --build-users-group=guixbuild
@end example
@cindex chroot
This way, the daemon starts build processes in a chroot, under one of
the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
environment contains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------
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.};
the @code{/proc} directory; it only shows the processes of the container
since a separate PID name space is used;
@file{/etc/passwd} with an entry for the current user and an entry for
user @file{nobody};
@file{/etc/group} with an entry for the user's group;
@file{/etc/hosts} with an entry that maps @code{localhost} to
a writable @file{/tmp} directory.
@end itemize
You can influence the directory where the daemon stores build trees
@i{via} the @code{TMPDIR} environment variable. However, the build tree
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
This way, the value of @code{TMPDIR} does not leak inside build
environments, which avoids discrepancies in cases where build processes
capture the name of their build tree.
@vindex http_proxy
The daemon also honors the @code{http_proxy} environment variable for
HTTP downloads it performs, be it for fixed-output derivations
(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
If you are installing Guix as an unprivileged user, it is still possible
to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
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}@footnote{This feature is available only when
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
present.}. When that
feature is enabled, a list of user-specified build machines is read from
@file{/etc/guix/machines.scm}; every time a build is requested, for
instance via @code{guix build}, the daemon attempts to offload it to one
of the machines that satisfy the constraints of the derivation, 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:
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
(host-key "ssh-ed25519 AAAAC3Nza@dots{}")
(user "bob")
(speed 2.)) ;incredibly fast!
(name "meeps.example.org")
(system "mips64el-linux")
(host-key "ssh-rsa AAAAB3Nza@dots{}")
(user "alice")
(string-append (getenv "HOME")
@end example
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}
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 @code{build-machine} data type is
detailed below.
@deftp {Data Type} build-machine
This data type represents build machines to which the daemon may offload
builds. The important fields are:
@table @code
@item name
The host name of the remote machine.
@item system
The system type of the remote machine---e.g., @code{"x86_64-linux"}.
@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.
@item host-key
This must be the machine's SSH @dfn{public host key} in OpenSSH format.
This is used to authenticate the machine when we connect to it. It is a
long string that looks like this:
ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
@end example
If the machine is running the OpenSSH daemon, @command{sshd}, the host
key can be found in a file such as
If the machine is running the SSH daemon of GNU@tie{}lsh,
@command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
similar file. It can be converted to the OpenSSH format using
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
@end example
@end table
A number of optional fields may be specified:
@table @asis
@item @code{port} (default: @code{22})
Port number of SSH server on the machine.
@item @code{private-key} (default: @file{~root/.ssh/id_rsa})
The SSH private key file to use when connecting to the machine, in
OpenSSH format. This key must not be protected with a passphrase.
Note that the default value is the private key @emph{of the root
account}. Make sure it exists if you use the default.
@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
@itemx @code{compression-level} (default: @code{3})
The SSH-level compression methods and compression level requested.
Note that offloading relies on SSH compression to reduce bandwidth usage
when transferring files to and from build machines.
@item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
File name of the Unix-domain socket @command{guix-daemon} is listening
to on that machine.
@item @code{parallel-builds} (default: @code{1})
The number of builds that may run in parallel on the machine.
@item @code{speed} (default: @code{1.0})
A ``relative speed factor''. The offload scheduler will tend to prefer
machines with a higher speed factor.
@item @code{features} (default: @code{'()})
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
@end deftp
The @code{guile} command must be in the search path on the build
machines. In addition, the Guix modules must be in
@code{$GUILE_LOAD_PATH} on the build machine---you can check whether
this is the case by running:
ssh build-machine guile -c "'(use-modules (guix config))'"
@end example
There is 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 first need to
generate a key pair on each machine to allow the daemon to export signed
archives of files from the store (@pxref{Invoking guix archive}):
# guix archive --generate-key
@end example
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:
# guix archive --authorize < master-public-key.txt
@end example
Likewise, the master machine must authorize the key of each build machine.
All the fuss with keys is here to express pairwise mutual trust
relations between the master and the build machines. Concretely, when
the master receives files from a build machine (and @i{vice versa}), its
build daemon can make sure they are genuine, have not been tampered
with, and that they are signed by an authorized key.
@cindex offload test
To test whether your setup is operational, run this command on the
master node:
# guix offload test
@end example
This will attempt to connect to each of the build machines specified in
@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are
available on each machine, attempt to export to the machine and import
from it, and report any error in the process.
If you want to test a different machine file, just specify it on the
command line:
# guix offload test machines-qualif.scm
@end example
Last, you can test the subset of the machines whose name matches a
regular expression like this:
# guix offload test machines.scm '\.gnu\.org$'
@end example
@cindex offload status
To display the current load of all build hosts, run this command on the
main node:
# guix offload status
@end example
@node SELinux Support
@subsection SELinux Support
@cindex SELinux, daemon policy
@cindex mandatory access control, SELinux
@cindex security, guix-daemon
Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
can be installed on a system where SELinux is enabled, in order to label
Guix files and to specify the expected behavior of the daemon. Since
GuixSD does not provide an SELinux base policy, the daemon policy cannot
be used on GuixSD.
@subsubsection Installing the SELinux policy
@cindex SELinux, policy installation
To install the policy run this command as root:
semodule -i etc/guix-daemon.cil
@end example
Then relabel the file system with @code{restorecon} or by a different
mechanism provided by your system.
Once the policy is installed, the file system has been relabeled, and
the daemon has been restarted, it should be running in the
@code{guix_daemon_t} context. You can confirm this with the following
ps -Zax | grep guix-daemon
@end example
Monitor the SELinux log files as you run a command like @code{guix build
hello} to convince yourself that SELinux permits all necessary
@subsubsection Limitations
@cindex SELinux, limitations
This policy is not perfect. Here is a list of limitations or quirks
that should be considered when deploying the provided SELinux policy for
the Guix daemon.
@code{guix_daemon_socket_t} isn’t actually used. None of the socket
operations involve contexts that have anything to do with
@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
but it would be preferrable to define socket rules for only this label.
@code{guix gc} cannot access arbitrary links to profiles. By design,
the file label of the destination of a symlink is independent of the
file label of the link itself. Although all profiles under
$localstatedir are labelled, the links to these profiles inherit the
label of the directory they are in. For links in the user’s home
directory this will be @code{user_home_t}. But for links from the root
user’s home directory, or @file{/tmp}, or the HTTP server’s working
directory, etc, this won’t work. @code{guix gc} would be prevented from
reading and following these links.
The daemon’s feature to listen for TCP connections might no longer work.
This might require extra rules, because SELinux treats network sockets
differently from files.
Currently all files with a name matching the regular expression
@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
label @code{guix_daemon_exec_t}; this means that @emph{any} file with
that name in any profile would be permitted to run in the
@code{guix_daemon_t} domain. This is not ideal. An attacker could
build a package that provides this executable and convince a user to
install and run it, which lifts it into the @code{guix_daemon_t} domain.
At that point SELinux could not prevent it from accessing files that are
allowed for processes in that domain.
We could generate a much more restrictive policy at installation time,
so that only the @emph{exact} file name of the currently installed
@code{guix-daemon} executable would be labelled with
@code{guix_daemon_exec_t}, instead of using a broad regular expression.
The downside is that root would have to install or upgrade the policy at
installation time whenever the Guix package that provides the
effectively running @code{guix-daemon} executable is upgraded.
@end enumerate
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
The @command{guix-daemon} program implements all the functionality to
access the store. This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc. It
is normally run as @code{root} like this:
# guix-daemon --build-users-group=guixbuild
@end example
For details on how to set it up, @pxref{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
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
system directories. By default, the latter contains @file{/dev} and
@file{/dev/pts}. 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}).
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
its @code{TMPDIR} environment variable. This directory is shared with
the container for the duration of the build, though within the container,
the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Invoking guix build, @option{--keep-failed}}).
The daemon listens for connections and spawns one sub-process for each session
started by a client (one of the @command{guix} sub-commands.) The
@command{guix processes} command allows you to get an overview of the activity
on your system by viewing each of the active sessions and clients.
@xref{Invoking guix processes}, for more information.
The following command-line options are supported:
@table @code
@item --build-users-group=@var{group}
Take users from @var{group} to run build processes (@pxref{Setting Up
the Daemon, build users}).
@item --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
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}).
@item --substitute-urls=@var{urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted,
@indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
(@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
@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.
When this option is used, @command{guix gc --list-failures} can be used
to query the set of store items marked as failed; @command{guix gc
--clear-failures} removes store items from the set of cached failures.
@xref{Invoking guix gc}.
@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.
The default value is @code{0}, but it may be overridden by clients, such
as the @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
The effect is to define the @code{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. The default value is
@code{1}. Setting it to @code{0} means that no builds will be performed
locally; instead, the daemon will offload builds (@pxref{Daemon Offload
Setup}), or simply fail.
@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.
The default value is @code{0}, which disables the timeout.
The value specified here can be overridden by clients (@pxref{Common
Build Options, @code{--max-silent-time}}).
@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.
The default value is @code{0}, which disables the timeout.
The value specified here can be overridden by clients (@pxref{Common
Build Options, @code{--timeout}}).
@item --rounds=@var{N}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical. Note that this
setting can be overridden by clients such as @command{guix build}
(@pxref{Invoking guix build}).
When used in conjunction with @option{--keep-failed}, the differing
output is kept in the store, under @file{/gnu/store/@dots{}-check}.
This makes it easy to look for differences between the two results.
@item --debug
Produce debugging output.
This is useful to debug daemon start-up issues, but then it may be
overridden by clients, for example the @code{--verbosity} option of
@command{guix build} (@pxref{Invoking guix build}).
@item --chroot-directory=@var{dir}
Add @var{dir} to the build chroot.
Doing this may change the result of build processes---for instance if
they use optional dependencies found in @var{dir} when it is available,
and not otherwise. For that reason, it is not recommended to do so.
Instead, make sure that each derivation declares all the inputs that it
@item --disable-chroot
Disable chroot builds.
Using this option is not recommended since, again, it would allow build
processes to gain access to undeclared dependencies. It is necessary,
though, when @command{guix-daemon} is running under an unprivileged user
@item --log-compression=@var{type}
Compress build logs according to @var{type}, one of @code{gzip},
@code{bzip2}, or @code{none}.
Unless @code{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}. To save space, the daemon automatically compresses
them with bzip2 by default.
@item --disable-deduplication
@cindex deduplication
Disable automatic file ``deduplication'' in the store.
By default, files added to the store are automatically ``deduplicated'':
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file. This can
noticeably reduce disk usage, at the expense of slightly increased
input/output load at the end of a build process. This option disables
this optimization.
@item --gc-keep-outputs[=yes|no]
Tell whether the garbage collector (GC) must keep outputs of live
@cindex GC roots
@cindex garbage collector roots
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 reachable from a GC
root. @xref{Invoking guix gc}, for more on 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.
In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness
to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to
``yes'' causes liveness to flow from derivations to outputs. When both are
set to ``yes'', 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 reachable from a GC
root. 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.
This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.
@item --lose-logs
Do not keep build logs. By default they are kept under
@item --system=@var{system}
Assume @var{system} as the current system type. By default it is the
architecture/kernel pair found at configure time, such as
@item --listen=@var{endpoint}
Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
as the file name of a Unix-domain socket if it starts with
@code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
host name or host name and port to listen to. Here are a few examples:
@table @code
@item --listen=/gnu/var/daemon
Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
creating it if needed.
@item --listen=localhost
@cindex daemon, remote access
@cindex remote access to the daemon
@cindex daemon, cluster setup
@cindex clusters, daemon setup
Listen for TCP connections on the network interface corresponding to
@code{localhost}, on port 44146.
@item --listen=
Listen for TCP connections on the network interface corresponding to
@code{}, on port 1234.
@end table
This option can be repeated multiple times, in which case
@command{guix-daemon} accepts connections on all the specified
endpoints. Users can tell client commands what endpoint to connect to
by setting the @code{GUIX_DAEMON_SOCKET} environment variable
(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).
@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}. Using
@code{--listen=@var{host}} is suitable on local networks, such as
clusters, where only trusted nodes may connect to the build daemon. In
other cases where remote access to the daemon is needed, we recommend
using Unix-domain sockets along with SSH.
@end quotation
When @code{--listen} is omitted, @command{guix-daemon} listens for
connections on the Unix-domain socket located at
@end table
@node Application Setup
@section Application Setup
@cindex foreign distro
When using Guix on top of GNU/Linux distribution other than GuixSD---a
so-called @dfn{foreign distro}---a few additional steps are needed to
get everything in place. Here are some of them.
@subsection Locales
@cindex locales, when not on GuixSD
@vindex LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
host system. Instead, you must first install one of the locale packages
available with Guix and then define the @code{GUIX_LOCPATH} environment
$ guix package -i glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
Manual}). There are two important differences though:
@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
to make sure the programs of the foreign distro will not end up loading
incompatible locale data.
libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
@code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
should your Guix profile contain a mixture of programs linked against
different libc version, each libc version will only try to load locale
data in the right format.
@end enumerate
This is important because the locale data format used by different libc
versions may be incompatible.
@subsection Name Service Switch
@cindex name service switch, glibc
@cindex NSS (name service switch), glibc
@cindex nscd (name service caching daemon)
@cindex name service caching daemon (nscd)
When using Guix on a foreign distro, we @emph{strongly recommend} that
the system run the GNU C library's @dfn{name service cache daemon},
@command{nscd}, which should be listening on the
@file{/var/run/nscd/socket} socket. Failing to do that, applications
installed with Guix may fail to look up host names or user accounts, or
may even crash. The next paragraphs explain why.
@cindex @file{nsswitch.conf}
The GNU C library implements a @dfn{name service switch} (NSS), which is
an extensible mechanism for ``name lookups'' in general: host name
resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
The GNU C Library Reference Manual}).
@cindex Network information service (NIS)
@cindex NIS (Network information service)
Being extensible, the NSS supports @dfn{plugins}, which provide new name
lookup implementations: for example, the @code{nss-mdns} plugin allow
resolution of @code{.local} host names, the @code{nis} plugin allows
user account lookup using the Network information service (NIS), and so
on. These extra ``lookup services'' are configured system-wide in
@file{/etc/nsswitch.conf}, and all the programs running on the system
honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
Reference Manual}).
When they perform a name lookup---for instance by calling the
@code{getaddrinfo} function in C---applications first try to connect to
the nscd; on success, nscd performs name lookups on their behalf. If
the nscd is not running, then they perform the name lookup by
themselves, by loading the name lookup services into their own address
space and running it. These name lookup services---the
@file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
the host system's C library, rather than from the C library the
application is linked against (the C library coming from Guix).
And this is where the problem is: if your application is linked against
Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
likely crash or have its name lookups fail unexpectedly.
Running @command{nscd} on the system, among other advantages, eliminates
this binary incompatibility problem because those @code{libnss_*.so}
files are loaded in the @command{nscd} process, not in applications
@subsection X11 Fonts
@cindex fonts
The majority of graphical applications use Fontconfig to locate and
load fonts and perform X11-client-side rendering. The @code{fontconfig}
package in Guix looks for fonts in @file{$HOME/.guix-profile}
by default. Thus, to allow graphical applications installed with Guix
to display fonts, you have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
has multiple outputs, one per language family (@pxref{Packages with
Multiple Outputs}). For instance, the following command installs fonts
for Chinese languages:
guix package -i font-adobe-source-han-sans:cn
@end example
@cindex @code{xterm}
Older programs such as @command{xterm} do not use Fontconfig and instead
rely on server-side font rendering. Such programs require to specify a
full name of a font using XLFD (X Logical Font Description), like this:
-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
@end example
To be able to use such full names for the TrueType fonts installed in
your Guix profile, you need to extend the font path of the X server:
@c Note: 'xset' does not accept symlinks so the trick below arranges to
@c get at the real directory. See <https://bugs.gnu.org/30655>.
xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
@end example
@cindex @code{xlsfonts}
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.
@cindex @code{fc-cache}
@cindex font cache
After installing fonts you may have to refresh the font cache to use
them in applications. The same applies when applications installed via
Guix do not seem to find fonts. To force rebuilding of the font cache
run @code{fc-cache -f}. The @code{fc-cache} command is provided by the
@code{fontconfig} package.
@subsection X.509 Certificates
@cindex @code{nss-certs}
The @code{nss-certs} package provides X.509 certificates, which allow
programs to authenticate Web servers accessed over HTTPS.
When using Guix on a foreign distro, you can install this package and
define the relevant environment variables so that packages know where to
look for certificates. @xref{X.509 Certificates}, for detailed
@subsection Emacs Packages
@cindex @code{emacs}
When you install Emacs packages with Guix, the elisp files may be placed
either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
sub-directories of
@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
directory exists because potentially there may exist thousands of Emacs
packages and storing all their files in a single directory may not be
reliable (because of name conflicts). So we think using a separate
directory for each package is a good idea. It is very similar to how
the Emacs package system organizes the file structure (@pxref{Package
Files,,, emacs, The GNU Emacs Manual}).
By default, Emacs (installed with Guix) ``knows'' where these packages
are placed, so you do not need to perform any configuration. If, for
some reason, you want to avoid auto-loading Emacs packages installed
with Guix, you can do so by running Emacs with @code{--no-site-file}
option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
@subsection The GCC toolchain
@cindex GCC
@cindex ld-wrapper
Guix offers individual compiler packages such as @code{gcc} but if you
are in need of a complete toolchain for compiling and linking source
code what you really want is the @code{gcc-toolchain} package. This
package provides a complete GCC toolchain for C/C++ development,
including GCC itself, the GNU C Library (headers and binaries, plus
debugging symbols in the @code{debug} output), Binutils, and a linker
@cindex attempt to use impure library, error message
The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
invoke the actual linker with this new set of arguments. By default,
the linker wrapper refuses to link to libraries outside the store to
ensure ``purity''. This can be annoying when using the toolchain to
link with local libraries. To allow references to libraries outside the
store you need to define the environment variable
@c TODO What else?
@c *********************************************************************
@node Package Management
@chapter Package Management
@cindex packages
The purpose of GNU Guix is to allow users to easily install, upgrade, and
remove software packages, without having to know about their build
procedures or dependencies. Guix also goes beyond this obvious set of
This chapter describes the main features of Guix, as well as the
package management tools it provides. Along with the command-line
interface described below (@pxref{Invoking guix package, @code{guix
package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
emacs-guix, The Emacs-Guix Reference Manual}), after installing
@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
with it):
guix package -i emacs-guix
@end example
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
* 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.
* Channels:: Customizing the package collection.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
@end menu
@node Features
@section Features
When using Guix, each package ends up in the @dfn{package store}, in its
own directory---something that resembles
@file{/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
use. These profiles are stored within each user's home directory, at
For example, @code{alice} installs GCC 4.7.2. As a result,
@file{/home/alice/.guix-profile/bin/gcc} points to
@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{/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
packages (@pxref{Invoking guix package}). It operates on the per-user
profiles, and can be used @emph{with normal user privileges}.
@cindex transactions
The command provides the obvious install, remove, and upgrade
operations. Each invocation is actually a @emph{transaction}: either
the specified operation succeeds, or nothing happens. Thus, if the
@command{guix package} process is terminated during the transaction,
or if a power outage occurs during the transaction, then the user's
profile remains in its previous state, and remains usable.
In addition, any package transaction may be @emph{rolled back}. So, if,
for example, an upgrade installs a new version of a package that turns
out to have a serious bug, users may roll back to the previous instance
of their profile, which was known to work well. Similarly, the global
system configuration on GuixSD is subject to
transactional upgrades and roll-back
(@pxref{Using the Configuration System}).
All packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by user
profiles, and remove those that are provably no longer referenced
(@pxref{Invoking guix gc}). Users may also explicitly remove old
generations of their profile so that the packages they refer to can be
@cindex reproducibility
@cindex reproducible builds
Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
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. 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{/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}). Because build results are usually bit-for-bit
reproducible, users do not have to trust servers that provide
substitutes: they can force a local build and @emph{challenge} providers
(@pxref{Invoking guix challenge}).
Control over the build environment is a feature that is also useful for
developers. The @command{guix environment} command allows developers of
a package to quickly set up the right development environment for their
package, without having to manually install the dependencies of the
package into their profile (@pxref{Invoking guix environment}).
@cindex replication, of software environments
@cindex provenance tracking, of software artifacts
All of Guix and its package definitions is version-controlled, and
@command{guix pull} allows you to ``travel in time'' on the history of Guix
itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
Guix instance on a different machine or at a later point in time, which in
turn allows you to @emph{replicate complete software environments}, while
retaining precise @dfn{provenance tracking} of the software.
@node Invoking guix package
@section Invoking @command{guix package}
@cindex installing packages
@cindex removing packages
@cindex package installation
@cindex package removal
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
previous configurations. It operates only on the user's own profile,
and works with normal user privileges (@pxref{Features}). Its syntax
guix package @var{options}
@end example
@cindex transactions
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
previous @dfn{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:
guix package -r lua -i guile guile-cairo
@end example
@command{guix package} also supports a @dfn{declarative approach}
whereby the user specifies the exact set of packages to be available and
passes it @i{via} the @option{--manifest} option
(@pxref{profile-manifest, @option{--manifest}}).
@cindex profile
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
@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
variable, and so on.
@cindex search paths
If you are not using the Guix System Distribution, consider adding the
following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
shells get all the right environment variable definitions:
GUIX_PROFILE="$HOME/.guix-profile" ; \
source "$HOME/.guix-profile/etc/profile"
@end example
In a multi-user setup, user profiles are stored in a place registered as
a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
to (@pxref{Invoking guix gc}). That directory is normally
@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
@code{--localstatedir}, and @var{user} is the user name. The
@file{per-user} directory is created when @command{guix-daemon} is
started, and the @var{user} sub-directory is created by @command{guix
The @var{options} can be among the following:
@table @code
@item --install=@var{package} @dots{}
@itemx -i @var{package} @dots{}
Install the specified @var{package}s.
Each @var{package} may specify either a simple package name, such as
@code{guile}, or a package name followed by an at-sign and version number,
such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
case, the newest version prefixed by @code{1.8} is selected.)
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}). 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
that automatically get installed along with the required package
(@pxref{package-propagated-inputs, @code{propagated-inputs} in
@code{package} objects}, for information about propagated inputs in
package definitions).
An example is the GNU MPC library: its C header files refer to those of
the GNU MPFR library, which in turn refer to those of the GMP library.
Thus, when installing MPC, the MPFR and GMP libraries also get installed
in the profile; removing MPC also removes MPFR and GMP---unless they had
also been explicitly installed by the user.
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
environment variable definitions are reported here.
@item --install-from-expression=@var{exp}
@itemx -e @var{exp}
Install the package @var{exp} evaluates to.
@var{exp} must be a Scheme expression that evaluates to a
@code{<package>} object. This option is notably useful to disambiguate
between same-named variants of a package, with expressions such as
@code{(@@ (gnu packages base) guile-final)}.
Note that this option installs the first output of the specified
package, which may be insufficient when needing a specific output of a
multiple-output package.
@item --install-from-file=@var{file}
@itemx -f @var{file}
Install the package that the code within @var{file} evaluates to.
As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):
@verbatiminclude package-hello.scm
@end example
Developers may find it useful to include such a @file{guix.scm} file
in the root of their project source tree that can be used to test
development snapshots and create reproducible development environments
(@pxref{Invoking guix environment}).
@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
@item --upgrade[=@var{regexp} @dots{}]
@itemx -u [@var{regexp} @dots{}]
@cindex upgrading packages
Upgrade all the installed packages. If one or more @var{regexp}s are
specified, upgrade only installed packages whose name matches a
@var{regexp}. Also see the @code{--do-not-upgrade} option below.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
you should regularly run @command{guix pull} (@pxref{Invoking guix
@item --do-not-upgrade[=@var{regexp} @dots{}]
When used together with the @code{--upgrade} option, do @emph{not}
upgrade any packages whose name matches a @var{regexp}. For example, to
upgrade all packages in the current profile except those containing the
substring ``emacs'':
$ guix package --upgrade . --do-not-upgrade emacs
@end example
@item @anchor{profile-manifest}--manifest=@var{file}
@itemx -m @var{file}
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
returned by the Scheme code in @var{file}.
This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--install} and similar
commands. The advantage is that @var{file} can be put under version
control, copied to different machines to reproduce the same profile, and
so on.
@c FIXME: Add reference to (guix profile) documentation when available.
@var{file} must return a @dfn{manifest} object, which is roughly a list
of packages:
@findex packages->manifest
(use-package-modules guile emacs)
(list emacs
;; Use a specific package output.
(list guile-2.0 "debug")))
@end example
@findex specifications->manifest
In this example we have to know which modules define the @code{emacs}
and @code{guile-2.0} variables to provide the right
@code{use-package-modules} line, which can be cumbersome. We can
instead provide regular package specifications and let
@code{specifications->manifest} look up the corresponding package
objects, like this:
'("emacs" "guile@@2.2" "guile@@2.2:debug"))
@end example
@item --roll-back
@cindex rolling back
@cindex undoing transactions
@cindex transactions, undoing
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
When combined with options such as @code{--install}, roll back occurs
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{zeroth
generation}, which contains no files apart from its own metadata.
After having rolled back, installing, removing, or upgrading packages
overwrites previous future generations. Thus, the history of the
generations in a profile is always linear.
@item --switch-generation=@var{pattern}
@itemx -S @var{pattern}
@cindex generations
Switch to a particular generation defined by @var{pattern}.
@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''. The latter means: move forward/backward by a
specified number of generations. For example, if you want to return to
the latest generation after @code{--roll-back}, use
The difference between @code{--roll-back} and
@code{--switch-generation=-1} is that @code{--switch-generation} will
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
@item --search-paths[=@var{kind}]
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
needed in order to use the set of installed packages. These environment
variables are used to specify @dfn{search paths} for files used by some
of the installed packages.
For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
environment variables to be defined so it can look for headers and
libraries in the user's profile (@pxref{Environment Variables,,, gcc,
Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
library are installed in the profile, then @code{--search-paths} will
suggest setting these variables to @code{@var{profile}/include} and
@code{@var{profile}/lib}, respectively.
The typical use case is to define these environment variables in the
$ eval `guix package --search-paths`
@end example
@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
meaning that the returned environment variable definitions will either
be exact settings, or prefixes or suffixes of the current value of these
variables. When omitted, @var{kind} defaults to @code{exact}.
This option can also be used to compute the @emph{combined} search paths
of several profiles. Consider this example:
$ guix package -p foo -i guile
$ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths
@end example
The last command above reports about the @code{GUILE_LOAD_PATH}
variable, even though, taken individually, neither @file{foo} nor
@file{bar} would lead to that recommendation.
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
@cindex collisions, in a profile
@cindex colliding packages in profiles
@cindex profile collisions
@item --allow-collisions
Allow colliding packages in the new profile. Use at your own risk!
By default, @command{guix package} reports as an error @dfn{collisions}
in the profile. Collisions happen when two or more different versions
or variants of a given package end up in the profile.
@item --verbose
Produce verbose output. In particular, emit the build log of the
environment on the standard error port.
@item --bootstrap
Use the bootstrap Guile to build the profile. This option is only
useful to distribution developers.
@end table
In addition to these actions, @command{guix package} supports the
following options to query the current state of a profile, or the
availability of packages:
@table @option
@item --search=@var{regexp}
@itemx -s @var{regexp}
@cindex searching for packages
List the available packages whose name, synopsis, or description matches
@var{regexp}, sorted by relevance. Print all the metadata of matching packages in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
GNU recutils manual}).
This allows specific fields to be extracted using the @command{recsel}
command, for instance:
$ guix package -s malloc | recsel -p name,version,relevance
name: jemalloc
version: 4.5.0
relevance: 6
name: glibc
version: 2.25
relevance: 1
name: libgc
version: 7.6.0
relevance: 1
@end example
Similarly, to show the name of all the packages available under the
terms of the GNU@tie{}LGPL version 3:
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils
name: gmp
@end example
It is also possible to refine search results using several @code{-s}
flags. For example, the following command returns a list of board
$ guix package -s '\<board\>' -s game | recsel -p name
name: gnubg
@end example
If we were to omit @code{-s game}, we would also get software packages
that deal with printed circuit boards; removing the angle brackets
around @code{board} would further add packages that have to do with
And now for a more elaborate example. The following command searches
for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
libraries, and prints the name and synopsis of the matching packages:
$ guix package -s crypto -s library | \
recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example
@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
information on @dfn{selection expressions} for @code{recsel -e}.
@item --show=@var{package}
Show details about @var{package}, taken from the list of available packages, in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
recutils manual}).
$ guix package --show=python | recsel -p name,version
name: python
version: 2.7.6
name: python
version: 3.3.5
@end example
You may also specify the full name of a package to only get details about a
specific version of it:
$ guix package --show=python@@3.4 | recsel -p name,version
name: python
version: 3.4.3
@end example
@item --list-installed[=@var{regexp}]
@itemx -I [@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
is installed (for instance, @code{out} for the default output,
@code{include} for its headers, etc.), and the path of this package in
the store.
@item --list-available[=@var{regexp}]
@itemx -A [@var{regexp}]
List packages currently available in the distribution for this system
(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
installed packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name,
its version string, the parts of the package (@pxref{Packages with
Multiple Outputs}), and the source location of its definition.
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
@cindex generations
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
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:
@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 smaller 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
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 @emph{not} deleted. Also, the
zeroth generation is never deleted.
Note that deleting generations prevents rolling 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 (@pxref{Common Build
Options}). It also supports package transformation options, such as
@option{--with-source} (@pxref{Package Transformation Options}).
However, note that package transformations are lost when upgrading; to
preserve transformations across upgrades, you should define your own
package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
(@pxref{Defining Packages}).
@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, or both. 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.
* Official Substitute Server:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Substitute Authentication:: How Guix verifies substitutes.
* Proxy Settings:: How to get substitutes via proxy.
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
@end menu
@node Official Substitute Server
@subsection Official Substitute Server
@cindex hydra
@cindex build farm
The @code{mirror.hydra.gnu.org} server is a front-end to an official build farm
that builds packages from Guix continuously for some
architectures, and makes them available as substitutes. This is the
default source of substitutes; it can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
or to client tools such as @command{guix package}
(@pxref{client-substitute-urls,, client @option{--substitute-urls}
Substitute URLs can be either HTTP or HTTPS.
HTTPS is recommended because communications are encrypted; conversely,
using HTTP makes all communications visible to an eavesdropper, who
could use the information gathered to determine, for instance, whether
your system has unpatched security vulnerabilities.
Substitutes from the official build farm are enabled by default when
using the Guix System Distribution (@pxref{GNU Distribution}). However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
installation steps (@pxref{Installation}). The following paragraphs
describe how to enable or disable substitutes for the official build
farm; the same procedure can also be used to enable substitutes for any
other substitute server.
@node Substitute Server Authorization
@subsection Substitute Server Authorization
@cindex security
@cindex substitutes, authorization thereof
@cindex access control list (ACL), for substitutes
@cindex ACL (access control list), for substitutes
To allow Guix to download substitutes from @code{hydra.gnu.org} or a
mirror thereof, 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.
The public key for @code{hydra.gnu.org} 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:
# guix archive --authorize < @var{prefix}/share/guix/hydra.gnu.org.pub
@end example
@quotation Note
Similarly, the @file{berlin.guixsd.org.pub} file contains the public key
for the project's new build farm, reachable at
As of this writing @code{berlin.guixsd.org} is being upgraded so it can
better scale up, but you might want to give it a try. It is backed by
20 x86_64/i686 build nodes and may be able to provide substitutes more
quickly than @code{mirror.hydra.gnu.org}.
@end quotation
Once this is in place, the output of a command like @code{guix build}
should change from something like:
$ guix build emacs --dry-run
The following derivations would be built:
@end example
to something like:
$ guix build emacs --dry-run
112.3 MB would be downloaded:
@end example
This indicates that substitutes from @code{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.
@cindex substitutes, how to disable
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.
@node Substitute Authentication
@subsection Substitute Authentication
@cindex digital signatures
Guix detects and raises an error when attempting to use a substitute
that has been tampered with. Likewise, it ignores substitutes that are
not signed, or that are not signed by one of the keys listed in the ACL.
There is one exception though: if an unauthorized server provides
substitutes that are @emph{bit-for-bit identical} to those provided by
an authorized server, then the unauthorized server becomes eligible for
downloads. For example, assume we have chosen two substitute servers
with this option:
--substitute-urls="https://a.example.org https://b.example.org"
@end example
@cindex reproducible builds
If the ACL contains only the key for @code{b.example.org}, and if
@code{a.example.org} happens to serve the @emph{exact same} substitutes,
then Guix will download substitutes from @code{a.example.org} because it
comes first in the list and can be considered a mirror of
@code{b.example.org}. In practice, independent build machines usually
produce the same binaries, thanks to bit-reproducible builds (see
When using HTTPS, the server's X.509 certificate is @emph{not} validated
(in other words, the server is not authenticated), contrary to what
HTTPS clients such as Web browsers usually do. This is because Guix
authenticates substitute information itself, as explained above, which
is what we care about (whereas X.509 certificates are about
authenticating bindings between domain names and public keys.)
@node Proxy Settings
@subsection Proxy Settings
@vindex http_proxy
Substitutes are downloaded over HTTP or HTTPS.
The @code{http_proxy} environment
variable can be set in the environment of @command{guix-daemon} and is
honored for downloads of substitutes. Note that the value of
@code{http_proxy} in the environment where @command{guix build},
@command{guix package}, and other client commands are run has
@emph{absolutely no effect}.
@node Substitution Failure
@subsection Substitution Failure
Even when a substitute for a derivation is available, sometimes the
substitution attempt will fail. This can happen for a variety of
reasons: the substitute server might be offline, the substitute may
recently have been deleted, the connection might have been interrupted,
When substitutes are enabled and a substitute for a derivation is
available, but the substitution attempt fails, Guix will attempt to
build the derivation locally depending on whether or not
@code{--fallback} was given (@pxref{fallback-option,, common build
option @code{--fallback}}). Specifically, if @code{--fallback} was
omitted, then no local build will be performed, and the derivation is
considered to have failed. However, if @code{--fallback} was given,
then Guix will attempt to build the derivation locally, and the success
or failure of the derivation depends on the success or failure of the
local build. Note that when substitutes are disabled or no substitute
is available for the derivation in question, a local build will
@emph{always} be performed, regardless of whether or not
@code{--fallback} was given.
To get an idea of how many substitutes are available right now, you can
try running the @command{guix weather} command (@pxref{Invoking guix
weather}). This command provides statistics on the substitutes provided
by a server.
@node On Trusting Binaries
@subsection On Trusting Binaries
@cindex trust, of pre-built binaries
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. One way to help is by publishing the software you
build using @command{guix publish} so that others have one more choice
of server to download substitutes from (@pxref{Invoking guix publish}).
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. The @command{guix challenge} command aims to
help users assess substitute servers, and to assist developers in
finding out about non-deterministic package builds (@pxref{Invoking guix
challenge}). Similarly, the @option{--check} option of @command{guix
build} allows users to check whether previously-installed substitutes
are genuine by rebuilding them locally (@pxref{build-check,
@command{guix build --check}}).
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 multiple-output packages
@cindex package outputs
@cindex outputs
Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads to exactly one directory in the store. When running
@command{guix package -i glibc}, one installs the default output of the
GNU libc package; the default output is called @code{out}, but its name
can be omitted as shown in this command. In this particular case, the
default output of @code{glibc} contains all the C header files, shared
libraries, static libraries, Info documentation, and other supporting
Sometimes it is more appropriate to separate the various types of files
produced from a single source package into separate outputs. For
instance, the GLib C library (used by GTK+ and related packages)
installs more than 20 MiB of reference documentation as HTML pages.
To save space for users who do not need it, the documentation goes to a
separate output, called @code{doc}. To install the main GLib output,
which contains everything but the documentation, one would run:
guix package -i glib
@end example
@cindex documentation
The command to install its documentation is:
guix package -i glib:doc
@end example
Some packages install programs with different ``dependency footprints''.
For instance, the WordNet package installs both command-line tools and
graphical user interfaces (GUIs). The former depend solely on the C
library, whereas the latter depend on Tcl/Tk and the underlying X
libraries. In this case, we leave the command-line tools in the default
output, whereas the GUIs are in a separate output. This allows users
who do not need the GUIs to save space. The @command{guix size} command
can help find out about such situations (@pxref{Invoking guix size}).
@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
There are several such multiple-output packages in the GNU distribution.
Other conventional output names include @code{lib} for libraries and
possibly header files, @code{bin} for stand-alone programs, and
@code{debug} for debugging information (@pxref{Installing Debugging
Files}). The outputs of a packages are listed in the third column of
the output of @command{guix package --list-available} (@pxref{Invoking
guix package}).
@node Invoking guix gc
@section Invoking @command{guix gc}
@cindex garbage collector
@cindex disk space
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{/gnu/store} directory. It is
the @emph{only} way to remove files from @file{/gnu/store}---removing
files or directories manually may break it beyond repair!
@cindex GC roots
@cindex garbage collector roots
The garbage collector has a set of known @dfn{roots}: any file under
@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 (``GC roots'' for short)
includes default user profiles; by default, the symlinks under
@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
added 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}).
Our recommendation is to run a garbage collection periodically, or when
you are short on disk space. For instance, to guarantee that at least
5@tie{}GB are available on your disk, simply run:
guix gc -F 5G
@end example
It is perfectly safe to run as a non-interactive periodic job
(@pxref{Scheduled Job Execution}, for how to set up such a job on
GuixSD). Running @command{guix gc} with no arguments will collect as
much garbage as it can, but that is often inconvenient: you may find
yourself having to rebuild or re-download software that is ``dead'' from
the GC viewpoint but that is necessary to build other pieces of
software---e.g., the compiler tool chain.
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), to print garbage-collector
information, or for more advanced queries. The garbage collection
options are as follows:
@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Collect garbage---i.e., unreachable @file{/gnu/store} files and
sub-directories. This is the default operation when no option is
When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
When @var{min} is omitted, collect all the garbage.
@item --free-space=@var{free}
@itemx -F @var{free}
Collect garbage until @var{free} space is available under
@file{/gnu/store}, if possible; @var{free} denotes storage space, such
as @code{500MiB}, as described above.
When @var{free} or more is already available in @file{/gnu/store}, do
nothing and exit immediately.
@item --delete
@itemx -d
Attempt to delete all the store files and directories specified as
arguments. This fails if some of the files are not in the store, or if
they are still live.
@item --list-failures
List store items corresponding to cached build failures.
This prints nothing unless the daemon was started with
@option{--cache-failures} (@pxref{Invoking guix-daemon,
@item --clear-failures
Remove the specified store items from the failed-build cache.
Again, this option only makes sense when the daemon is started with
@option{--cache-failures}. Otherwise, it does nothing.
@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.
@item --list-live
Show the list of live store files and directories.
@end table
In addition, the references among existing store files can be queried:
@table @code
@item --references
@itemx --referrers
@cindex package dependencies
List the references (respectively, the referrers) of store files given
as arguments.
@item --requisites
@itemx -R
@cindex closure
List the requisites of the store files passed as arguments. Requisites
include the store files themselves, their references, and the references
of these, recursively. In other words, the returned list is the
@dfn{transitive closure} of the store files.
@xref{Invoking guix size}, for a tool to profile the size of the closure
of an element. @xref{Invoking guix graph}, for a tool to visualize
the graph of references.
@item --derivers
@cindex derivation
Return the derivation(s) leading to the given store items
For example, this command:
guix gc --derivers `guix package -I ^emacs$ | cut -f4`
@end example
returns the @file{.drv} file(s) leading to the @code{emacs} package
installed in your profile.
Note that there may be zero matching @file{.drv} files, for instance
because these files have been garbage-collected. There can also be more
than one matching @file{.drv} due to fixed-output derivations.
@end table
Lastly, the following options allow you to check the integrity of the
store and to control disk usage.
@table @option
@item --verify[=@var{options}]
@cindex integrity, of the store
@cindex integrity checking
Verify the integrity of the store.
By default, make sure that all the store items marked as valid in the
database of the daemon actually exist in @file{/gnu/store}.
When provided, @var{options} must be a comma-separated list containing one
or more of @code{contents} and @code{repair}.
When passing @option{--verify=contents}, the daemon computes the
content hash of each store item and compares it against its hash in the
database. Hash mismatches are reported as data corruptions. Because it
traverses @emph{all the files in the store}, this command can take a
long time, especially on systems with a slow disk drive.
@cindex repairing the store
@cindex corruption, recovering from
Using @option{--verify=repair} or @option{--verify=contents,repair}
causes the daemon to try to repair corrupt store items by fetching
substitutes for them (@pxref{Substitutes}). Because repairing is not
atomic, and thus potentially dangerous, it is available only to the
system administrator. A lightweight alternative, when you know exactly
which items in the store are corrupt, is @command{guix build --repair}
(@pxref{Invoking guix build}).
@item --optimize
@cindex deduplication
Optimize the store by hard-linking identical files---this is
The daemon performs deduplication after each successful build or archive
import, unless it was started with @code{--disable-deduplication}
(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
this option is primarily useful when the daemon was running with
@end table
@node Invoking guix pull
@section Invoking @command{guix pull}
@cindex upgrading Guix
@cindex updating Guix
@cindex @command{guix pull}
@cindex pull
Packages are installed or upgraded to the latest version available in
the distribution currently available on your local machine. To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
descriptions, and deploys it. Source code is downloaded from a
@uref{https://git-scm.com, Git} repository, by default the official
GNU@tie{}Guix repository, though this can be customized.
On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix. Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
version. New @command{guix} sub-commands added by the update also
become available.
Any user can update their Guix copy using @command{guix pull}, and the
effect is limited to the user who run @command{guix pull}. For
instance, when user @code{root} runs @command{guix pull}, this has no
effect on the version of Guix that user @code{alice} sees, and vice
The result of running @command{guix pull} is a @dfn{profile} available
under @file{~/.config/guix/current} containing the latest Guix. Thus,
make sure to add it to the beginning of your search path so that you use
the latest version, and similarly for the Info manual
export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
@end example
The @code{--list-generations} or @code{-l} option lists past generations
produced by @command{guix pull}, along with details about their provenance:
$ guix pull -l
Generation 1 Jun 10 2018 00:18:18
guix 65956ad
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: origin/master
commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
Generation 2 Jun 11 2018 11:02:49
guix e0cc7f6
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: origin/master
commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
2 new packages: keepalived, libnfnetlink
6 packages upgraded: emacs-nix-mode@@2.0.4,
guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
Generation 3 Jun 13 2018 23:31:07 (current)
guix 844cc1c
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: origin/master
commit: 844cc1c8f394f03b404c5bb3aee086922373490c
28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
@end example
@ref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.
This @code{~/.config/guix/current} profile works like any other profile
created by @command{guix package} (@pxref{Invoking guix package}). That
is, you can list generations, roll back to the previous
generation---i.e., the previous Guix---and so on:
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
Download code from the specified @var{url}, at the given @var{commit} (a valid
Git commit ID represented as a hexadecimal string), or @var{branch}.
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
These options are provided for convenience, but you can also specify your
configuration in the @file{~/.config/guix/channels.scm} file or using the
@option{--channels} option (see below).
@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file} instead of
@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
evaluates to a list of channel objects. @xref{Channels}, for more
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
is provided, the subset of generations that match @var{pattern}.
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).
@ref{Invoking guix describe}, for a way to display information about the
current generation only.
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of @file{~/.config/guix/current}.
@item --dry-run
@itemx -n
Show which channel commit(s) would be used and what would be built or
substituted but do not actually do it.
@item --verbose
Produce verbose output, writing build logs to the standard error output.
@item --bootstrap
Use the bootstrap Guile to build the latest Guix. This option is only
useful to Guix developers.
@end table
The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
repository and branch to pull from, as well as @emph{additional} repositories
containing package modules that should be deployed. @xref{Channels}, for more
In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).
@node Channels
@section Channels
@cindex channels
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
@cindex @command{guix pull}, configuration file
@cindex configuration of @command{guix pull}
Guix and its package collection are updated by running @command{guix pull}
(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
deploys Guix itself from the official GNU@tie{}Guix repository. This can be
customized by defining @dfn{channels} in the
@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
of a Git repository to be deployed, and @command{guix pull} can be instructed
to pull from one or more channels. In other words, channels can be used to
@emph{customize} and to @emph{extend} Guix, as we will see below.
@subsection Using a Custom Guix Channel
The channel called @code{guix} specifies where Guix itself---its command-line
tools as well as its package collection---should be downloaded. For instance,
suppose you want to update from your own copy of the Guix repository at
@code{example.org}, and specifically the @code{super-hacks} branch, you can
write in @code{~/.config/guix/channels.scm} this specification:
;; Tell 'guix pull' to use my own repo.
(list (channel
(name 'guix)
(url "https://example.org/my-guix.git")
(branch "super-hacks")))
@end lisp
From there on, @command{guix pull} will fetch code from the @code{super-hacks}
branch of the repository at @code{example.org}.
@subsection Specifying Additional Channels
@cindex extending the package collection (channels)
@cindex personal packages (channels)
@cindex channels, for personal packages
You can also specify @emph{additional channels} to pull from. Let's say you
have a bunch of custom package variants or personal packages that you think
would make little sense to contribute to the Guix project, but would like to
have these packages transparently available to you at the command line. You
would first write modules containing those package definitions (@pxref{Package
Modules}), maintain them in a Git repository, and then you and anyone else can
use it as an additional channel to get packages from. Neat, no?
@c What follows stems from discussions at
@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
@c earlier discussions on guix-devel@gnu.org.
@quotation Warning
Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
publish your personal channel to the world, we would like to share a few words
of caution:
Before publishing a channel, please consider contributing your package
definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
to free software of all sorts, and packages in Guix proper are readily
available to all Guix users and benefit from the project's quality assurance
When you maintain package definitions outside Guix, we, Guix developers,
consider that @emph{the compatibility burden is on you}. Remember that
package modules and package definitions are just Scheme code that uses various
programming interfaces (APIs). We want to remain free to change these APIs to
keep improving Guix, possibly in ways that break your channel. We never
change APIs gratuitously, but we will @emph{not} commit to freezing APIs
Corollary: if you're using an external channel and that channel breaks, please
@emph{report the issue to the channel authors}, not to the Guix project.
@end itemize
You've been warned! Having said this, we believe external channels are a
practical way to exert your freedom to augment Guix' package collection and to
share your improvements, which are basic tenets of
@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
@end quotation
Once you have a Git repository containing your own package modules, you can
write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
pull from your personal channel @emph{in addition} to the default Guix
@vindex %default-channels
;; Add my personal packages to those Guix provides.
(cons (channel
(name 'my-personal-packages)
(url "https://example.org/personal-packages.git"))
@end lisp
Note that the snippet above is (as always!) Scheme code; we use @code{cons} to
add a channel the list of channels that the variable @code{%default-channels}
is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
Manual}). With this file in place, @command{guix pull} builds not only Guix
but also the package modules from your own repository. The result in
@file{~/.config/guix/current} is the union of Guix with your own package
$ guix pull --list-generations
Generation 19 Aug 27 2018 16:20:48
guix d894ab8
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: master
commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
my-personal-packages dd3df5e
repository URL: https://example.org/personal-packages.git
branch: master
commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example
The output of @command{guix pull} above shows that Generation@tie{}19 includes
both Guix and packages from the @code{my-personal-packages} channel. Among
the new and upgraded packages that are listed, some like @code{my-gimp} and
@code{my-emacs-with-cool-features} might come from
@code{my-personal-packages}, while others come from the Guix default channel.
@subsection Replicating Guix
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
The @command{guix pull --list-generations} output above shows precisely which
commits were used to build this instance of Guix. We can thus replicate it,
say, on another machine, by providing a channel specification in
@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
;; Deploy specific commits of my channels of interest.
(list (channel
(name 'guix)
(url "https://git.savannah.gnu.org/git/guix.git")
(commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
(name 'my-personal-packages)
(url "https://example.org/personal-packages.git")
(branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
The @command{guix describe --format=channels} command can even generate this
list of channels directly (@pxref{Invoking guix describe}).
At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}. The output of @command{guix build gimp} on
one machine will be exactly the same, bit for bit, as the output of the same
command on the other machine. It also means both machines have access to all
the source code of Guix and, transitively, to all the source code of every
package it defines.
This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.
@node Inferiors
@section Inferiors
@c TODO: Remove this once we're more confident about API stability.
@quotation Note
The functionality described here is a ``technology preview'' as of version
@value{VERSION}. As such, the interface is subject to change.
@end quotation
@cindex inferiors
@cindex composition of Guix revisions
Sometimes you might need to mix packages from the revision of Guix you're
currently running with packages available in a different revision of Guix.
Guix @dfn{inferiors} allow you to achieve that by composing different Guix
revisions in arbitrary ways.
@cindex inferior packages
Technically, an ``inferior'' is essentially a separate Guix process connected
to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
@code{(guix inferior)} module allows you to create inferiors and to
communicate with them. It also provides a high-level interface to browse and
manipulate the packages that an inferior provides---@dfn{inferior packages}.
When combined with channels (@pxref{Channels}), inferiors provide a simple way
to interact with a separate revision of Guix. For example, let's assume you
want to install in your profile the current @code{guile} package, along with
the @code{guile-json} as it existed in an older revision of Guix---perhaps
because the newer @code{guile-json} has an incompatible API and you want to
run your code against the old API@. To do that, you could write a manifest for
use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
manifest, you would create an inferior for that old Guix revision you care
about, and you would look up the @code{guile-json} package in the inferior:
(use-modules (guix inferior) (guix channels)
(srfi srfi-1)) ;for 'first'
(define channels
;; This is the old revision from which we want to
;; extract guile-json.
(list (channel
(name 'guix)
(url "https://git.savannah.gnu.org/git/guix.git")
(define inferior
;; An inferior representing the above revision.
(inferior-for-channels channels))
;; Now create a manifest with the current "guile" package
;; and the old "guile-json" package.
(list (first (lookup-inferior-packages inferior "guile-json"))
(specification->package "guile")))
@end lisp
On its first run, @command{guix package --manifest} might have to build the
channel you specified before it can create the inferior; subsequent runs will
be much faster because the Guix revision will be cached.
The @code{(guix inferior)} module provides the following procedures to open an
@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
[#:cache-directory] [#:ttl]
Return an inferior for @var{channels}, a list of channels. Use the cache at
@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
This procedure opens a new connection to the build daemon.
As a side effect, this procedure may build or substitute binaries for
@var{channels}, which can take time.
@end deffn
@deffn {Scheme Procedure} open-inferior @var{directory} @
[#:command "bin/guix"]
Open the inferior Guix in @var{directory}, running
@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
the inferior could not be launched.
@end deffn
@cindex inferior packages
The procedures listed below allow you to obtain and manipulate inferior
@deffn {Scheme Procedure} inferior-packages @var{inferior}
Return the list of packages known to @var{inferior}.
@end deffn
@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
Return the sorted list of inferior packages matching @var{name} in
@var{inferior}, with highest version numbers first. If @var{version} is true,
return only packages with a version number prefixed by @var{version}.
@end deffn
@deffn {Scheme Procedure} inferior-package? @var{obj}
Return true if @var{obj} is an inferior package.
@end deffn
@deffn {Scheme Procedure} inferior-package-name @var{package}
@deffnx {Scheme Procedure} inferior-package-version @var{package}
@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
@deffnx {Scheme Procedure} inferior-package-description @var{package}
@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
@deffnx {Scheme Procedure} inferior-package-location @var{package}
@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
These procedures are the counterpart of package record accessors
(@pxref{package Reference}). Most of them work by querying the inferior
@var{package} comes from, so the inferior must still be live when you call
these procedures.
@end deffn
Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}). They are also
transparently handled by the @code{packages->manifest} procedure, which is
commonly use in manifests (@pxref{Invoking guix package, the
@option{--manifest} option of @command{guix package}}). Thus you can insert
an inferior package pretty much anywhere you would insert a regular package:
in manifests, in the @code{packages} field of your @code{operating-system}
declaration, and so on.
@node Invoking guix describe
@section Invoking @command{guix describe}
@cindex reproducibility
@cindex replicating Guix
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?'' This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
machine or user account, if you want to report a bug or to determine what
change in the channels you are using caused it, or if you want to record your
system state for reproducibility purposes. The @command{guix describe}
command answers these questions.
When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
displays the channel(s) that it was built from, including their repository URL
and commit IDs (@pxref{Channels}):
$ guix describe
Generation 10 Sep 03 2018 17:32:44 (current)
guix e0fa68c
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: master
commit: e0fa68c7718fffd33d81af415279d6ddb518f727
@end example
If you're familiar with the Git version control system, this is similar in
spirit to @command{git describe}; the output is also similar to that of
@command{guix pull --list-generations}, but limited to the current generation
(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
information is all it takes to describe the revision of Guix you're using, and
also to replicate it.
To make it easier to replicate Guix, @command{guix describe} can also be asked
to return a list of channels instead of the human-readable description above:
$ guix describe -f channels
(list (channel
(name 'guix)
(url "https://git.savannah.gnu.org/git/guix.git")
@end example
You can save this to a file and feed it to @command{guix pull -C} on some
other machine or at a later point in time, which will instantiate @emph{this
exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
From there on, since you're able to deploy the same revision of Guix, you can
just as well @emph{replicate a complete software environment}. We humbly
think that this is @emph{awesome}, and we hope you'll like it too!
The details of the options supported by @command{guix describe} are as
@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce output in the specified @var{format}, one of:
@table @code
@item human
produce human-readable output;
@item channels
produce a list of channel specifications that can be passed to @command{guix
pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
guix pull});
@item json
@cindex JSON
produce a list of channel specifications in JSON format;
@item recutils
produce a list of channel specifications in Recutils format.
@end table
@item --profile=@var{profile}
@itemx -p @var{profile}
Display information about @var{profile}.
@end table
@node Invoking guix pack
@section Invoking @command{guix pack}
Occasionally you want to pass software to people who are not (yet!)
lucky enough to be using Guix. You'd tell them to run @command{guix
package -i @var{something}}, but that's not possible in this case. This
is where @command{guix pack} comes in.
@quotation Note
If you are looking for ways to exchange binaries among machines that
already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
publish}, and @ref{Invoking guix archive}.
@end quotation
@cindex pack
@cindex bundle
@cindex application bundle
@cindex software bundle
The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
@dfn{software bundle}: it creates a tarball or some other archive
containing the binaries of the software you're interested in, and all
its dependencies. The resulting archive can be used on any machine that
does not have Guix, and people can run the exact same binaries as those
you have with Guix. The pack itself is created in a bit-reproducible
fashion, so anyone can verify that it really contains the build results
that you pretend to be shipping.
For example, to create a bundle containing Guile, Emacs, Geiser, and all
their dependencies, you can run:
$ guix pack guile emacs geiser
@end example
The result here is a tarball containing a @file{/gnu/store} directory
with all the relevant packages. The resulting tarball contains a
@dfn{profile} with the three packages of interest; the profile is the
same as would be created by @command{guix package -i}. It is this
mechanism that is used to create Guix's own standalone binary tarball
(@pxref{Binary Installation}).
Users of this pack would have to run
@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
find inconvenient. To work around it, you can create, say, a
@file{/opt/gnu/bin} symlink to the profile:
guix pack -S /opt/gnu/bin=bin guile emacs geiser
@end example
That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
@cindex relocatable binaries, with @command{guix pack}
What if the recipient of your pack does not have root privileges on
their machine, and thus cannot unpack it in the root file system? In
that case, you will want to use the @code{--relocatable} option (see
below). This option produces @dfn{relocatable binaries}, meaning they
they can be placed anywhere in the file system hierarchy: in the example
above, users can unpack your tarball in their home directory and
directly run @file{./opt/gnu/bin/guile}.
@cindex Docker, build an image with guix pack
Alternatively, you can produce a pack in the Docker image format using
the following command:
guix pack -f docker guile emacs geiser
@end example
The result is a tarball that can be passed to the @command{docker load}
command. See the
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
@cindex Singularity, build an image with guix pack
@cindex SquashFS, build an image with guix pack
Yet another option is to produce a SquashFS image with the following
guix pack -f squashfs guile emacs geiser
@end example
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
@uref{http://singularity.lbl.gov, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
Several command-line options allow you to customize your pack:
@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce a pack in the given @var{format}.
The available formats are:
@table @code
@item tarball
This is the default format. It produces a tarball containing all the
specified binaries and symlinks.
@item docker
This produces a tarball that follows the
Docker Image Specification}.
@item squashfs
This produces a SquashFS image containing all the specified binaries and
symlinks, as well as empty mount points for virtual file systems like
@end table
@item --relocatable
@itemx -R
Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
anywhere in the file system hierarchy and run from there. For example,
if you create a pack containing Bash with:
guix pack -R -S /mybin=bin bash
@end example
... you can copy that pack to a machine that lacks Guix, and from your
home directory as a normal user, run:
tar xf pack.tar.gz
@end example
In that shell, if you type @code{ls /gnu/store}, you'll notice that
@file{/gnu/store} shows up and contains all the dependencies of
@code{bash}, even though the machine actually lacks @file{/gnu/store}
altogether! That is probably the simplest way to deploy Guix-built
software on a non-Guix machine.
There's a gotcha though: this technique relies on the @dfn{user
namespace} feature of the kernel Linux, which allows unprivileged users
to mount or change root. Old versions of Linux did not support it, and
some GNU/Linux distributions turn it off; on these systems, programs
from the pack @emph{will fail to run}, unless they are unpacked in the
root file system.
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
This has the same purpose as the same-named option in @command{guix
build} (@pxref{Additional Build Options, @code{--expression} in
@command{guix build}}).
@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
code in @var{file}.
This has a similar purpose as the same-named option in @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
same manifest files. It allows you to define a collection of packages
once and use it both for creating profiles and for creating archives
for use on machines that do not have Guix installed. Note that you can
specify @emph{either} a manifest file @emph{or} a list of packages,
but not both.
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the system type of the build host.
@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
configuration triplets,, autoconf, Autoconf}).
@item --compression=@var{tool}
@itemx -C @var{tool}
Compress the resulting tarball using @var{tool}---one of @code{gzip},
@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
@item --symlink=@var{spec}
@itemx -S @var{spec}
Add the symlinks specified by @var{spec} to the pack. This option can
appear several times.
@var{spec} has the form @code{@var{source}=@var{target}}, where
@var{source} is the symlink that will be created and @var{target} is the
symlink target.
For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
symlink pointing to the @file{bin} sub-directory of the profile.
@item --localstatedir
@itemx --profile-name=@var{name}
Include the ``local state directory'', @file{/var/guix}, in the resulting
pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
profile---by default @var{name} is @code{guix-profile}, which corresponds to
@file{/var/guix} contains the store database (@pxref{The Store}) as well
as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
the pack means that the store is ``complete'' and manageable by Guix;
not providing it pack means that the store is ``dead'': items cannot be
added to it or removed from it after extraction of the pack.
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
@item --bootstrap
Use the bootstrap binaries to build the pack. This option is only
useful to Guix developers.
@end table
In addition, @command{guix pack} supports all the common build options
(@pxref{Common Build Options}) and all the package transformation
options (@pxref{Package Transformation Options}).
@node Invoking guix archive
@section Invoking @command{guix archive}
@cindex @command{guix archive}
@cindex 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 on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.
@quotation Note
If you're looking for a way to produce archives in a format suitable for
tools other than Guix, @pxref{Invoking guix pack}.
@end quotation
@cindex exporting store items
To export store files as an archive to standard output, run:
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}:
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
common build options (@pxref{Common Build Options}).
To transfer the @code{emacs} package to a machine connected over SSH,
one would run:
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example