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, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 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.
* 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 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.
* Programming Index::           Data types, functions, and variables.

@detailmenu
 --- The Detailed Node Listing ---

Installation

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

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.
* Emacs Interface::             Package management from Emacs.
* 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.

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.

Utilities

* Invoking guix build::         Building packages from the command line.
* 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.
* Invoking guix environment::   Setting up development environments.
* Invoking guix publish::       Sharing substitutes.

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.
* 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.
* Various Services::            Other services.

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.
* Python Modules::              Taming the snake.
* Perl Modules::                Little pearls.
* Fonts::                       Fond of fonts.

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