Skip to content
Snippets Groups Projects
guix.texi 393 KiB
Newer Older
\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
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2015 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
Copyright @copyright{} 2015 Leo Famulari

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.
* guix system: (guix)Invoking guix system
                      Managing 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.
* Emacs Interface::             Using Guix from Emacs.
* 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.

Emacs Interface

* Initial Setup: Emacs Initial Setup.	Preparing @file{~/.emacs}.
* Package Management: Emacs Package Management.	Managing packages and generations.
* Popup Interface: Emacs Popup Interface.	Magit-like interface for guix commands.
* Prettify Mode: Emacs Prettify.	Abbreviating @file{/gnu/store/@dots{}} file names.
* Build Log Mode: Emacs Build Log.	Highlighting Guix build logs.
* Completions: Emacs Completions.	Completing @command{guix} shell command.
* Development: Emacs Development.	Tools for Guix developers.
Alex Kost's avatar
Alex Kost committed
* Hydra: Emacs Hydra.			Interface for Guix build farm.
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.
Ludovic Courtès's avatar
Ludovic Courtès committed
* 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.
Ludovic Courtès's avatar
Ludovic Courtès committed
* Invoking guix size::          Profiling disk usage.
Ludovic Courtès's avatar
Ludovic Courtès committed
* Invoking guix graph::         Visualizing the graph of packages.
* Invoking guix environment::   Setting up development environments.
* Invoking guix publish::       Sharing substitutes.
Ludovic Courtès's avatar
Ludovic Courtès committed
* Invoking guix challenge::     Challenging substitute servers.
* Invoking guix container::     Process isolation.

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 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.
* Defining Services::           Adding new service definitions.

Services

* Base Services::               Essential system services.
* Networking Services::         Network setup, SSH daemon, etc.
* X Window::                    Graphical display.
* Desktop Services::            D-Bus and desktop services.
* Database Services::           SQL databases.
Andy Wingo's avatar
Andy Wingo committed
* Mail Services::               IMAP, POP3, SMTP, and all that.
* Web Services::                Web servers.
* Various Services::            Other services.
Defining Services

* Service Composition::         The model for composing services.
* Service Types and Services::  Types and services.
* Service Reference::           API reference.
* dmd 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.
* 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

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 pioneered by Nix (@pxref{Acknowledgments}).
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
@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 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.

@cindex Guix System Distribution
@cindex GuixSD
Last but not least, Guix is used to build a distribution of the GNU
system, with many GNU and non-GNU free software packages.  The Guix
System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
properties of Guix at the system level.  With GuixSD, users
@emph{declare} all aspects of the operating system configuration, and
Guix takes care of instantiating that configuration in a reproducible,
stateless fashion.  @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.
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}.
* 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.
@node Binary Installation
@section Binary Installation

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

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 don't have the required public key,
then run this command to import it:

@example
$ gpg --keyserver keys.gnupg.net --recv-keys 3D9AEBB5
@end example

@noindent
and rerun the @code{gpg --verify} command.
# tar --warning=no-timestamp -xf \
     guix-binary-@value{VERSION}.@var{system}.tar.xz
# mv var/guix /var/ && mv gnu /
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}).

# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
On hosts using the systemd init system, drop
@file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in
@file{/etc/systemd/system}.

Likewise, on hosts using the Upstart init system, drop
@file{~root/.guix-profile/lib/upstart/system/guix-daemon.conf} in
@file{/etc/init}.

Loading
Loading full blame...