Newer
Older
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@c %**end of header
@include version.texi
Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
Taylan Ulrich Bayırlı/Kammer
committed
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2015 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Taylan Ulrich Bayırlı/Kammer
committed
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
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
* guix system: (guix)Invoking guix system
Managing the operating system configuration.
@dircategory Software development
@direntry
* guix environment: (guix)Invoking guix environment
Building development environments with Guix.
@end direntry
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*
@end titlepage
@contents
@c *********************************************************************
@node Top
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.
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.
* 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 graph:: Visualizing the graph of packages.
* 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.
* 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.
* 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.
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 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
Nikita Karetnikov
committed
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
Nikita Karetnikov
committed
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
Nikita Karetnikov
committed
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
Nikita Karetnikov
committed
explicit inputs are visible.
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
Nikita Karetnikov
committed
transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
Nikita Karetnikov
committed
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
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}@footnote{As
usual, make sure to download the associated @file{.sig} file and to
verify the authenticity of the tarball against it!}, where @var{system}
is @code{x86_64-linux} for an @code{x86_64} machine already running the
kernel Linux, and so on.
@item
As @code{root}, run:
@example
# tar --warning=no-timestamp -xf \
guix-binary-@value{VERSION}.@var{system}.tar.xz
# mv var/guix /var/ && mv gnu /
@end example
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}).
Ludovic Courtès
committed
Run the daemon:
# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@end example
On hosts using the systemd init system, drop
@file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in
@file{/etc/systemd/system}.
@item
Make the @command{guix} command available to other users on the machine,
for instance with:
@example
# mkdir -p /usr/local/bin
# cd /usr/local/bin
# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
@item
To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
authorize them:
@example
# guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
@end enumerate
And that's it! For additional tips and tricks, @pxref{Application
Setup}.
The @code{guix} package must remain available in @code{root}'s
profile, or it would become subject to garbage collection---in which
case you would find yourself badly handicapped by the lack of the
@command{guix} command.
The tarball in question can be (re)produced and verified simply by
running the following command in the Guix source tree:
@example
make guix-binary.@var{system}.tar.xz
@end example
@node Requirements
@section Requirements
This section lists requirements when building Guix from source. The
build procedure for Guix is the same as for other GNU software, and is
not covered here. Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.
GNU Guix depends on the following packages:
@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
@item @url{http://gnupg.org/, GNU libgcrypt};
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
@itemize
@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
allow you to use the @command{guix import pypi} command (@pxref{Invoking
guix import}). It is of
interest primarily for developers and not for casual users.
@item
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
allow you to access @code{https} URLs with the @command{guix download}
command (@pxref{Invoking guix download}), the @command{guix import pypi}
command, and the @command{guix import cpan} command. This is primarily
of interest to developers. @xref{Guile Preparations, how to install the
GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:
@itemize
@item @url{http://sqlite.org, SQLite 3};
@item @url{http://www.bzip.org, libbz2};
@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
Nikita Karetnikov
committed
When a working installation of @url{http://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nikita Karetnikov
committed
Nix replaces the three dependencies above.
Guix is compatible with Nix, so it is possible to share the same store
between both. To do so, you must pass @command{configure} not only the
same @code{--with-store-dir} value, but also the same
Nikita Karetnikov
committed
@code{--localstatedir} value. The latter is essential because it
specifies where the database that stores metadata about the store is
located, among other things. The default values for Nix are
@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
Nikita Karetnikov
committed
Note that @code{--disable-daemon} is not required if
your goal is to share the store with Nix.
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
@node Running the Test Suite
@section Running the Test Suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite. It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software. To run the test
suite, type:
@example
make check
@end example
Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up. The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
that is created for test purposes will already have various things in
cache.
Upon failure, please email @email{bug-guix@@gnu.org} and attach the
@file{test-suite.log} file. When @file{tests/@var{something}.scm}
fails, please also attach the @file{@var{something}.log} file available
in the top-level build directory. Please specify the Guix version being
used as well as version numbers of the dependencies
(@pxref{Requirements}) in your message.
@node Setting Up the Daemon
@section Setting Up the Daemon
@cindex daemon
Operations such as building a package or running the garbage collector
are all performed by a specialized process, the @dfn{build daemon}, on
behalf of clients. Only the daemon may access the store and its
associated database. Thus, any operation that manipulates the store
goes through the daemon. For instance, command-line tools such as
@command{guix package} and @command{guix build} communicate with the
daemon (@i{via} remote procedure calls) to instruct it what to do.
The following sections explain how to prepare the build daemon's
environment. Also @ref{Substitutes}, for information on how to allow
the daemon to download pre-built binaries.
@menu
* Build Environment Setup:: Preparing the isolated build environment.
* Daemon Offload Setup:: Offloading builds to remote machines.
@end menu
@node Build Environment Setup
@subsection Build Environment Setup
In a standard multi-user setup, Guix and its daemon---the
@command{guix-daemon} program---are installed by the system
administrator; @file{/gnu/store} is owned by @code{root} and
@command{guix-daemon} runs as @code{root}. Unprivileged users may use
Guix tools to build packages or otherwise access the store, and the
daemon will do it on their behalf, ensuring that the store is kept in a
consistent state, and allowing built packages to be shared among users.
@cindex build users
When @command{guix-daemon} runs as @code{root}, you may not want package
build processes themselves to run as @code{root} too, for obvious
security reasons. To avoid that, a special pool of @dfn{build users}
should be created for use by build processes started by the daemon.
These build users need not have a shell and a home directory: they will
just be used when the daemon drops @code{root} privileges in build
processes. Having several such users allows the daemon to launch
distinct build processes under separate UIDs, which guarantees that they
do not interfere with each other---an essential feature since builds are
regarded as pure functions (@pxref{Introduction}).
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
# groupadd --system guixbuild
# for i in `seq -w 1 10`;
useradd -g guixbuild -G guixbuild \
-d /var/empty -s `which nologin` \
-c "Guix build user $i" --system \
guixbuilder$i;
done
@end example
@noindent
The number of build users determines how many build jobs may run in
parallel, as specified by the @option{--max-jobs} option
(@pxref{Invoking guix-daemon, @option{--max-jobs}}). The
@code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
file in @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started.}:
# guix-daemon --build-users-group=guixbuild
@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
environment contains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------
@itemize
@item
a minimal @code{/dev} directory, created mostly independently from the
host @code{/dev}@footnote{``Mostly'', because while the set of files
that appear in the chroot's @code{/dev} is fixed, most of these files
can only be created if the host has them.};
@item
the @code{/proc} directory; it only shows the container's processes
since a separate PID name space is used;
@item
@file{/etc/passwd} with an entry for the current user and an entry for
user @file{nobody};
@item
@file{/etc/group} with an entry for the user's group;
@item
@file{/etc/hosts} with an entry that maps @code{localhost} to
@code{127.0.0.1};
@item
a writable @file{/tmp} directory.
@end itemize
If you are installing Guix as an unprivileged user, it is still possible
to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
However, build processes will not be isolated from one another, and not
from the rest of the system. Thus, build processes may interfere with
each other, and may access programs, libraries, and other files
available on the system---making it much harder to view them as
@emph{pure} functions.
@node Daemon Offload Setup
@subsection Using the Offload Facility
@cindex offloading
@cindex build hook
When desired, the build daemon can @dfn{offload}
derivation builds to other machines
running Guix, using the @code{offload} @dfn{build hook}. When that
feature is enabled, a list of user-specified build machines is read from
@file{/etc/guix/machines.scm}; anytime a build is requested, for
instance via @code{guix build}, the daemon attempts to offload it to one
of the machines that satisfies the derivation's constraints, in
particular its system type---e.g., @file{x86_64-linux}. Missing
prerequisites for the build are copied over SSH to the target machine,
which then proceeds with the build; upon success the output(s) of the
build are copied back to the initial machine.
The @file{/etc/guix/machines.scm} file typically looks like this:
@example
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
(user "bob")
(speed 2.)) ; incredibly fast!
(build-machine
(name "meeps.example.org")
(system "mips64el-linux")
(user "alice")
(private-key
(string-append (getenv "HOME")
@end example
@noindent
In the example above we specify a list of two build machines, one for
the @code{x86_64} architecture and one for the @code{mips64el}
architecture.
In fact, this file is---not surprisingly!---a Scheme file that is
evaluated when the @code{offload} hook is started. Its return value
must be a list of @code{build-machine} objects. While this example
shows a fixed list of build machines, one could imagine, say, using
DNS-SD to return a list of potential build machines discovered in the
local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
detailed below.
@deftp {Data Type} build-machine
This data type represents build machines the daemon may offload builds
to. The important fields are:
@table @code
@item name
The remote machine's host name.
@item system
The remote machine's system type---e.g., @code{"x86_64-linux"}.
@item user
The user account to use when connecting to the remote machine over SSH.
Note that the SSH key pair must @emph{not} be passphrase-protected, to
allow non-interactive logins.
@end table
A number of optional fields may be specified:
@item port
Port number of the machine's SSH server (default: 22).
@item private-key
The SSH private key file to use when connecting to the machine.
Currently offloading uses GNU@tie{}lsh as its SSH client
(@pxref{Invoking lsh,,, GNU lsh Manual}). Thus, the key file here must
be an lsh key file. This may change in the future, though.
@item parallel-builds
The number of builds that may run in parallel on the machine (1 by
default.)
@item speed
A ``relative speed factor''. The offload scheduler will tend to prefer
machines with a higher speed factor.
@item features
A list of strings denoting specific features supported by the machine.
An example is @code{"kvm"} for machines that have the KVM Linux modules
and corresponding hardware support. Derivations can request features by
name, and they will be scheduled on matching build machines.
@end table
The @code{guix} command must be in the search path on the build
machines, since offloading works by invoking the @code{guix archive} and
@code{guix build} commands. In addition, the Guix modules must be in
@code{$GUILE_LOAD_PATH} on the build machine---you can check whether
this is the case by running:
@example
lsh build-machine guile -c '(use-modules (guix config))'
@end example
There's one last thing to do once @file{machines.scm} is in place. As
explained above, when offloading, files are transferred back and forth
between the machine stores. For this to work, you first need to
generate a key pair on each machine to allow the daemon to export signed
archives of files from the store (@pxref{Invoking guix archive}):
@example
# guix archive --generate-key
@end example
@noindent
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:
@example
# guix archive --authorize < master-public-key.txt
@end example
@noindent
Likewise, the master machine must authorize the key of each build machine.
All the fuss with keys is here to express pairwise mutual trust
relations between the master and the build machines. Concretely, when
the master receives files from a build machine (and @i{vice versa}), its
build daemon can make sure they are genuine, have not been tampered
with, and that they are signed by an authorized key.
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
The @command{guix-daemon} program implements all the functionality to
access the store. This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc. It
is normally run as @code{root} like this:
@example
# guix-daemon --build-users-group=guixbuild
@end example
@noindent
For details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot
@cindex container, build environment
@cindex build environment
@cindex reproducible builds
By default, @command{guix-daemon} launches build processes under
different UIDs, taken from the build group specified with
@code{--build-users-group}. In addition, each build process is run in a
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
system directories. By default, the latter contains @file{/dev} and
@file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
@dfn{container}: in addition to having its own file system tree, it has
a separate mount name space, its own PID name space, network name space,
etc. This helps achieve reproducible builds (@pxref{Features}).
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
its @code{TMPDIR} environment variable; this directory is shared with
the container for the duration of the build. Be aware that using a
directory other than @file{/tmp} can affect build results---for example,
with a longer directory name, a build process that uses Unix-domain
sockets might hit the name length limitation for @code{sun_path}, which
it would otherwise not hit.
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Invoking guix build, @option{--keep-failed}}).
The following command-line options are supported:
@table @code
@item --build-users-group=@var{group}
Take users from @var{group} to run build processes (@pxref{Setting Up
the Daemon, build users}).
Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).
By default substitutes are used, unless the client---such as the
@command{guix package} command---is explicitly invoked with
@code{--no-substitutes}.
When the daemon runs with @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
is used.
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
@cindex build hook
@item --no-build-hook
Do not use the @dfn{build hook}.
The build hook is a helper program that the daemon can start and to
which it submits build requests. This mechanism is used to offload
builds to other machines (@pxref{Daemon Offload Setup}).
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.
The default value is @code{0}, but it may be overridden by clients, such
as the @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
The effect is to define the @code{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. The default value is
@code{1}. Setting it to @code{0} means that no builds will be performed
locally; instead, the daemon will offload builds (@pxref{Daemon Offload
Setup}), or simply fail.
@item --debug
Produce debugging output.
This is useful to debug daemon start-up issues, but then it may be
overridden by clients, for example the @code{--verbosity} option of
@command{guix build} (@pxref{Invoking guix build}).
@item --chroot-directory=@var{dir}
Add @var{dir} to the build chroot.
Doing this may change the result of build processes---for instance if
they use optional dependencies found in @var{dir} when it is available,
and not otherwise. For that reason, it is not recommended to do so.
Instead, make sure that each derivation declares all the inputs that it
needs.
@item --disable-chroot
Disable chroot builds.
Using this option is not recommended since, again, it would allow build
processes to gain access to undeclared dependencies. It is necessary,
though, when @command{guix-daemon} is running under an unprivileged user
account.
@item --disable-log-compression
Disable compression of the build logs.
Unless @code{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}. To save space, the daemon automatically compresses
them with bzip2 by default. This option disables that.
Ludovic Courtès
committed
@item --disable-deduplication
@cindex deduplication
Disable automatic file ``deduplication'' in the store.
By default, files added to the store are automatically ``deduplicated'':
Ludovic Courtès
committed
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file. This can
noticeably reduce disk usage, at the expense of slightly increased
Ludovic Courtès
committed
input/output load at the end of a build process. This option disables
this optimization.
@item --gc-keep-outputs[=yes|no]
Tell whether the garbage collector (GC) must keep outputs of live
derivations.
When set to ``yes'', the GC will keep the outputs of any live derivation
available in the store---the @code{.drv} files. The default is ``no'',
meaning that derivation outputs are kept only if they are GC roots.
@item --gc-keep-derivations[=yes|no]
Tell whether the garbage collector (GC) must keep derivations
corresponding to live outputs.
When set to ``yes'', as is the case by default, the GC keeps
derivations---i.e., @code{.drv} files---as long as at least one of their
outputs is live. This allows users to keep track of the origins of
items in their store. Setting it to ``no'' saves a bit of disk space.
Note that when both @code{--gc-keep-derivations} and
@code{--gc-keep-outputs} are used, the effect is to keep all the build
prerequisites (the sources, compiler, libraries, and other build-time
tools) of live objects in the store, regardless of whether these
prerequisites are live. This is convenient for developers since it
saves rebuilds or downloads.
@item --impersonate-linux-2.6
On Linux-based systems, impersonate Linux 2.6. This means that the
kernel's @code{uname} system call will report 2.6 as the release number.
This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.
@item --lose-logs
Do not keep build logs. By default they are kept under
@code{@var{localstatedir}/guix/log}.
@item --system=@var{system}
Assume @var{system} as the current system type. By default it is the
architecture/kernel pair found at configure time, such as
@code{x86_64-linux}.
@item --listen=@var{socket}
Listen for connections on @var{socket}, the file name of a Unix-domain
socket. The default socket is
@file{@var{localstatedir}/daemon-socket/socket}. This option is only
useful in exceptional circumstances, such as if you need to run several
daemons on the same machine.
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
@node Application Setup
@section Application Setup
When using Guix on top of GNU/Linux distribution other than GuixSD, a
few additional steps are needed to get everything in place. Here are
some of them.
@subsection Locales
@cindex locales, when not on GuixSD
Packages installed @i{via} Guix will not use the host system's locale
data. Instead, you must first install one of the locale packages
available with Guix and then define the @code{LOCPATH} environment
variable (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library
Reference Manual}):
@example
$ guix package -i glibc-locales
$ export LOCPATH=$HOME/.guix-profile/lib/locale
@end example
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
110@tie{}MiB. Alternately, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
@subsection X11 Fonts
The majority of graphical applications use Fontconfig to locate and
load fonts and perform X11-client-side rendering. Guix's
@code{fontconfig} package looks for fonts in @file{$HOME/.guix-profile}
by default. Thus, to allow graphical applications installed with Guix
to display fonts, you will have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
@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. Two user interfaces are provided for
routine package management tasks: A command-line interface described below
(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user
interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
@menu
* 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.
@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{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
(note that Guix comes with an Emacs extension to shorten those file
Instead of referring to these directories, users have their own
@dfn{profile}, which points to the packages that they actually want to
use. These profiles are stored within each user's home directory, at
@code{$HOME/.guix-profile}.
For example, @code{alice} installs GCC 4.7.2. As a result,
@file{/home/alice/.guix-profile/bin/gcc} points to
@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
@code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
simply continues to point to
@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
coexist on the same system without any interference.
The @command{guix package} command is the central tool to manage
packages (@pxref{Invoking guix package}). 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 operation succeeds, or nothing happens. Thus, if the
@command{guix package} process 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. Similarly, the global
system configuration is subject to transactional upgrades and roll-back
(@pxref{Using the Configuration System}).
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
(@pxref{Invoking guix gc}). Users may also explicitly remove old
generations of their profile so that the packages they refer to can be
collected.
@cindex reproducibility
@cindex reproducible builds
Finally, Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
Each @file{/gnu/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. It also helps maximize @dfn{build reproducibility}:
thanks to the isolated build environments that are used, a given build
is likely to yield bit-identical files when performed on different
machines (@pxref{Invoking guix-daemon, container}).
This foundation allows Guix to support @dfn{transparent binary/source
deployment}. When a pre-built binary for a @file{/gnu/store} item is
available from an external source---a @dfn{substitute}, Guix just
downloads it and unpacks it;
otherwise, it builds the package from source, locally
(@pxref{Substitutes}).
Control over the build environment is a feature that is also useful for
developers. The @command{guix environment} command allows developers of
a package to quickly set up the right development environment for their
package, without having to manually install the package's dependencies
in their profile (@pxref{Invoking guix environment}).
@node Invoking guix package
@section Invoking @command{guix package}
The @command{guix package} command is 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}
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
previous @dfn{generations} of the profile remain available, should the user
want to roll back.
For example, to remove @code{lua} and install @code{guile} and
@code{guile-cairo} in a single transaction:
@example
guix package -r lua -i guile guile-cairo
@end example
@command{guix package} also supports a @dfn{declarative approach}
whereby the user specifies the exact set of packages to be available and
passes it @i{via} the @option{--manifest} option
(@pxref{profile-manifest, @option{--manifest}}).
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
variable, and so on.
@cindex search paths
If you are not using the Guix System Distribution, consider adding the
following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
shells get all the right environment variable definitions:
@example
GUIX_PROFILE="$HOME/.guix-profile" \
source "$HOME/.guix-profile/etc/profile"
@end example
In a multi-user setup, user profiles are stored in a place registered as
a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
to (@pxref{Invoking guix gc}). That directory is normally
@code{@var{localstatedir}/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
@code{--localstatedir}, and @var{user} is the user name. The
@file{per-user} directory is created when @command{guix-daemon} is
started, and the @var{user} sub-directory is created by @command{guix
package}.
The @var{options} can be among the following:
@item --install=@var{package} @dots{}
@itemx -i @var{package} @dots{}
Install the specified @var{package}s.
Each @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.8} or simply @code{guile-1.8} (in the latter
case, the newest version prefixed by @code{1.8} is selected.)
If no version number is specified, the
newest available version will be selected. 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{binutils-2.22:lib}
(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
name (and optionally version) are searched for among the GNU
distribution modules (@pxref{Package Modules}).
@cindex propagated inputs
Sometimes packages have @dfn{propagated inputs}: these are dependencies
that automatically get installed along with the required package
(@pxref{package-propagated-inputs, @code{propagated-inputs} in
@code{package} objects}, for information about propagated inputs in
package definitions).
An example is the GNU MPC library: its C header files refer to those of
the GNU MPFR library, which in turn refer to those of the GMP library.
Thus, when installing MPC, the MPFR and GMP libraries also get installed
in the profile; removing MPC also removes MPFR and GMP---unless they had
also been explicitly installed independently.
Besides, packages sometimes rely on the definition of environment
variables for their search paths (see explanation of
@code{--search-paths} below). Any missing or possibly incorrect
environment variable definitions are reported here.
@c XXX: keep me up-to-date
Finally, when installing a GNU package, the tool reports the
availability of a newer upstream version. In the future, it may provide
the option of installing directly from the upstream version, even if
that version is not yet in the distribution.
@item --install-from-expression=@var{exp}
@itemx -e @var{exp}
Install the package @var{exp} evaluates to.
@var{exp} must be a Scheme expression that evaluates to a
@code{<package>} object. This option is notably useful to disambiguate
between same-named variants of a package, with expressions such as
@code{(@@ (gnu packages base) guile-final)}.
Note that this option installs the first output of the specified
package, which may be insufficient when needing a specific output of a
multiple-output package.
@item --install-from-file=@var{file}
@itemx -f @var{file}
Install the package that the code within @var{file} evaluates to.
As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):
@example
@verbatiminclude package-hello.scm
@end example
Developers may find it useful to include such a @file{package.scm} file
in the root of their project's source tree that can be used to test
development snapshots and create reproducible development environments
(@pxref{Invoking guix environment}).
@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.
As for @code{--install}, each @var{package} may specify a version number
and/or output name in addition to the package name. For instance,
@code{-r glibc:debug} would remove the @code{debug} output of
@code{glibc}.
@item --upgrade[=@var{regexp} @dots{}]
@itemx -u [@var{regexp} @dots{}]
Upgrade all the installed packages. If one or more @var{regexp}s are
specified, upgrade only installed packages whose name matches a
@var{regexp}. Also see the @code{--do-not-upgrade} option below.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
you should regularly run @command{guix pull} (@pxref{Invoking guix
pull}).
@item --do-not-upgrade[=@var{regexp} @dots{}]
When used together with the @code{--upgrade} option, do @emph{not}
upgrade any packages whose name matches a @var{regexp}. For example, to
upgrade all packages in the current profile except those containing the
substring ``emacs'':
@example
$ guix package --upgrade . --do-not-upgrade emacs
@end example
@item @anchor{profile-manifest}--manifest=@var{file}
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
returned by the Scheme code in @var{file}.
This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--install} and similar
commands. The advantage is that @var{file} can be put under version
control, copied to different machines to reproduce the same profile, and
so on.
@c FIXME: Add reference to (guix profile) documentation when available.
@var{file} must return a @dfn{manifest} object, which is roughly a list
of packages:
(use-package-modules guile emacs)
@item --roll-back
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
When combined with options such as @code{--install}, roll back occurs
before any other actions.
Ludovic Courtès
committed
When rolling back from the first generation that actually contains
installed packages, the profile is made to point to the @dfn{zeroth
generation}, which contains no files apart from its own meta-data.
Ludovic Courtès
committed
Installing, removing, or upgrading packages from a generation that has
been rolled back to overwrites previous future generations. Thus, the
history of a profile's generations is always linear.
@item --switch-generation=@var{pattern}
@itemx -S @var{pattern}
Switch to a particular generation defined by @var{pattern}.
@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''. The latter means: move forward/backward by a
specified number of generations. For example, if you want to return to
the latest generation after @code{--roll-back}, use
@code{--switch-generation=+1}.
The difference between @code{--roll-back} and
@code{--switch-generation=-1} is that @code{--switch-generation} will
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
@item --search-paths[=@var{kind}]
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
needed in order to use the set of installed packages. These environment
variables are used to specify @dfn{search paths} for files used by some
of the installed packages.
For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
environment variables to be defined so it can look for headers and
libraries in the user's profile (@pxref{Environment Variables,,, gcc,
Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
library are installed in the profile, then @code{--search-paths} will
suggest setting these variables to @code{@var{profile}/include} and
@code{@var{profile}/lib}, respectively.
The typical use case is to define these environment variables in the
shell:
@example
$ eval `guix package --search-paths`
@end example
@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
meaning that the returned environment variable definitions will either
be exact settings, or prefixes or suffixes of the current value of these
variables. When omitted, @var{kind} defaults to @code{exact}.
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
Ludovic Courtès
committed
@item --verbose
Produce verbose output. In particular, emit the environment's build log
on the standard error port.
@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:
@item --search=@var{regexp}
@itemx -s @var{regexp}
List the available packages whose name, synopsis, or description matches
@var{regexp}. Print all the meta-data of matching packages in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
GNU recutils manual}).
This allows specific fields to be extracted using the @command{recsel}
command, for instance:
@example
$ guix package -s malloc | recsel -p name,version
name: glibc
version: 2.17
name: libgc
version: 7.2alpha6
@end example
Similarly, to show the name of all the packages available under the
terms of the GNU@tie{}LGPL version 3:
@example
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils
name: gmp
@dots{}
@end example
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
@item --show=@var{package}
Show details about @var{package}, taken from the list of available packages, in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
recutils manual}).
@example
$ guix package --show=python | recsel -p name,version
name: python
version: 2.7.6
name: python
version: 3.3.5
@end example
You may also specify the full name of a package to only get details about a
specific version of it:
@example
$ guix package --show=python-3.3.5 | recsel -p name,version
name: python
version: 3.3.5
@end example
@item --list-installed[=@var{regexp}]
@itemx -I [@var{regexp}]
List the currently installed packages in the specified profile, with the
most recently installed packages shown last. 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 distribution for this system
(@pxref{GNU 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, the parts of the package (@pxref{Packages with
Multiple Outputs}), and the source location of its definition.
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
Return a list of generations along with their creation dates; for each
generation, show the installed packages, with the most recently
installed packages shown last. Note that the zeroth generation is never
shown.
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
For each installed package, print the following items, separated by
tabs: the name of a package, its version string, the part of the package
that is installed (@pxref{Packages with Multiple Outputs}), and the
location of this package in the store.
When @var{pattern} is used, the command returns only matching
generations. Valid patterns include:
@itemize
@item @emph{Integers and comma-separated integers}. Both patterns denote
generation numbers. For instance, @code{--list-generations=1} returns
the first one.
And @code{--list-generations=1,8,2} outputs three generations in the
specified order. Neither spaces nor trailing commas are allowed.
@item @emph{Ranges}. @code{--list-generations=2..9} prints the
specified generations and everything in between. Note that the start of
a range must be lesser than its end.
It is also possible to omit the endpoint. For example,
@code{--list-generations=2..}, returns all generations starting from the
second one.
@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
or months by passing an integer along with the first letter of the
Ludovic Courtès
committed
duration. For example, @code{--list-generations=20d} lists generations
that are up to 20 days old.
@end itemize
@item --delete-generations[=@var{pattern}]
@itemx -d [@var{pattern}]
Ludovic Courtès
committed
When @var{pattern} is omitted, delete all generations except the current
one.
This command accepts the same patterns as @option{--list-generations}.
Ludovic Courtès
committed
When @var{pattern} is specified, delete the matching generations. When
@var{pattern} specifies a duration, generations @emph{older} than the
specified duration match. For instance, @code{--delete-generations=1m}
deletes generations that are more than one month old.
If the current generation matches, it is @emph{not} deleted. Also, the
zeroth generation is never deleted.
Note that deleting generations prevents roll-back to them.
Consequently, this command must be used with care.
Finally, since @command{guix package} may actually start build
processes, it supports all the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
@node Substitutes
@section Substitutes
@cindex substitutes
@cindex pre-built binaries
Guix supports transparent source/binary deployment, which means that it
can either build things locally, or download pre-built items from a
server. We call these pre-built items @dfn{substitutes}---they are
substitutes for local build results. In many cases, downloading a
substitute is much faster than building things locally.
Substitutes can be anything resulting from a derivation build
(@pxref{Derivations}). Of course, in the common case, they are
pre-built package binaries, but source tarballs, for instance, which
also result from derivation builds, can be available as substitutes.
The @code{hydra.gnu.org} server is a front-end to a build farm that
builds packages from the GNU distribution continuously for some
architectures, and makes them available as substitutes. This is the
default source of substitutes; it can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
or to client tools such as @command{guix package}
(@pxref{client-substitute-urls,, client @option{--substitute-urls}
option}).
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
@cindex security
@cindex digital signatures
To allow Guix to download substitutes from @code{hydra.gnu.org}, you
must add its public key to the access control list (ACL) of archive
imports, using the @command{guix archive} command (@pxref{Invoking guix
archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
be compromised and to serve genuine substitutes.
This public key is installed along with Guix, in
@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
the installation prefix of Guix. If you installed Guix from source,
make sure you checked the GPG signature of
@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
Then, you can run something like this:
@example
# guix archive --authorize < hydra.gnu.org.pub
@end example
Once this is in place, the output of a command like @code{guix build}
should change from something like:
@example
$ guix build emacs --dry-run
The following derivations would be built:
/gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
/gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
/gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
/gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
@dots{}
@end example
@noindent
to something like:
@example
$ guix build emacs --dry-run
The following files would be downloaded:
/gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
/gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
/gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
/gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
@dots{}
@end example
@noindent
This indicates that substitutes from @code{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.
Guix ignores substitutes that are not signed, or that are not signed by
one of the keys listed in the ACL. It also detects and raises an error
when attempting to use a substitute that has been tampered with.
The substitute mechanism can be disabled globally by running
@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
guix-daemon}). It can also be disabled temporarily by passing the
@code{--no-substitutes} option to @command{guix package}, @command{guix
build}, and other command-line tools.
Today, each individual's control over their own computing is at the
mercy of institutions, corporations, and groups with enough power and
determination to subvert the computing infrastructure and exploit its
weaknesses. While using @code{hydra.gnu.org} substitutes can be
convenient, we encourage users to also build on their own, or even run
their own build farm, such that @code{hydra.gnu.org} is less of an
interesting target. One way to help is by publishing the software you
build using @command{guix publish} so that others have one more choice
of server to download substitutes from (@pxref{Invoking guix publish}).
Guix has the foundations to maximize build reproducibility
(@pxref{Features}). In most cases, independent builds of a given
package or derivation should yield bit-identical results. Thus, through
a diverse set of independent package builds, we can strengthen the
integrity of our systems.
In the future, we want Guix to have support to publish and retrieve
binaries to/from other users, in a peer-to-peer fashion. If you would
like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
@node Packages with Multiple Outputs
@section Packages with Multiple Outputs
@cindex multiple-output packages
@cindex package outputs
Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads exactly one directory in the store. When running
@command{guix package -i glibc}, one installs the default output of the
GNU libc package; the default output is called @code{out}, but its name
can be omitted as shown in this command. In this particular case, the
default output of @code{glibc} contains all the C header files, shared
libraries, static libraries, Info documentation, and other supporting
files.
Sometimes it is more appropriate to separate the various types of files
produced from a single source package into separate outputs. For
instance, the GLib C library (used by GTK+ and related packages)
installs more than 20 MiB of reference documentation as HTML pages.
To save space for users who do not need it, the documentation goes to a
separate output, called @code{doc}. To install the main GLib output,
which contains everything but the documentation, one would run:
@example
guix package -i glib
@end example
The command to install its documentation is:
@example
guix package -i glib:doc
@end example
Some packages install programs with different ``dependency footprints''.
For instance, the WordNet package install both command-line tools and
graphical user interfaces (GUIs). The former depend solely on the C
library, whereas the latter depend on Tcl/Tk and the underlying X
libraries. In this case, we leave the command-line tools in the default
output, whereas the GUIs are in a separate output. This allows users
who do not need the GUIs to save space. The @command{guix size} command
can help find out about such situations (@pxref{Invoking guix size}).
@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
There are several such multiple-output packages in the GNU distribution.
Other conventional output names include @code{lib} for libraries and
possibly header files, @code{bin} for stand-alone programs, and
@code{debug} for debugging information (@pxref{Installing Debugging
Files}). The outputs of a packages are listed in the third column of
the output of @command{guix package --list-available} (@pxref{Invoking
guix package}).
@node Invoking guix gc
@section Invoking @command{guix gc}
@cindex garbage collector
Packages that are installed but not used may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
collector to reclaim space from the @file{/gnu/store} directory. It is
the @emph{only} way to remove files from @file{/gnu/store}---removing
files or directories manually may break it beyond repair!
The garbage collector has a set of known @dfn{roots}: any file under
@file{/gnu/store} reachable from a root is considered @dfn{live} and
cannot be deleted; any other file is considered @dfn{dead} and may be
deleted. The set of garbage collector roots includes default user
profiles, and may be augmented with @command{guix build --root}, for
example (@pxref{Invoking guix build}).
Prior to running @code{guix gc --collect-garbage} to make space, it is
often useful to remove old generations from user profiles; that way, old
package builds referenced by those generations can be reclaimed. This
is achieved by running @code{guix package --delete-generations}
(@pxref{Invoking guix package}).
The @command{guix gc} command has three modes of operation: it can be
used to garbage-collect any dead files (the default), to delete specific
files (the @code{--delete} option), to print garbage-collector
information, or for more advanced queries. The garbage collection
options are as follows:
@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Collect garbage---i.e., unreachable @file{/gnu/store} files and
sub-directories. This is the default operation when no option is
specified.
When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
When @var{min} is omitted, collect all the garbage.
@item --delete
@itemx -d
Attempt to delete all the store files and directories specified as
arguments. This fails if some of the files are not in the store, or if
they are still live.
@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.
@item --list-live
Show the list of live store files and directories.
@end table
In addition, the references among existing store files can be queried:
@table @code
@item --references
@itemx --referrers
List the references (respectively, the referrers) of store files given
as arguments.
List the requisites of the store files passed as arguments. Requisites
include the store files themselves, their references, and the references
of these, recursively. In other words, the returned list is the
@dfn{transitive closure} of the store files.
@xref{Invoking guix size}, for a tool to profile the size of an
element's closure. @xref{Invoking guix graph}, for a tool to visualize
the graph of references.
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
Lastly, the following options allow you to check the integrity of the
store and to control disk usage.
@table @option
@item --verify[=@var{options}]
@cindex integrity, of the store
@cindex integrity checking
Verify the integrity of the store.
By default, make sure that all the store items marked as valid in the
daemon's database actually exist in @file{/gnu/store}.
When provided, @var{options} must a comma-separated list containing one
or more of @code{contents} and @code{repair}.
When passing @option{--verify=contents}, the daemon will compute the
content hash of each store item and compare it against its hash in the
database. Hash mismatches are reported as data corruptions. Because it
traverses @emph{all the files in the store}, this command can take a
long time, especially on systems with a slow disk drive.
@cindex repairing the store
Using @option{--verify=repair} or @option{--verify=contents,repair}
causes the daemon to try to repair corrupt store items by fetching
substitutes for them (@pxref{Substitutes}). Because repairing is not
atomic, and thus potentially dangerous, it is available only to the
system administrator.
@item --optimize
@cindex deduplication
Optimize the store by hard-linking identical files---this is
@dfn{deduplication}.
The daemon performs deduplication after each successful build or archive
import, unless it was started with @code{--disable-deduplication}
(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
this option is primarily useful when the daemon was running with
@code{--disable-deduplication}.
@end table
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
@node Invoking guix pull
@section Invoking @command{guix pull}
Packages are installed or upgraded to the latest version available in
the distribution currently available on your local machine. To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
descriptions, and deploys it.
On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix. Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
version. New @command{guix} sub-commands added by the update also
become available.
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
@table @code
@item --verbose
Produce verbose output, writing build logs to the standard error output.
@item --url=@var{url}
Download the source tarball of Guix from @var{url}.
By default, the tarball is taken from its canonical address at
@code{gnu.org}, for the stable branch of Guix.
@item --bootstrap
Use the bootstrap Guile to build the latest Guix. This option is only
useful to Guix developers.
@end table
@node Invoking guix archive
@section Invoking @command{guix archive}
The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them.
In particular, it allows store files to be transferred from one machine
to another machine's store. For example, to transfer the @code{emacs}
package to a machine connected over SSH, one would run:
@example
guix archive --export -r emacs | ssh the-machine guix archive --import
Similarly, a complete user profile may be transferred from one machine
to another like this:
@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
ssh the-machine guix-archive --import
@end example
@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the target
machine's store. The @code{--missing} option can help figure out which
items are missing from the target's store.
Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
comparable in spirit to `tar', but with a few noteworthy differences
that make it more appropriate for our purposes. First, rather than
recording all Unix meta-data for each file, the Nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed. Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order. This makes archive production fully
deterministic.
When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended. When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.
The main options are:
@table @code
@item --export
Export the specified store files or packages (see below.) Write the
resulting archive to the standard output.
Dependencies are @emph{not} included in the output, unless
@code{--recursive} is passed.
@item -r
@itemx --recursive
When combined with @code{--export}, this instructs @command{guix
archive} to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.
@item --import
Read an archive from the standard input, and import the files listed
therein into the store. Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
keys (see @code{--authorize} below.)
@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.
@item --generate-key[=@var{parameters}]
Generate a new key pair for the daemons. This is a prerequisite before
archives can be exported with @code{--export}. Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.
The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret.) When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternately, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).
@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.
The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}. The file contains
@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@end table
To export store files as an archive to the standard output, run:
@example
guix archive --export @var{options} @var{specifications}...
@end example
@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}). For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:
@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example
If the specified packages are not built yet, @command{guix archive}
automatically builds them. The build process may be controlled with the
same options that can be passed to the @command{guix build} command
(@pxref{Invoking guix build, common build options}).
@c *********************************************************************
@include emacs.texi
@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 by the Guix daemon, on behalf of users. In a
standard setup, the daemon has write access to the store---the
@file{/gnu/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. The term ``derivation'' comes from the fact
that build results @emph{derive} from them.
This chapter describes all these APIs in turn, starting from high-level
package definitions.
* 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.
@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-module (gnu packages hello)
#:use-module (guix packages)
#:use-module (guix download)
#:use-module (guix build-system gnu)
#:use-module (guix licenses)
#:use-module (gnu packages gawk))
(define-public hello
(package
(name "hello")
(method url-fetch)
(uri (string-append "mirror://gnu/hello/hello-" version
".tar.gz"))
(sha256
(base32
"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system)
(arguments `(#:configure-flags '("--enable-silent-rules")))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
(home-page "http://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here. This expression binds variable @code{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"}.
With luck, you may be able to import part or all of the definition of
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).
In the example above, @var{hello} is defined into a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
the command-line tools (@pxref{Package Modules}).
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
(@pxref{origin Reference}, for the complete reference).
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. You can obtain this information with
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).
@cindex patches
When needed, the @code{origin} form can also have a @code{patches} field
listing patches to be applied, and a @code{snippet} field giving a
Scheme expression to modify the source code.
@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
package (@pxref{Build Systems}). Here, @var{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.
@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}). Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag.
@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 (@pxref{Build Systems}).
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
Taylan Ulrich Bayırlı/Kammer
committed
@xref{package Reference}, for a full description of possible fields.
Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}). You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
Eventually, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).
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{/gnu/store}.
The build actions it 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 @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).
@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
@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:
@deffn {Scheme Procedure} package-cross-derivation @var{store} @
@var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn
Taylan Ulrich Bayırlı/Kammer
committed
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
@menu
* package Reference :: The package data type.
* origin Reference:: The origin data type.
@end menu
@node package Reference
@subsection @code{package} Reference
This section summarizes all the options available in @code{package}
declarations (@pxref{Defining Packages}).
@deftp {Data Type} package
This is the data type representing a package recipe.
@table @asis
@item @code{name}
The name of the package, as a string.
@item @code{version}
The version of the package, as a string.
@item @code{source}
An origin object telling how the source code for the package should be
acquired (@pxref{origin Reference}).
@item @code{build-system}
The build system that should be used to build the package (@pxref{Build
Systems}).
@item @code{arguments} (default: @code{'()})
The arguments that should be passed to the build system. This is a
list, typically containing sequential keyword-value pairs.
@item @code{inputs} (default: @code{'()})
Package or derivation inputs to the build. This is a list of lists,
where each list has the name of the input (a string) as its first
element, a package or derivation object as its second element, and
optionally the name of the output of the package or derivation that
should be used, which defaults to @code{"out"}.
@item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()})
@cindex propagated inputs
Taylan Ulrich Bayırlı/Kammer
committed
This field is like @code{inputs}, but the specified packages will be
force-installed alongside the package they belong to
(@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
information on how @command{guix package} deals with propagated inputs.)
For example this is necessary when a library needs headers of another
library to compile, or needs another shared library to be linked
alongside itself when a program wants to link to it.
Taylan Ulrich Bayırlı/Kammer
committed
@item @code{native-inputs} (default: @code{'()})
This field is like @code{inputs}, but in case of a cross-compilation it
will be ensured that packages for the architecture of the build machine
are present, such that executables from them can be used during the
build.
This is typically where you would list tools needed at build time but
not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
Bison. @command{guix lint} can report likely mistakes in this area
(@pxref{Invoking guix lint}).
Taylan Ulrich Bayırlı/Kammer
committed
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
@item @code{self-native-input?} (default: @code{#f})
This is a Boolean field telling whether the package should use itself as
a native input when cross-compiling.
@item @code{outputs} (default: @code{'("out")})
The list of output names of the package. @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.
@item @code{native-search-paths} (default: @code{'()})
@itemx @code{search-paths} (default: @code{'()})
A list of @code{search-path-specification} objects describing
search-path environment variables honored by the package.
@item @code{replacement} (default: @code{#f})
This must either @code{#f} or a package object that will be used as a
@dfn{replacement} for this package. @xref{Security Updates, grafts},
for details.
@item @code{synopsis}
A one-line description of the package.
@item @code{description}
A more elaborate description of the package.
@item @code{license}
The license of the package; a value from @code{(guix licenses)}.
@item @code{home-page}
The URL to the home-page of the package, as a string.
@item @code{supported-systems} (default: @var{%supported-systems})
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.
Loading
Loading full blame...