394 lines
13 KiB
Plaintext
394 lines
13 KiB
Plaintext
\input texinfo
|
|
@c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
@setfilename guix.info
|
|
@documentencoding UTF-8
|
|
@settitle 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{Guix Reference Manual}
|
|
@subtitle{Using the 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 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 Guix
|
|
|
|
This document describes Guix version @value{VERSION}.
|
|
|
|
@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
|
|
|
|
Guix is a functional package management tool. 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 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
|
|
|
|
|
|
|
|
|
|
|
|
@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:
|