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

@copying
Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
Copyright @copyright{} 2013 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov

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

@dircategory Package management
@direntry
* guix: (guix).       Guix, the functional package manager.
* guix package: (guix)Invoking guix package
                      Managing packages with Guix.
* guix build: (guix)Invoking guix build
                      Building packages with Guix.
@end direntry

@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author Ludovic Courtès
@author Andreas Enge
@author Nikita Karetnikov

@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.
* Function Index::              Functions.
@end menu

@c *********************************************************************
@node Introduction
@chapter Introduction

GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
using the international phonetic alphabet (IPA).} is a functional
package management tool for the GNU system.  Package management consists
of all activities that relate to building packages from sources,
honoring their build-time and run-time dependencies,
installing packages in user environments, upgrading installed packages
to new versions or rolling back to a previous set, removing unused
software packages, etc.

@cindex functional package management
The term @dfn{functional} refers to a specific package management
discipline.  In Guix, the package build and installation process is seen
as a 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 system's environment in
any way; for instance, it cannot create, modify, or delete files outside
of its build and installation directories.  This is achieved by running
build processes in isolated environments (or @dfn{containers}), where only their
explicit inputs are visible.

@cindex store
The result of package build functions is @dfn{cached} in the file
system, in a special directory called @dfn{the store} (@pxref{The
Store}).  Each package is installed in a directory of its own, in the
store---by default under @file{/nix/store}.  The directory name contains
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 of Guix's salient features: support for
transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).

Guix has a command-line interface, which allows users to build, install,
upgrade, and remove packages, as well as a Scheme programming interface.

Last but not least, Guix is used to build a distribution of the GNU
system, with many GNU and non-GNU free software packages.  @xref{GNU
Distribution}.

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

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.

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.

@menu
* Requirements::                Software needed to build and run Guix.
* Setting Up the Daemon::       Preparing the build daemon's environment.
* Invoking guix-daemon::        Running the build daemon.
@end menu

@node Requirements
@section Requirements

GNU Guix depends on the following packages:

@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
@item @url{http://gnupg.org/, GNU libgcrypt}
@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++}
@end itemize

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

@menu
* Build Environment Setup::     Preparing the isolated build environment.
* Daemon Offload Setup::        Offloading builds to remote machines.
@end menu

@node Build Environment Setup
@subsection Build Environment Setup

In a standard multi-user setup, Guix and its daemon---the
@command{guix-daemon} program---are installed by the system
administrator; @file{/nix/store} is owned by @code{root} and
@command{guix-daemon} runs as @code{root}.  Unprivileged users may use
Guix tools to build packages or otherwise access the store, and the