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.
 
 
 
 
 
 

22848 lines
826 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 OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@copying
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 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017, 2018 Clément Lassieur@*
Copyright @copyright{} 2017 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
Copyright @copyright{} 2017 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
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
@direntry
* 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
@direntry
* 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
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author The GNU Guix Developers
@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*
@insertcopying
@end titlepage
@contents
@c *********************************************************************
@node Top
@top GNU Guix
This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* 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.
@detailmenu
--- The Detailed Node Listing ---
Installation
* 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.
* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
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?
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.
Defining Packages
* package Reference :: The package data type.
* origin Reference:: The origin data type.
Utilities
* 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 @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.
Services
* 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:: The TLP tool.
* 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.
Contributing
* 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
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
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
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}).
@menu
* 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
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
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
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:
@enumerate
@item
@cindex downloading Guix binary
Download the binary tarball from
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
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:
@example
$ wget ftp://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:
@example
$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
@noindent
and rerun the @code{gpg --verify} command.
@c end authentication part
@item
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:
@example
# cd /tmp
# tar --warning=no-timestamp -xf \
guix-binary-@value{VERSION}.@var{system}.tar.xz
# 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
step.)
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
reproducible.
@item
Make @code{root}'s profile available under @file{~root/.guix-profile}:
@example
# ln -sf /var/guix/profiles/per-user/root/guix-profile \
~root/.guix-profile
@end example
Source @file{etc/profile} to augment @code{PATH} and other relevant
environment variables:
@example
# GUIX_PROFILE="`echo ~root`/.guix-profile" ; \
source $GUIX_PROFILE/etc/profile
@end example
@item
Create the group and user accounts for build users as explained below
(@pxref{Build Environment Setup}).
@item
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
@c See this thread for more information:
@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
@example
# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
# systemctl start guix-daemon && systemctl enable guix-daemon
@end example
If your host distro uses the Upstart init system:
@example
# initctl reload-configuration
# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
# start guix-daemon
@end example
Otherwise, you can still start the daemon manually with:
@example
# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@end example
@item
Make the @command{guix} command available to other users on the machine,
for instance with:
@example
# mkdir -p /usr/local/bin
# cd /usr/local/bin
# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
@end example
It is also a good idea to make the Info version of this manual available
there:
@example
# mkdir -p /usr/local/share/info
# cd /usr/local/share/info
# for i in /var/guix/profiles/per-user/root/guix-profile/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.)
@item
@cindex substitutes, authorization thereof
To use substitutes from @code{hydra.gnu.org} or one of its mirrors
(@pxref{Substitutes}), authorize them:
@example
# guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
@end example
@item
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:
@example
# 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:
@example
make guix-binary.@var{system}.tar.xz
@end example
@noindent
... which, in turn, runs:
@example
guix pack -s @var{system} --localstatedir 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:
@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or
later, including 2.2.x;
@item @url{http://gnupg.org/, GNU libgcrypt};
@item
@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
@item
@c FIXME: Specify a version number once a release has been made.
@uref{https://notabug.org/civodul/guile-sqlite3, Guile-SQLite3};
@item
@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:
@itemize
@item
Installing
@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.
@item
@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.
@item
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:
@itemize
@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:
@example
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
cache.
It is also possible to run a subset of the tests by defining the
@code{TESTS} makefile variable as in this example:
@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:
@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:
@example
make check-system
@end example
@noindent
or, again, by defining @code{TESTS} to select a subset of tests to run:
@example
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.
@menu
* 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.
@example
# groupadd --system guixbuild
# for i in `seq -w 1 10`;
do
useradd -g guixbuild -G guixbuild \
-d /var/empty -s `which nologin` \
-c "Guix build user $i" --system \
guixbuilder$i;
done
@end example
@noindent
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{@var{prefix}/lib/upstart/system/guix-daemon.conf}
file in @file{/etc/init}.}:
@example
# guix-daemon --build-users-group=guixbuild
@end example
@cindex chroot
@noindent
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! -----------------------
@itemize
@item
a minimal @code{/dev} directory, created mostly independently from the
host @code{/dev}@footnote{``Mostly'', because while the set of files
that appear in the chroot's @code{/dev} is fixed, most of these files
can only be created if the host has them.};
@item
the @code{/proc} directory; it only shows the processes of the container
since a separate PID name space is used;
@item
@file{/etc/passwd} with an entry for the current user and an entry for
user @file{nobody};
@item
@file{/etc/group} with an entry for the user's group;
@item
@file{/etc/hosts} with an entry that maps @code{localhost} to
@code{127.0.0.1};
@item
a writable @file{/tmp} directory.
@end itemize
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:
@example
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
(host-key "ssh-ed25519 AAAAC3Nza@dots{}")
(user "bob")
(speed 2.)) ;incredibly fast!
(build-machine
(name "meeps.example.org")
(system "mips64el-linux")
(host-key "ssh-rsa AAAAB3Nza@dots{}")
(user "alice")
(private-key
(string-append (getenv "HOME")
"/.ssh/identity-for-guix"))))
@end example
@noindent
In the example above we specify a list of two build machines, one for
the @code{x86_64} architecture and one for the @code{mips64el}
architecture.
In fact, this file is---not surprisingly!---a Scheme file that is
evaluated when the @code{offload} hook is started. Its return value
must be a list of @code{build-machine} objects. While this example
shows a fixed list of build machines, one could imagine, say, using
DNS-SD to return a list of potential build machines discovered in the
local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
Avahi in Guile Scheme Programs}). The @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:
@example
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
@file{/etc/ssh/ssh_host_ed25519_key.pub}.
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}):
@example
$ 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.
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:
@example
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}):
@example
# guix archive --generate-key
@end example
@noindent
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:
@example
# guix archive --authorize < master-public-key.txt
@end example
@noindent
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:
@example
# 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:
@example
# 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:
@example
# 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:
@example
# 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:
@example
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
command:
@example
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
operations.
@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.
@enumerate
@item
@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.
@item
@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.
@item
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.
@item
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:
@example
# guix-daemon --build-users-group=guixbuild
@end example
@noindent
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. Be aware that using a
directory other than @file{/tmp} can affect build results---for example,
with a longer directory name, a build process that uses Unix-domain
sockets might hit the name length limitation for @code{sun_path}, which
it would otherwise not hit.
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 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
(@pxref{Substitutes}).
When the daemon runs with @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-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
needs.
@item --disable-chroot
Disable chroot builds.
Using this option is not recommended since, again, it would allow build
processes to gain access to undeclared dependencies. It is necessary,
though, when @command{guix-daemon} is running under an unprivileged user
account.
@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
derivations.
@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 GC roots.
@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.
Note that when both @code{--gc-keep-derivations} and
@code{--gc-keep-outputs} are used, the effect is to keep all the build
prerequisites (the sources, compiler, libraries, and other build-time
tools) of live objects in the store, regardless of whether these
prerequisites are live. This is convenient for developers since it
saves rebuilds or downloads.
@item --impersonate-linux-2.6
On Linux-based systems, impersonate Linux 2.6. This means that the
kernel's @code{uname} system call will report 2.6 as the release number.
This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.
@item --lose-logs
Do not keep build logs. By default they are kept under
@code{@var{localstatedir}/guix/log}.
@item --system=@var{system}
Assume @var{system} as the current system type. By default it is the
architecture/kernel pair found at configure time, such as
@code{x86_64-linux}.
@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=128.0.0.42:1234
Listen for TCP connections on the network interface corresponding to
@code{128.0.0.42}, 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
@file{@var{localstatedir}/guix/daemon-socket/socket}.
@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
@anchor{locales-and-locpath}
@cindex locales, when not on GuixSD
@vindex LOCPATH
@vindex GUIX_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
variable:
@example
$ 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:
@enumerate
@item
@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.
@item
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
themselves.
@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
@code{font-gnu-freefont-ttf}.
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:
@example
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:
@example
-*-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>.
@example
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
information.
@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
wrapper.
@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
@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.
@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
features.
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):
@example
guix package -i emacs-guix
@end example
@menu
* 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.
* 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
@code{$HOME/.guix-profile}.
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
collected.
@cindex reproducibility
@cindex reproducible builds
Finally, Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
Each @file{/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}).
@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
is:
@example
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:
@example
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:
@example
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
package}.
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).
@anchor{package-cmd-propagated-inputs}
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}):
@example
@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
@code{glibc}.
@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
pull}).
@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'':
@example
$ 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
@example
(use-package-modules guile emacs)
(packages->manifest
(list emacs
guile-2.0
;; 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:
@example
(specifications->manifest
'("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
@code{--switch-generation=+1}.
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
shell:
@example
$ 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:
@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:
@example
$ 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:
@example
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils
name: gmp
@dots{}
@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
games:
@example
$ guix package -s '\<board\>' -s game | recsel -p name
name: gnubg
@dots{}
@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
keyboards.
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:
@example
$ guix package -s crypto -s library | \
recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example
@noindent
@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}).
@example
$ 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:
@example
$ 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
shown.
For each installed package, print the following items, separated by
tabs: the name of a package, its version string, the part of the package
that is installed (@pxref{Packages with Multiple Outputs}), and the
location of this package in the store.
When @var{pattern} is used, the command returns only matching
generations. Valid patterns include:
@itemize
@item @emph{Integers and comma-separated integers}. Both patterns denote
generation numbers. For instance, @code{--list-generations=1} returns
the first one.
And @code{--list-generations=1,8,2} outputs three generations in the
specified order. Neither spaces nor trailing commas are allowed.
@item @emph{Ranges}. @code{--list-generations=2..9} prints the
specified generations and everything in between. Note that the start of
a range must be 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
one.
This command accepts the same patterns as @option{--list-generations}.
When @var{pattern} is specified, delete the matching generations. When
@var{pattern} specifies a duration, generations @emph{older} than the
specified duration match. For instance, @code{--delete-generations=1m}
deletes generations that are more than one month old.
If the current generation matches, it is @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.
@menu
* 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}
option}).
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:
@example
# 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
@indicateurl{https://berlin.guixsd.org}.
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:
@example
$ guix build emacs --dry-run
The following derivations would be built:
/gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
/gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
/gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
/gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
@dots{}
@end example
@noindent
to something like:
@example
$ guix build emacs --dry-run
112.3 MB would be downloaded:
/gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
/gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
/gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
/gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
@dots{}
@end example
@noindent
This indicates that substitutes from @code{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.
@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:
@example
--substitute-urls="https://a.example.org https://b.example.org"
@end example
@noindent
@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
below).
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,
etc.
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
files.
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:
@example
guix package -i glib
@end example
@cindex documentation
The command to install its documentation is:
@example
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:
@example
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
specified.
When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
(@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,
@option{--cache-failures}}).
@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
(@pxref{Derivations}).
For example, this command:
@example
guix gc --derivers `guix package -I ^emacs$ | cut -f4`
@end example
@noindent
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
@dfn{deduplication}.
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
@code{--disable-deduplication}.
@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.
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
versa.
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
(@pxref{Documentation}):
@example
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:
@example
$ 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
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
@end example
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:
@example
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /home/charlie/.config/guix/current-1-link
@end example
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
@table @code
@item --verbose
Produce verbose output, writing build logs to the standard error output.
@item --url=@var{url}
Download Guix from the Git repository at @var{url}.
@vindex GUIX_PULL_URL
By default, the source is taken from its canonical Git repository at
@code{gnu.org}, for the stable branch of Guix. To use a different source,
set the @code{GUIX_PULL_URL} environment variable.
@item --commit=@var{commit}
Deploy @var{commit}, a valid Git commit ID represented as a hexadecimal
string.
@item --branch=@var{branch}
Deploy the tip of @var{branch}, the name of a Git branch available on
the repository at @var{url}.
@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}).
@item --bootstrap
Use the bootstrap Guile to build the latest Guix. This option is only
useful to Guix developers.
@end table
In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).
@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:
@example
$ guix pack guile emacs geiser
@dots{}
/gnu/store/@dots{}-pack.tar.gz
@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:
@example
guix pack -S /opt/gnu/bin=bin guile emacs geiser
@end example
@noindent
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:
@example
guix pack -f docker guile emacs geiser
@end example
@noindent
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
command:
@example
guix pack -f squashfs guile emacs geiser
@end example
@noindent
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
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
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
procfs.
@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:
@example
guix pack -R -S /mybin=bin bash
@end example
@noindent
... you can copy that pack to a machine that lacks Guix, and from your
home directory as a normal user, run:
@example
tar xf pack.tar.gz
./mybin/sh
@end example
@noindent
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
Include the ``local state directory'', @file{/var/guix}, in the
resulting pack.
@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:
@example
guix archive --export @var{options} @var{specifications}...
@end example
@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}). For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:
@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example
If the specified packages are not built yet, @command{guix archive}
automatically builds them. The build process may be controlled with the
common build options (@pxref{Common Build Options}).
To transfer the @code{emacs} package to a machine connected over SSH,
one would run:
@example
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example
@noindent
Similarly, a complete user profile may be transferred from one machine
to another like this:
@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
ssh the-machine guix-archive --import
@end example
@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the store on the
target machine. The @code{--missing} option can help figure out which
items are missing from the target store. The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).
@cindex nar, archive format
@cindex normalized archive (nar)
Archives are stored in the ``normalized archive'' or ``nar'' format, which is
comparable in spirit to `tar', but with differences
that make it more appropriate for our purposes. First, rather than
recording all Unix metadata for each file, the nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed. Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order. This makes archive production fully
deterministic.
When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended. When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.
The main options are:
@table @code
@item --export
Export the specified store files or packages (see below.) Write the
resulting archive to the standard output.
Dependencies are @emph{not} included in the output, unless
@code{--recursive} is passed.
@item -r
@itemx --recursive
When combined with @code{--export}, this instructs @command{guix
archive} to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.
@item --import
Read an archive from the standard input, and import the files listed
therein into the store. Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
keys (see @code{--authorize} below.)
@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.
@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemon. This is a prerequisite before
archives can be exported with @code{--export}. Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.
The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret.) When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).
@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.
The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}. The file contains
@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@item --extract=@var{directory}
@itemx -x @var{directory}
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and extract it to @var{directory}. This is a
low-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs
served by @code{hydra.gnu.org} to @file{/tmp/emacs}:
@example
$ wget -O - \
https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
| bunzip2 | guix archive -x /tmp/emacs
@end example
Single-item archives are different from multiple-item archives produced
by @command{guix archive --export}; they contain a single store item,
and they do @emph{not} embed a signature. Thus this operation does
@emph{no} signature verification and its output should be considered
unsafe.
The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers.
@end table
@c *********************************************************************
@node Programming Interface
@chapter Programming Interface
GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages. The first interface allows users to
write high-level package definitions. These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies. These definitions can then be
turned into concrete build actions.
Build actions are performed by the Guix daemon, on behalf of users. In a
standard setup, the daemon has write access to the store---the
@file{/gnu/store} directory---whereas users do not. The recommended
setup also has the daemon perform builds in chroots, under a specific
build users, to minimize interference with the rest of the system.
@cindex derivation
Lower-level APIs are available to interact with the daemon and the
store. To instruct the daemon to perform a build action, users actually
provide it with a @dfn{derivation}. A derivation is a low-level
representation of the build actions to be taken, and the environment in
which they should occur---derivations are to package definitions what
assembly is to C programs. The term ``derivation'' comes from the fact
that build results @emph{derive} from them.
This chapter describes all these APIs in turn, starting from high-level
package definitions.
@menu
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
@end menu
@node Defining Packages
@section Defining Packages
The high-level interface to package definitions is implemented in the
@code{(guix packages)} and @code{(guix build-system)} modules. As an
example, the package definition, or @dfn{recipe}, for the GNU Hello
package looks like this:
@example
(define-module (gnu packages hello)
#:use-module (guix packages)
#:use-module (guix download)
#:use-module (guix build-system gnu)
#:use-module (guix licenses)
#:use-module (gnu packages gawk))
(define-public hello
(package
(name "hello")
(version "2.10")
(source (origin
(method url-fetch)
(uri (string-append "mirror://gnu/hello/hello-" version
".tar.gz"))
(sha256
(base32
"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system)
(arguments '(#:configure-flags '("--enable-silent-rules")))
(inputs `(("gawk" ,gawk)))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
(home-page "http://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here. This expression binds the variable
@code{hello} to a @code{<package>} object, which is essentially a record
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
This package object can be inspected using procedures found in the
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.
With luck, you may be able to import part or all of the definition of
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).
In the example above, @var{hello} is defined in a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
the command-line tools (@pxref{Package Modules}).
There are a few points worth noting in the above package definition:
@itemize
@item
The @code{source} field of the package is an @code{<origin>} object
(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.
The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
the GNU mirrors defined in @code{(guix download)}.
The @code{sha256} field specifies the expected SHA256 hash of the file
being downloaded. It is mandatory, and allows Guix to check the
integrity of the file. The @code{(base32 @dots{})} form introduces the
base32 representation of the hash. You can obtain this information with
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).
@cindex patches
When needed, the @code{origin} form can also have a @code{patches} field
listing patches to be applied, and a @code{snippet} field giving a
Scheme expression to modify the source code.
@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
package (@pxref{Build Systems}). Here, @var{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.
@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}). Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag.
@cindex quote
@cindex quoting
@findex '
@findex quote
What about these quote (@code{'}) characters? They are Scheme syntax to
introduce a literal list; @code{'} is synonymous with @code{quote}.
@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
for details. Here the value of the @code{arguments} field is a list of
arguments passed to the build system down the road, as with @code{apply}
(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
Manual}).
The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
@code{#:configure-flags} is a keyword used to pass a keyword argument
to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
Reference Manual}).
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package. Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk}
variable; @var{gawk} is itself bound to a @code{<package>} object.
@cindex backquote (quasiquote)
@findex `
@findex quasiquote
@cindex comma (unquote)
@findex ,
@findex unquote
@findex ,@@
@findex unquote-splicing
Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
us to introduce a literal list in the @code{inputs} field, while
@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
Reference Manual}).
Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here. Instead, @var{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).
However, any other dependencies need to be specified in the
@code{inputs} field. Any dependency not specified here will simply be
unavailable to the build process, possibly leading to a build failure.
@end itemize
@xref{package Reference}, for a full description of possible fields.
Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}), troubleshooting any build failures
you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
@vindex GUIX_PACKAGE_PATH
Lastly, @pxref{Package Modules}, for information
on how to extend the distribution by adding your own package definitions
to @code{GUIX_PACKAGE_PATH}.
Finally, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).
Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).
@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).
@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
@end deffn
@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:
@deffn {Scheme Procedure} package-cross-derivation @var{store} @
@var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn
@cindex package transformations
@cindex input rewriting
@cindex dependency tree rewriting
Packages can be manipulated in arbitrary ways. An example of a useful
transformation is @dfn{input rewriting}, whereby the dependency tree of
a package is rewritten by replacing specific inputs by others:
@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
[@var{rewrite-name}]
Return a procedure that, when passed a package, replaces its direct and
indirect dependencies (but not its implicit inputs) according to
@var{replacements}. @var{replacements} is a list of package pairs; the
first element of each pair is the package to replace, and the second one
is the replacement.
Optionally, @var{rewrite-name} is a one-argument procedure that takes
the name of a package and returns its new name after rewrite.
@end deffn
@noindent
Consider this example:
@example
(define libressl-instead-of-openssl
;; This is a procedure to replace OPENSSL by LIBRESSL,
;; recursively.
(package-input-rewriting `((,openssl . ,libressl))))
(define git-with-libressl
(libressl-instead-of-openssl git))
@end example
@noindent
Here we first define a rewriting procedure that replaces @var{openssl}
with @var{libressl}. Then we use it to define a @dfn{variant} of the
@var{git} package that uses @var{libressl} instead of @var{openssl}.
This is exactly what the @option{--with-input} command-line option does
(@pxref{Package Transformation Options, @option{--with-input}}).
A more generic procedure to rewrite a package dependency graph is
@code{package-mapping}: it supports arbitrary changes to nodes in the
graph.
@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
Return a procedure that, given a package, applies @var{proc} to all the packages
depended on and returns the resulting package. The procedure stops recursion
when @var{cut?} returns true for a given package.
@end deffn
@menu
* package Reference :: The package data type.
* origin Reference:: The origin data type.
@end menu
@node package Reference
@subsection @code{package} Reference
This section summarizes all the options available in @code{package}
declarations (@pxref{Defining Packages}).
@deftp {Data Type} package
This is the data type representing a package recipe.
@table @asis
@item @code{name}
The name of the package, as a string.
@item @code{version}
The version of the package, as a string.
@item @code{source}
An object telling how the source code for the package should be
acquired. Most of the time, this is an @code{origin} object, which
denotes a file fetched from the Internet (@pxref{origin Reference}). It
can also be any other ``file-like'' object such as a @code{local-file},
which denotes a file from the local file system (@pxref{G-Expressions,
@code{local-file}}).
@item @code{build-system}
The build system that should be used to build the package (@pxref{Build
Systems}).
@item @code{arguments} (default: @code{'()})
The arguments that should be passed to the build system. This is a
list, typically containing sequential keyword-value pairs.
@item @code{inputs} (default: @code{'()})
@itemx @code{native-inputs} (default: @code{'()})
@itemx @code{propagated-inputs} (default: @code{'()})
@cindex inputs, of packages
These fields list dependencies of the package. Each one is a list of
tuples, where each tuple has a label for the input (a string) as its
first element, a package, origin, or derivation as its second element,
and optionally the name of the output thereof that should be used, which
defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
more on package outputs). For example, the list below specifies three
inputs:
@example
`(("libffi" ,libffi)
("libunistring" ,libunistring)
("glib:bin" ,glib "bin")) ;the "bin" output of Glib
@end example
@cindex cross compilation, package dependencies
The distinction between @code{native-inputs} and @code{inputs} is
necessary when considering cross-compilation. When cross-compiling,
dependencies listed in @code{inputs} are built for the @emph{target}
architecture; conversely, dependencies listed in @code{native-inputs}
are built for the architecture of the @emph{build} machine.
@code{native-inputs} is typically used to list tools needed at
build time, but not at run time, such as Autoconf, Automake, pkg-config,
Gettext, or Bison. @command{guix lint} can report likely mistakes in
this area (@pxref{Invoking guix lint}).
@anchor{package-propagated-inputs}
Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
specified packages will be automatically installed alongside the package
they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
package}}, for information on how @command{guix package} deals with
propagated inputs.)
For example this is necessary when a C/C++ library needs headers of
another library to compile, or when a pkg-config file refers to another
one @i{via} its @code{Requires} field.
Another example where @code{propagated-inputs} is useful is for languages
that lack a facility to record the run-time search path akin to the
@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
more. To ensure that libraries written in those languages can find
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.
@item @code{self-native-input?} (default: @code{#f})
This is a Boolean field telling whether the package should use itself as
a native input when cross-compiling.
@item @code{outputs} (default: @code{'("out")})
The list of output names of the package. @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.
@item @code{native-search-paths} (default: @code{'()})
@itemx @code{search-paths} (default: @code{'()})
A list of @code{search-path-specification} objects describing
search-path environment variables honored by the package.
@item @code{replacement} (default: @code{#f})
This must be either @code{#f} or a package object that will be used as a
@dfn{replacement} for this package. @xref{Security Updates, grafts},
for details.
@item @code{synopsis}
A one-line description of the package.