guix.texi

\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
@set KEY-SERVER pool.sks-keyservers.net

@c The official substitute server used by default.
@set SUBSTITUTE-SERVER ci.guix.info

@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 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, 2019 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nils Gillmann@*
Copyright @copyright{} 2016, 2017, 2018 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017, 2018 Clément Lassieur@*
Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
Copyright @copyright{} 2017, 2018 Marius Bakke@*
Copyright @copyright{} 2017 Hartmut Goebel@*
Copyright @copyright{} 2017 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018 Gábor Boskovits@*
Copyright @copyright{} 2018 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory System administration
@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.

@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
zu GNU Guix}).  If you would like to translate it in your native language,
consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.

@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.
* 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.
* 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.
* Channels::                    Customizing the package collection.
* Inferiors::                   Interacting with another revision of Guix.
* Invoking guix describe::      Display information about your Guix revision.
* Invoking guix pack::          Creating software bundles.
* Invoking guix archive::       Exporting and importing store files.

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.
* Invoking guix repl::          Fiddling with Guix interactively.

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 guix processes::     Listing client processes.

Invoking @command{guix build}

* Common Build Options::        Build options for most commands.
* Package Transformation Options::  Creating variants of packages.
* Additional Build Options::    Options specific to 'guix build'.
* Debugging Build Failures::    Real life packaging experience.

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::   Extending battery life.
* Audio Services::              The MPD.
* Virtualization Services::     Virtualization services.
* Version Control Services::    Providing remote access to Git repositories.
* Game Services::               Game servers.
* Miscellaneous Services::      Other services.

Defining Services

* Service Composition::         The model for composing services.
* Service Types and Services::  Types and services.
* Service Reference::           API reference.
* Shepherd Services::           A particular type of service.

Packaging Guidelines

* Software Freedom::            What may go into the distribution.
* Package Naming::              What's in a name?
* Version Numbers::             When the name is not enough.
* Synopses and Descriptions::   Helping users find the right package.
* Python Modules::              A touch of British comedy.
* Perl Modules::                Little pearls.
* Java Packages::               Coffee break.
* Fonts::                       Fond of fonts.

@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 and distribution of the GNU system.
Guix makes it easy for unprivileged
users to install, upgrade, or remove software 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 Guix System
@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 a standalone operating system distribution,
@dfn{Guix@tie{}System} (@pxref{GNU Distribution}).

@node Managing Software the Guix Way
@section Managing Software the Guix Way

@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 functional package management
@cindex isolation
Under the hood, Guix implements the @dfn{functional package management}
discipline pioneered by Nix (@pxref{Acknowledgments}).
In Guix, the package build and installation process is seen
as a @emph{function}, in the mathematical sense.  That function takes inputs,
such as build scripts, a compiler, and libraries, and
returns an installed package.  As a pure function, its result depends
solely on its inputs---for instance, it cannot refer to software or
scripts that were not explicitly passed as inputs.  A build function
always produces the same result when passed a given set of inputs.  It
cannot alter the environment of the running system in
any way; for instance, it cannot create, modify, or delete files outside
of its build and installation directories.  This is achieved by running
build processes in isolated environments (or @dfn{containers}), where only their
explicit inputs are visible.

@cindex store
The result of package build functions is @dfn{cached} in the file
system, in a special directory called @dfn{the store} (@pxref{The
Store}).  Each package is installed in a directory of its own in the
store---by default under @file{/gnu/store}.  The directory name contains
a hash of all the inputs used to build that package; thus, changing an
input yields a different directory name.

This approach is the foundation for the salient features of Guix: support
for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).


@node GNU Distribution
@section GNU Distribution

@cindex Guix System
@cindex GuixSD
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}.  The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}).  When we need to
distinguish between the two, we refer to the standalone distribution as
Guix@tie{}System.

The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications.  The complete
list of available packages can be browsed
@url{http://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

@example
guix package --list-available
@end example

Our goal is to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.

Packages are currently available on the following platforms:

@table @code

@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;

@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;

@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.

@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.  This is
currently in an experimental stage, with limited support.
@xref{Contributing}, for how to help!

@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel.

@end table

With Guix@tie{}System, 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}).  Guix System uses the Linux-libre kernel, the Shepherd
initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
Manual}), the well-known GNU utilities and tool chain, as well as the
graphical environment or system services of your choice.

Guix System is available on all the above platforms except
@code{mips64el-linux}.

@noindent
For information on porting to other architectures or kernels,
@pxref{Porting}.

Building this distribution is a cooperative effort, and you are invited
to join!  @xref{Contributing}, for information about how you can help.


@c *********************************************************************
@node Installation
@chapter Installation

@cindex installing Guix

@quotation Note
We recommend the use of this
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
shell installer script} to install Guix on top of a running GNU/Linux system,
thereafter called a @dfn{foreign distro}.@footnote{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}.} The script automates the
download, installation, and initial configuration of Guix.  It should be run
as the root user.
@end quotation

@cindex foreign distro
@cindex directories related to foreign distro
When installed on a 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}).

If you prefer to perform the installation steps manually or want to tweak
them, you may find the following subsections useful.  They describe the
software requirements of Guix, as well as how to install it manually and get
ready to use it.

@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
@cindex installer script
This section describes how to install Guix on an arbitrary system from a
self-contained tarball providing binaries for Guix and for all its
dependencies.  This is often quicker than installing from source, which
is described in the next sections.  The only requirement is to have
GNU@tie{}tar and Xz.

Installing goes along these lines:

@enumerate
@item
@cindex downloading Guix binary
Download the binary tarball from
@indicateurl{https://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 https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
@end example

If that command fails because you do not have the required public key,
then run this command to import it:

@example
$ gpg --keyserver @value{KEY-SERVER} \
      --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 the profile available under @file{~root/.config/guix/current}, which is
where @command{guix pull} will install updates (@pxref{Invoking guix pull}):

@example
# mkdir -p ~root/.config/guix
# ln -sf /var/guix/profiles/per-user/root/current-guix \
         ~root/.config/guix/current
@end example

Source @file{etc/profile} to augment @code{PATH} and other relevant
environment variables:

@example
# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
  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/.config/guix/current/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/.config/guix/current/lib/upstart/system/guix-daemon.conf \
     /etc/init/
# start guix-daemon
@end example

Otherwise, you can still start the daemon manually with:

@example
# ~root/.config/guix/current/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/current-guix/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/current-guix/share/info/* ;
  do ln -s $i ; done
@end example

That way, assuming @file{/usr/local/share/info} is in the search path,
running @command{info guix} will open this manual (@pxref{Other Info
Directories,,, texinfo, GNU Texinfo}, for more details on changing the
Info search path.)

@item
@cindex substitutes, authorization thereof
To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its mirrors
(@pxref{Substitutes}), authorize them:

@example
# guix archive --authorize < \
     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.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 \
  --profile-name=current-guix guix
@end example

@xref{Invoking guix pack}, for more info on this handy tool.

@node Requirements
@section Requirements

This section lists requirements when building Guix from source.  The
build procedure for Guix is the same as for other GNU software, and is
not covered here.  Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.

@cindex official website
GNU Guix is available for download from its website at
@url{https://www.gnu.org/software/guix/}.

GNU Guix depends on the following packages:

@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@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
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
@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 @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON};
@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
@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://gnupg.org/, GNU libgcrypt};
@item @url{http://sqlite.org, SQLite 3};
@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize

@cindex state directory
When configuring Guix on a system that already has a Guix installation,
be sure to specify the same state directory as the existing installation
using the @code{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
GNU Coding Standards}).  The @command{configure} script protects against
unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).

@cindex Nix, compatibility
When a working installation of @url{http://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}.  In that case,
Nix replaces the three dependencies above.

Guix is compatible with Nix, so it is possible to share the same store
between both.  To do so, you must pass @command{configure} not only the
same @code{--with-store-dir} value, but also the same
@code{--localstatedir} value.  The latter is essential because it
specifies where the database that stores metadata about the store is
located, among other things.  The default values for Nix are
@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
Note that @code{--disable-daemon} is not required if
your goal is to share the store with Nix.

@node Running the Test Suite
@section Running the Test Suite

@cindex test suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite.  It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software.  To run the test
suite, type:

@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")