guix/doc/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 BCA689B636553801C3C62150197A5888235FACAC

@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017 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 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich@*
Copyright @copyright{} 2016 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016 ng0@*
Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017 Clément Lassieur@*
Copyright @copyright{} 2017 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa

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 build: (guix)Invoking guix build.      Building 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.
@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.

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 archive::       Exporting and importing store files.

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 @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'.

GNU Distribution

* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring the operating system.
* 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 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.
* GRUB 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.
* Database Services::           SQL databases.
* Mail Services::               IMAP, POP3, SMTP, and all that.
* Messaging Services::          Messaging services.
* Kerberos Services::           Kerberos services.
* Web Services::                Web servers.
* VPN Services::                VPN daemons.
* Network File System::         NFS related services.
* Continuous Integration::      The Cuirass service.
* 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::              Taming the snake.
* 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.

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
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{~/.guix-profile}:

@example
# ln -sf /var/guix/profiles/per-user/root/guix-profile \
         ~root/.guix-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:

@example
# ln -s ~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
# ln -s ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
# initctl reload-configuration
# 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
@end enumerate

This completes root-level install of Guix.  Each user will need to
perform additional steps to make their Guix environment ready for use,
@pxref{Application Setup}.

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


@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.7 or later;
@item @url{http://gnupg.org/, GNU libgcrypt};
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize

The following dependencies are optional:

@itemize
@item
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to
access @code{https} URLs for substitutes, which is highly recommended
(@pxref{Substitutes}).  It also allows you to access HTTPS URLs with the
@command{guix download} command (@pxref{Invoking guix download}), the
@command{guix import pypi} command, and the @command{guix import cpan}
command.  @xref{Guile Preparations, how to install the GnuTLS bindings
for Guile,, gnutls-guile, GnuTLS-Guile}.

@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://zlib.net, zlib} is available, @command{guix publish}
can compress build byproducts (@pxref{Invoking guix publish}).
@end itemize

Unless @code{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:

@itemize
@item @url{http://sqlite.org, SQLite 3};
@item @url{http://www.bzip.org, libbz2};
@item @url{http://gcc.gnu.org, GCC's g++}, 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