     [file version.texi not included]

This manual documents GNU Guix version 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.''

GNU Guix
********

This document describes GNU Guix version VERSION, a functional package management tool written for the GNU system.

Introduction
************

GNU Guix (``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.

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

The result of package build functions is cached in the file system, in a special directory called the package store.  In practice, each package is installed in a directory of its own, in the store---by default under /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 (see 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.

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.

Features
========

When using Guix, each package ends up in the package store, in its own directory---something that resembles /nix/store/xxx-package-1.2, where xxx is a base32 string.

Instead of referring to these directories, users have their own profile, which points to the packages that they actually want to use.  That profile is normally stored in $HOME/.guix-profile, and each user has its own profile.

For example, if alice installed GCC 4.7.2, then /home/alice/.guix-profile/bin/gcc points to /nix/store/xxx-gcc-4.7.2/bin/gcc; on the same machine, 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 guix-package command is the central tool to manage packages.  It operates on those per-user profiles, and can be used with normal user privileges.

The command provides the obvious install, remove, and upgrade operations.  Each invocation is actually a transaction: either the specified operations succeed, or nothing happens.  Thus, if the 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 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 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 purely functional approach to package management, as described in the introduction (see Introduction). Each /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 transparent binary/source deployment.  When a pre-built binary for a /nix/store path is available from an external source, Guix just downloads it; otherwise, it builds the package from source, locally.

Invoking guix-package
=====================

The 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 (see Features).  Its syntax is:

     guix-package OPTIONS

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

--install=PACKAGE
-i PACKAGE
     Install PACKAGE.

     PACKAGE may specify either a simple package name, such as guile, or a package name followed by a hyphen and version number, such as guile-1.8.  In addition, PACKAGE may contain a colon, followed by the name of one of the outputs of the package, as in gcc:doc or libsigsegv-2.10:lib.

--remove=PACKAGE
-r PACKAGE
     Remove PACKAGE.

--upgrade=REGEXP
-u REGEXP
     Upgrade all the installed packages matching REGEXP.

--profile=PROFILE
-p PROFILE
     Use PROFILE instead of the user's default profile.

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

--bootstrap
     Use the bootstrap Guile to build the profile.  This option is only useful to distribution developers.

In addition to these actions guix-package supports the following options to query the current state of a profile, or the availability of packages:

--list-installed[=REGEXP]
-I [REGEXP]
     List currently installed packages in the specified profile.  When REGEXP is specified, list only installed packages whose name matches 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, out for the default output, include for its headers, etc.), and the path of this package in the store.

--list-available[=REGEXP]
-A [REGEXP]
     List packages currently available in the software distribution.  When REGEXP is specified, list only installed packages whose name matches REGEXP.

     For each package, print the following items separated by tabs: its name, its version string, and the source location of its definition.

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 the Guix daemon, on behalf of users.  In a standard setup, the daemon has write access to the store---the /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.

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

Defining Packages
=================

The high-level interface to package definitions is implemented in the (guix packages) and (guix build-system) modules.  As an example, the package definition, or recipe, for the GNU Hello package looks like this:

     (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+")))

Without being a Scheme expert, the reader may have guessed the meaning of the various fields here.  This expression binds variable HELLO to a <package> object, which is essentially a record (see Scheme records (GNU Guile Reference Manual)). This package object can be inspected using procedures found in the (guix packages) module; for instance, (package-name hello) returns---surprise!---"hello".

There are a few points worth noting in the above package definition:

  * The source field of the package is an <origin> object. Here, the url-fetch method from (guix download) is used, meaning that the source is a file to be downloaded over FTP or HTTP.

     The mirror://gnu prefix instructs url-fetch to use one of the GNU mirrors defined in (guix download).

     The 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 (base32 ...) form introduces the base32 representation of the hash.  A convenient way to obtain this information is with the guix-download tool.

  * The build-system field is set to GNU-BUILD-SYSTEM.  The GNU-BUILD-SYSTEM variable is defined in the (guix build-system gnu) module, and is bound to a <build-system> object.

     Naturally, GNU-BUILD-SYSTEM represents the familiar GNU Build System, and variants thereof (see configuration and makefile conventions (GNU Coding Standards)).  In a nutshell, packages using the GNU Build System may be configured, build, and installed with the usual ./configure && make && make check && make install command sequence.  This is what GNU-BUILD-SYSTEM does.

     In addition, 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.

  * The 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 "gawk" whose value is that of the GAWK variable; GAWK is itself bound to a <package> object.

     Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here.  Instead, GNU-BUILD-SYSTEM takes care of ensuring that they are present.

     However, any other dependencies need to be specified in the inputs field.  Any dependency not specified here will simply be unavailable to the build process, possibly leading to a build failure.

There are other fields that package definitions may provide.  Of particular interest is the 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:

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

These are keyword arguments (see keyword arguments in Guile (GNU Guile Reference Manual)).  They are passed to GNU-BUILD-SYSTEM, which interprets them as meaning ``do not run make check'', and ``run configure with the --enable-silent-rules flag''.

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

Behind the scenes, a derivation corresponding to the <package> object is first computed by the package-derivation procedure. That derivation is stored in a .drv file under /nix/store. The build actions is prescribes may then be realized by using the build-derivations procedure (see The Store).

 -- Scheme Procedure: package-derivation STORE PACKAGE [SYSTEM]
     Return the derivation of PACKAGE for SYSTEM.  The result is the file name of the derivation---i.e., a .drv file under /nix/store.

     PACKAGE must be a valid <package> object, and SYSTEM must be a string denoting the target system type---e.g., "x86_64-linux" for an x86_64 Linux-based GNU system.  STORE must be a connection to the daemon, which operates on the store (see The Store).

The Store
=========

(guix store)

Derivations
===========

(guix derivations)

Utilities
*********

Invoking guix-build
===================

The 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:

     guix-build OPTIONS PACKAGE-OR-DERIVATION...

PACKAGE-OR-DERIVATION may be either the name of a package found in the software distribution such as coreutils, or a derivation such as /nix/store/xxx-coreutils-8.19.drv.  Alternatively, the --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 OPTIONS may be zero or more of the following:

--expression=EXPR
-e EXPR
     Build the package EXPR evaluates to.

     For example, EXPR may be (@ (distro packages guile) guile-1.8), which unambiguously designates this specific variant of version 1.8 of Guile.

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

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

--system=SYSTEM
-s SYSTEM
     Attempt to build for SYSTEM---e.g., 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 --system=i686-linux on an x86_64-linux system allows users to build packages in a complete 32-bit environment.

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

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

--dry-run
-n
     Do not build the derivations.

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

--cores=N
-c N
     Allow the use of up to N CPU cores for the build.  The special value 0 means to use as many CPU cores as available.

--root=FILE
-r FILE
     Make FILE a symlink to the result, and register it as a garbage collector root.

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

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.

GNU Free Documentation License
******************************

     [file fdl-1.3.texi not included]