guix-devel/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

@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

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

Copyright @copyright{} 2012 Ludovic Court@`es

@quotation
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 quotation
@end titlepage

@copying
This manual documents GNU Guix version @value{VERSION}.

Copyright (C) 2012, 2013 Ludovic Courtès

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

@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?
* Package Management::          Package installation, upgrade, etc.
* Programming Interface::       Using Guix in Scheme.
* Utilities::                   Package management commands.

* 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
in all the activities that relate to building packages from source,
honoring the build-time and run-time dependencies on packages,
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 depended on, and
returns the 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.  Last
but not least, a build function 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 dedicated ``chroots'', where only their explicit
inputs are visible.

@cindex package store
The result of package build functions is @dfn{cached} in the file
system, in a special directory called the @dfn{package store}.  In
practice, 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 upgrades and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).

Guix has a command-line interface allowing users to build, install,
upgrade, and remove packages, as well as a Scheme programming interface.
The remainder of this manual describes them.

@c *********************************************************************
@node Package Management
@chapter Package Management

The purpose of GNU Guix is to allow users to easily install, upgrade, and
remove software packages, without having to know about their build
procedure 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.

@menu
* Features::                    How Guix will make your life brighter.
* Invoking guix-package::       Package installation, removal, etc.
* Invoking guix-gc::            Running the garbage collector.
@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{/nix/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.  That profile is normally stored in @code{$HOME/.guix-profile}, and
each user has its own profile.

For example, if @code{alice} installed GCC 4.7.2, then
@file{/home/alice/.guix-profile/bin/gcc} points to
@file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob}
may have installed GCC 4.8.0, in which case its profile refers to these
particular package installation.  Both coexist, without any
interference.

The @command{guix-package} command is the central tool to manage
packages.  It operates on those per-user profiles, and can be used
@emph{with normal user privileges}.

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

All those packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by the 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.

Finally, Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
Each @file{/nix/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.

This foundation allows Guix to support @dfn{transparent binary/source
deployment}.  When a pre-built binary for a @file{/nix/store} path is
available from an external source, Guix just downloads it; otherwise, it
builds the package from source, locally.

@node Invoking guix-package
@section Invoking @command{guix-package}

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

Primarily, @var{options} specifies the operations to be performed during
the transaction.  Upon completion, a new profile is created, but
previous generations of the profile remain available, should the user
want to roll back.

@table @code

@item --install=@var{package}
@itemx -i @var{package}
Install @var{package}.

@var{package} may specify either a simple package name, such as
@code{guile}, or a package name followed by a hyphen and version number,
such as @code{guile-1.8}.  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{libsigsegv-2.10:lib}.

@item --remove=@var{package}
@itemx -r @var{package}
Remove @var{package}.

@item --upgrade=@var{regexp}
@itemx -u @var{regexp}
Upgrade all the installed packages matching @var{regexp}.

@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.

@item --dry-run
@itemx -n
Show what would be done without actually doing it.

@item --verbose
Produce verbose output.  In particular, emit the environment's build log
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 --list-installed[=@var{regexp}]
@itemx -I [@var{regexp}]
List currently installed packages in the specified profile.  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 software 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, and the source location of its definition.

@end table


@node Invoking guix-gc
@section Invoking @command{guix-gc}

@cindex garbage collector
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{/nix/store} directory.

The garbage collector has a set of known @dfn{roots}: any file under
@file{/nix/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 includes default user
profiles, and may be augmented with @command{guix-build --root}, for
example (@pxref{Invoking guix-build}).

The @command{guix-gc} command has three mode of operations: it can be
used to garbage-collect any dead files (the default), to delete specific
files (the @code{--delete} option), or to print garbage-collector
information.  The available options are listed below:

@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Collect garbage---i.e., unreachable @file{/nix/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.

When @var{min} is omitted, collect all the garbage.

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


@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{/nix/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.

This chapter describes all these APIs in turn, starting from high-level
package definitions.

@menu
* Defining Packages::   Defining new packages.
* The Store::           Manipulating the package store.
* Derivations::         Low-level interface to package derivations.
@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 hello
  (package
    (name "hello")
    (version "2.8")
    (source (origin
             (method url-fetch)
             (uri (string-append "mirror://gnu/hello/hello-" version
                                 ".tar.gz"))
             (sha256
              (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
    (build-system gnu-build-system)
    (inputs `(("gawk" ,gawk)))
    (synopsis "GNU Hello")
    (description "Yeah...")
    (home-page "http://www.gnu.org/software/hello/")
    (license "GPLv3+")))
@end example

@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here.  This expression binds variable @var{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"}.

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.
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.  A convenient way to obtain this
information is with the @code{guix-download} tool.

@item
@cindex GNU Build System
The @code{build-system} field is set to @var{gnu-build-system}.  The
@var{gnu-build-system} variable is defined in the @code{(guix
build-system gnu)} module, and is bound to a @code{<build-system>}
object.

Naturally, @var{gnu-build-system} represents the familiar GNU Build
System, and variants thereof (@pxref{Configuration, configuration and
makefile conventions,, standards, GNU Coding Standards}).  In a
nutshell, packages using the GNU Build System may be configured, built,
and installed with the usual @code{./configure && make && make check &&
make install} command sequence.  This is what @var{gnu-build-system}
does.

In addition, @var{gnu-build-system} ensures that the ``standard''
environment for GNU packages is available.  This includes tools such as
GCC, Coreutils, Bash, Make, Diffutils, and Patch.

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

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.

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

There are other fields that package definitions may provide.  Of
particular interest is the @code{arguments} field.  When specified, it
must be bound to a list of additional arguments to be passed to the
build system.  For instance, the above definition could be augmented
with the following field initializer:

@example
    (arguments `(#:tests? #f
                 #:configure-flags '("--enable-silent-rules")))
@end example

@noindent
These are keyword arguments (@pxref{Optional Arguments, keyword
arguments in Guile,, guile, GNU Guile Reference Manual}).  They are
passed to @var{gnu-build-system}, which interprets them as meaning ``do
not run @code{make check}'', and ``run @file{configure} with the
@code{--enable-silent-rules} flag''.

Once a package definition is in place@footnote{Simple package
definitions like the one above may be automatically converted from the
Nixpkgs distribution using the @command{guix-import} command.}, the
package may actually be built using the @code{guix-build} command-line
tool (@pxref{Invoking guix-build}).

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{/nix/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 derivation of @var{package} for @var{system}.  The result is
the file name of the derivation---i.e., a @code{.drv} file under
@code{/nix/store}.

@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

@node The Store
@section The Store

@code{(guix store)}

@node Derivations
@section Derivations

@code{(guix derivations)}

@c *********************************************************************
@node Utilities
@chapter Utilities

@menu
* Invoking guix-build:: Building packages from the command line.
@end menu

@node Invoking guix-build
@section Invoking @command{guix-build}

The @command{guix-build} command builds packages or derivations and
their dependencies, and prints the resulting store paths.  It is mainly
useful for distribution developers.  The general syntax is:

@example
guix-build @var{options} @var{package-or-derivation}@dots{}
@end example

@var{package-or-derivation} may be either the name of a package found in
the software distribution such as @code{coreutils}, or a derivation such
as @file{/nix/store/xxx-coreutils-8.19.drv}.  Alternatively, the
@code{--expression} option may be used to specify a Scheme expression
that evaluates to a package; this is useful when disambiguation among
several same-named packages or package variants is needed.

The @var{options} may be zero or more of the following:

@table @code

@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package @var{expr} evaluates to.

For example, @var{expr} may be @code{(@@ (distro packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.

@item --source
@itemx -S
Build the packages' source derivations, rather than the packages
themselves.

For instance, @code{guix-build -S gcc} returns something like
@file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.

@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the host's system type.

An example use of this is on Linux-based systems, which can emulate
different personalities.  For instance, passing
@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
to build packages in a complete 32-bit environment.

@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.

@item --keep-failed
@itemx -K
Keep the build tree of failed builds.  Thus, if a build fail, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at
the end of the build log.  This is useful when debugging build issues.

@item --dry-run
@itemx -n
Do not build the derivations.

@item --no-substitutes
Build instead of resorting to pre-built substitutes.

@item --cores=@var{n}
@itemx -c @var{n}
Allow the use of up to @var{n} CPU cores for the build.  The special
value @code{0} means to use as many CPU cores as available.

@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

@item --verbosity=@var{level}
Use the given verbosity level.  @var{level} must be an integer between 0
and 5; higher means more verbose output.  Setting a level of 4 or more
may be helpful when debugging setup issues with the build daemon.

@end table

Behind the scenes, @command{guix-build} is essentially an interface to
the @code{package-derivation} procedure of the @code{(guix packages)}
module, and to the @code{build-derivations} procedure of the @code{(guix
store)} module.


@c *********************************************************************
@node Acknowledgments
@chapter Acknowledgments

Guix is based on the Nix package manager, which was designed and
implemented by Eelco Dolstra.  Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes.  Without this work, Guix would not exist.

The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.

@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@c *********************************************************************
@node Concept Index
@unnumbered Concept Index
@printindex cp

@node Function Index
@unnumbered Function Index
@printindex fn

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End: