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

@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 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 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.
@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 operations succeed, 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.
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 it 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} specify 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 -x @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 --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



@c *********************************************************************
@node Programming Interface
@chapter Programming Interface

@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

@code{(guix packages)} and @code{(guix build-system)}

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