mirror of
https://git.in.rschanz.org/ryan77627/guix.git
synced 2024-12-25 13:58:15 -05:00
51c8d7909d
* doc/guix.texi (Invoking guix-package): Fix short form of `--install'. Reported by Andreas Enge <andreas@enge.fr>.
571 lines
21 KiB
Text
571 lines
21 KiB
Text
\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@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
|
||
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 -i @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
|
||
|
||
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
|
||
@file{/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.
|
||
|
||
@cindex derivation
|
||
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 @dfn{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.
|
||
|
||
@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
|
||
|
||
The high-level interface to package definitions is implemented in the
|
||
@code{(guix packages)} and @code{(guix build-system)} modules. As an
|
||
example, the package definition, or @dfn{recipe}, for the GNU Hello
|
||
package looks like this:
|
||
|
||
@example
|
||
(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+")))
|
||
@end example
|
||
|
||
@noindent
|
||
Without being a Scheme expert, the reader may have guessed the meaning
|
||
of the various fields here. This expression binds variable @var{hello}
|
||
to a @code{<package>} object, which is essentially a record
|
||
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
|
||
This package object can be inspected using procedures found in the
|
||
@code{(guix packages)} module; for instance, @code{(package-name hello)}
|
||
returns---surprise!---@code{"hello"}.
|
||
|
||
There are a few points worth noting in the above package definition:
|
||
|
||
@itemize
|
||
@item
|
||
The @code{source} field of the package is an @code{<origin>} object.
|
||
Here, the @code{url-fetch} method from @code{(guix download)} is used,
|
||
meaning that the source is a file to be downloaded over FTP or HTTP.
|
||
|
||
The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
|
||
the GNU mirrors defined in @code{(guix download)}.
|
||
|
||
The @code{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 @code{(base32 @dots{})} form introduces the
|
||
base32 representation of the hash. A convenient way to obtain this
|
||
information is with the @code{guix-download} tool.
|
||
|
||
@item
|
||
@cindex GNU Build System
|
||
The @code{build-system} field is set to @var{gnu-build-system}. The
|
||
@var{gnu-build-system} variable is defined in the @code{(guix
|
||
build-system gnu)} module, and is bound to a @code{<build-system>}
|
||
object.
|
||
|
||
Naturally, @var{gnu-build-system} represents the familiar GNU Build
|
||
System, and variants thereof (@pxref{Configuration, configuration and
|
||
makefile conventions,, standards, GNU Coding Standards}). In a
|
||
nutshell, packages using the GNU Build System may be configured, build,
|
||
and installed with the usual @code{./configure && make && make check &&
|
||
make install} command sequence. This is what @var{gnu-build-system}
|
||
does.
|
||
|
||
In addition, @var{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.
|
||
|
||
@item
|
||
The @code{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 @code{"gawk"} whose value is that of the @var{gawk}
|
||
variable; @var{gawk} is itself bound to a @code{<package>} object.
|
||
|
||
Note that GCC, Coreutils, Bash, and other essential tools do not need to
|
||
be specified as inputs here. Instead, @var{gnu-build-system} takes care
|
||
of ensuring that they are present.
|
||
|
||
However, any other dependencies need to be specified in the
|
||
@code{inputs} field. Any dependency not specified here will simply be
|
||
unavailable to the build process, possibly leading to a build failure.
|
||
@end itemize
|
||
|
||
There are other fields that package definitions may provide. Of
|
||
particular interest is the @code{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:
|
||
|
||
@example
|
||
(arguments `(#:tests? #f
|
||
#:configure-flags '("--enable-silent-rules")))
|
||
@end example
|
||
|
||
@noindent
|
||
These are keyword arguments (@pxref{Optional Arguments, keyword
|
||
arguments in Guile,, guile, GNU Guile Reference Manual}). They are
|
||
passed to @var{gnu-build-system}, which interprets them as meaning ``do
|
||
not run @code{make check}'', and ``run @file{configure} with the
|
||
@code{--enable-silent-rules} flag''.
|
||
|
||
Once a package definition is in place@footnote{Simple package
|
||
definitions like the one above may be automatically converted from the
|
||
Nixpkgs distribution using the @command{guix-import} command.}, the
|
||
package may actually be built using the @code{guix-build} command-line
|
||
tool (@pxref{Invoking guix-build}).
|
||
|
||
Behind the scenes, a derivation corresponding to the @code{<package>}
|
||
object is first computed by the @code{package-derivation} procedure.
|
||
That derivation is stored in a @code{.drv} file under @file{/nix/store}.
|
||
The build actions is prescribes may then be realized by using the
|
||
@code{build-derivations} procedure (@pxref{The Store}).
|
||
|
||
@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
|
||
Return the derivation of @var{package} for @var{system}. The result is
|
||
the file name of the derivation---i.e., a @code{.drv} file under
|
||
@code{/nix/store}.
|
||
|
||
@var{package} must be a valid @code{<package>} object, and @var{system}
|
||
must be a string denoting the target system type---e.g.,
|
||
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
|
||
must be a connection to the daemon, which operates on the store
|
||
(@pxref{The Store}).
|
||
@end deffn
|
||
|
||
@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:
|