You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
12377 lines
467 KiB
12377 lines
467 KiB
\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
|
|
|
|
@c Identifier of the OpenPGP key used to sign tarballs and such.
|
|
@set OPENPGP-SIGNING-KEY-ID 090B11993D9AEBB5
|
|
|
|
@copying
|
|
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
|
|
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
|
|
Copyright @copyright{} 2013 Nikita Karetnikov@*
|
|
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
|
|
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
|
|
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
|
|
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
|
|
Copyright @copyright{} 2015, 2016 Leo Famulari@*
|
|
Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
|
|
Copyright @copyright{} 2016 Ben Woodcroft@*
|
|
Copyright @copyright{} 2016 Chris Marusich@*
|
|
Copyright @copyright{} 2016 Efraim Flashner@*
|
|
Copyright @copyright{} 2016 John Darrington@*
|
|
Copyright @copyright{} 2016 ng0
|
|
|
|
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 System administration
|
|
@direntry
|
|
* Guix: (guix). Manage installed software and system configuration.
|
|
* guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
|
|
* guix build: (guix)Invoking guix build. Building packages.
|
|
* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
|
|
* guix pull: (guix)Invoking guix pull. Update the list of available packages.
|
|
* guix system: (guix)Invoking guix system. Manage the operating system configuration.
|
|
@end direntry
|
|
|
|
@dircategory Software development
|
|
@direntry
|
|
* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
|
|
@end direntry
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Guix user interface: (guix)Emacs Interface. Package management from the comfort of Emacs.
|
|
@end direntry
|
|
|
|
|
|
@titlepage
|
|
@title GNU Guix Reference Manual
|
|
@subtitle Using the GNU Guix Functional Package Manager
|
|
@author The GNU Guix Developers
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Edition @value{EDITION} @*
|
|
@value{UPDATED} @*
|
|
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@c *********************************************************************
|
|
@node Top
|
|
@top GNU Guix
|
|
|
|
This document describes GNU Guix version @value{VERSION}, a functional
|
|
package management tool written for the GNU system.
|
|
|
|
@menu
|
|
* Introduction:: What is Guix about?
|
|
* Installation:: Installing Guix.
|
|
* Package Management:: Package installation, upgrade, etc.
|
|
* Emacs Interface:: Using Guix from Emacs.
|
|
* Programming Interface:: Using Guix in Scheme.
|
|
* Utilities:: Package management commands.
|
|
* GNU Distribution:: Software for your friendly GNU system.
|
|
* Contributing:: Your help needed!
|
|
|
|
* Acknowledgments:: Thanks!
|
|
* GNU Free Documentation License:: The license of this manual.
|
|
* Concept Index:: Concepts.
|
|
* Programming Index:: Data types, functions, and variables.
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Installation
|
|
|
|
* Binary Installation:: Getting Guix running in no time!
|
|
* Requirements:: Software needed to build and run Guix.
|
|
* Running the Test Suite:: Testing Guix.
|
|
* Setting Up the Daemon:: Preparing the build daemon's environment.
|
|
* Invoking guix-daemon:: Running the build daemon.
|
|
* Application Setup:: Application-specific setup.
|
|
|
|
Setting Up the Daemon
|
|
|
|
* Build Environment Setup:: Preparing the isolated build environment.
|
|
* Daemon Offload Setup:: Offloading builds to remote machines.
|
|
|
|
Package Management
|
|
|
|
* Features:: How Guix will make your life brighter.
|
|
* Invoking guix package:: Package installation, removal, etc.
|
|
* Substitutes:: Downloading pre-built binaries.
|
|
* Packages with Multiple Outputs:: Single source package, multiple outputs.
|
|
* Invoking guix gc:: Running the garbage collector.
|
|
* Invoking guix pull:: Fetching the latest Guix and distribution.
|
|
* Invoking guix archive:: Exporting and importing store files.
|
|
|
|
Emacs Interface
|
|
|
|
* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
|
|
* Package Management: Emacs Package Management. Managing packages and generations.
|
|
* Licenses: Emacs Licenses. Interface for licenses of Guix packages.
|
|
* Package Source Locations: Emacs Package Locations. Interface for package location files.
|
|
* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
|
|
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
|
|
* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
|
|
* Completions: Emacs Completions. Completing @command{guix} shell command.
|
|
* Development: Emacs Development. Tools for Guix developers.
|
|
* Hydra: Emacs Hydra. Interface for Guix build farm.
|
|
|
|
Programming Interface
|
|
|
|
* Defining Packages:: Defining new packages.
|
|
* Build Systems:: Specifying how packages are built.
|
|
* The Store:: Manipulating the package store.
|
|
* Derivations:: Low-level interface to package derivations.
|
|
* The Store Monad:: Purely functional interface to the store.
|
|
* G-Expressions:: Manipulating build expressions.
|
|
|
|
Defining Packages
|
|
|
|
* package Reference:: The package data type.
|
|
* origin Reference:: The origin data type.
|
|
|
|
Utilities
|
|
|
|
* Invoking guix build:: Building packages from the command line.
|
|
* Invoking guix edit:: Editing package definitions.
|
|
* Invoking guix download:: Downloading a file and printing its hash.
|
|
* Invoking guix hash:: Computing the cryptographic hash of a file.
|
|
* Invoking guix import:: Importing package definitions.
|
|
* Invoking guix refresh:: Updating package definitions.
|
|
* Invoking guix lint:: Finding errors in package definitions.
|
|
* Invoking guix size:: Profiling disk usage.
|
|
* Invoking guix graph:: Visualizing the graph of packages.
|
|
* Invoking guix environment:: Setting up development environments.
|
|
* Invoking guix publish:: Sharing substitutes.
|
|
* Invoking guix challenge:: Challenging substitute servers.
|
|
* Invoking guix container:: Process isolation.
|
|
|
|
Invoking @command{guix build}
|
|
|
|
* Common Build Options:: Build options for most commands.
|
|
* Package Transformation Options:: Creating variants of packages.
|
|
* Additional Build Options:: Options specific to 'guix build'.
|
|
|
|
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 Installation
|
|
|
|
* Limitations:: What you can expect.
|
|
* Hardware Considerations:: Supported hardware.
|
|
* USB Stick Installation:: Preparing the installation medium.
|
|
* Preparing for Installation:: Networking, partitioning, etc.
|
|
* Proceeding with the Installation:: The real thing.
|
|
* Installing GuixSD in a VM:: GuixSD playground.
|
|
* Building the Installation Image:: How this comes to be.
|
|
|
|
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.
|
|
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
|
|
* Defining Services:: Adding new service definitions.
|
|
|
|
Services
|
|
|
|
* Base Services:: Essential system services.
|
|
* Scheduled Job Execution:: The mcron service.
|
|
* Networking Services:: Network setup, SSH daemon, etc.
|
|
* X Window:: Graphical display.
|
|
* Desktop Services:: D-Bus and desktop services.
|
|
* Database Services:: SQL databases.
|
|
* Mail Services:: IMAP, POP3, SMTP, and all that.
|
|
* Web Services:: Web servers.
|
|
* Miscellaneous Services:: Other services.
|
|
|
|
Defining Services
|
|
|
|
* Service Composition:: The model for composing services.
|
|
* Service Types and Services:: Types and services.
|
|
* Service Reference:: API reference.
|
|
* Shepherd Services:: A particular type of service.
|
|
|
|
Packaging Guidelines
|
|
|
|
* Software Freedom:: What may go into the distribution.
|
|
* Package Naming:: What's in a name?
|
|
* Version Numbers:: When the name is not enough.
|
|
* Synopses and Descriptions:: Helping users find the right package.
|
|
* Python Modules:: Taming the snake.
|
|
* Perl Modules:: Little pearls.
|
|
* Java Packages:: Coffee break.
|
|
* Fonts:: Fond of fonts.
|
|
|
|
Contributing
|
|
|
|
* Building from Git:: The latest and greatest.
|
|
* Running Guix Before It Is Installed:: Hacker tricks.
|
|
* The Perfect Setup:: The right tools.
|
|
* Coding Style:: Hygiene of the contributor.
|
|
* Submitting Patches:: Share your work.
|
|
|
|
Coding Style
|
|
|
|
* Programming Paradigm:: How to compose your elements.
|
|
* Modules:: Where to store your code?
|
|
* Data Types and Pattern Matching:: Implementing data structures.
|
|
* Formatting Code:: Writing conventions.
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@c *********************************************************************
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
@cindex purpose
|
|
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
|
|
using the international phonetic alphabet (IPA).} is a package
|
|
management tool for the GNU system. Guix makes it easy for unprivileged
|
|
users to install, upgrade, or remove packages, to roll back to a
|
|
previous package set, to build packages from source, and generally
|
|
assists with the creation and maintenance of software environments.
|
|
|
|
@cindex user interfaces
|
|
Guix provides a command-line package management interface
|
|
(@pxref{Invoking guix package}), a set of command-line utilities
|
|
(@pxref{Utilities}), a visual user interface in Emacs (@pxref{Emacs
|
|
Interface}), as well as Scheme programming interfaces
|
|
(@pxref{Programming Interface}).
|
|
@cindex build daemon
|
|
Its @dfn{build daemon} is responsible for building packages on behalf of
|
|
users (@pxref{Setting Up the Daemon}) and for downloading pre-built
|
|
binaries from authorized sources (@pxref{Substitutes}).
|
|
|
|
@cindex extensibility of the distribution
|
|
@cindex customization of packages
|
|
Guix includes package definitions for many GNU and non-GNU packages, all
|
|
of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
|
|
user's computing freedom}. It is @emph{extensible}: users can write
|
|
their own package definitions (@pxref{Defining Packages}) and make them
|
|
available as independent package modules (@pxref{Package Modules}). It
|
|
is also @emph{customizable}: users can @emph{derive} specialized package
|
|
definitions from existing ones, including from the command line
|
|
(@pxref{Package Transformation Options}).
|
|
|
|
@cindex Guix System Distribution
|
|
@cindex GuixSD
|
|
You can install GNU@tie{}Guix on top of an existing GNU/Linux system
|
|
where it complements the available tools without interference
|
|
(@pxref{Installation}), or you can use it as part of the standalone
|
|
@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
|
|
With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
|
|
system configuration and Guix takes care of instantiating the
|
|
configuration in a transactional, reproducible, and stateless fashion
|
|
(@pxref{System Configuration}).
|
|
|
|
@cindex functional package management
|
|
Under the hood, Guix implements the @dfn{functional package management}
|
|
discipline pioneered by Nix (@pxref{Acknowledgments}).
|
|
In Guix, the package build and installation process is seen
|
|
as a @emph{function}, in the mathematical sense. That function takes inputs,
|
|
such as build scripts, a compiler, and libraries, and
|
|
returns an installed package. As a pure function, its result depends
|
|
solely on its inputs---for instance, it cannot refer to software or
|
|
scripts that were not explicitly passed as inputs. A build function
|
|
always produces the same result when passed a given set of inputs. It
|
|
cannot alter the environment of the running system in
|
|
any way; for instance, it cannot create, modify, or delete files outside
|
|
of its build and installation directories. This is achieved by running
|
|
build processes in isolated environments (or @dfn{containers}), where only their
|
|
explicit inputs are visible.
|
|
|
|
@cindex store
|
|
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 for the salient features of Guix: support
|
|
for transactional package upgrade and rollback, per-user installation, and
|
|
garbage collection of packages (@pxref{Features}).
|
|
|
|
|
|
@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}.
|
|
|
|
@cindex foreign distro
|
|
When installed on a running GNU/Linux system---thereafter called a
|
|
@dfn{foreign distro}---GNU@tie{}Guix complements the available tools
|
|
without interference. Its data lives exclusively in two directories,
|
|
usually @file{/gnu/store} and @file{/var/guix}; other files on your
|
|
system, such as @file{/etc}, are left untouched.
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Binary Installation
|
|
@section Binary Installation
|
|
|
|
This section describes how to install Guix on an arbitrary system from a
|
|
self-contained tarball providing binaries for Guix and for all its
|
|
dependencies. This is often quicker than installing from source, which
|
|
is described in the next sections. The only requirement is to have
|
|
GNU@tie{}tar and Xz.
|
|
|
|
Installing goes along these lines:
|
|
|
|
@enumerate
|
|
@item
|
|
Download the binary tarball from
|
|
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
|
|
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
|
|
already running the kernel Linux, and so on.
|
|
|
|
@c The following is somewhat duplicated in ``System Installation''.
|
|
Make sure to download the associated @file{.sig} file and to verify the
|
|
authenticity of the tarball against it, along these lines:
|
|
|
|
@example
|
|
$ wget ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
|
|
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
|
|
@end example
|
|
|
|
If that command fails because you do not have the required public key,
|
|
then run this command to import it:
|
|
|
|
@example
|
|
$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
|
|
@end example
|
|
|
|
@noindent
|
|
and rerun the @code{gpg --verify} command.
|
|
@c end authentication part
|
|
|
|
@item
|
|
As @code{root}, run:
|
|
|
|
@example
|
|
# cd /tmp
|
|
# 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}).
|
|
|
|
@item
|
|
Run the daemon, and set it to automatically start on boot.
|
|
|
|
If your host distro uses the systemd init system, this can be achieved
|
|
with these commands:
|
|
|
|
@example
|
|
# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
|
|
/etc/systemd/system/
|
|
# systemctl start guix-daemon && systemctl enable guix-daemon
|
|
@end example
|
|
|
|
If your host distro uses the Upstart init system:
|
|
|
|
@example
|
|
# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
|
|
# start guix-daemon
|
|
@end example
|
|
|
|
Otherwise, you can still start the daemon manually with:
|
|
|
|
@example
|
|
# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
|
|
@end example
|
|
|
|
@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
|
|
@end example
|
|
|
|
It is also a good idea to make the Info version of this manual available
|
|
there:
|
|
|
|
@example
|
|
# mkdir -p /usr/local/share/info
|
|
# cd /usr/local/share/info
|
|
# for i in /var/guix/profiles/per-user/root/guix-profile/share/info/* ;
|
|
do ln -s $i ; done
|
|
@end example
|
|
|
|
That way, assuming @file{/usr/local/share/info} is in the search path,
|
|
running @command{info guix} will open this manual (@pxref{Other Info
|
|
Directories,,, texinfo, GNU Texinfo}, for more details on changing the
|
|
Info search path.)
|
|
|
|
@item
|
|
To use substitutes from @code{hydra.gnu.org} or one of its mirrors
|
|
(@pxref{Substitutes}), authorize them:
|
|
|
|
@example
|
|
# guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
|
|
@end example
|
|
@end enumerate
|
|
|
|
This completes root-level install of Guix. Each user will need to
|
|
perform additional steps to make their Guix environment ready for use,
|
|
@pxref{Application Setup}.
|
|
|
|
You can confirm that Guix is working by installing a sample package into
|
|
the root profile:
|
|
|
|
@example
|
|
# guix package -i hello
|
|
@end example
|
|
|
|
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. In other words, do not remove @code{guix} by running
|
|
@code{guix package -r guix}.
|
|
|
|
The binary installation tarball 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
|
|
@item
|
|
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to
|
|
access @code{https} URLs for substitutes, which is highly recommended
|
|
(@pxref{Substitutes}). It also allows you to access 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. @xref{Guile Preparations, how to install the GnuTLS bindings
|
|
for Guile,, gnutls-guile, GnuTLS-Guile}.
|
|
|
|
@item
|
|
Installing
|
|
@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
|
|
When @url{http://zlib.net, zlib} is available, @command{guix publish}
|
|
can compress build byproducts (@pxref{Invoking guix publish}).
|
|
@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.
|
|
@end itemize
|
|
|
|
When configuring Guix on a system that already has a Guix installation,
|
|
be sure to specify the same state directory as the existing installation
|
|
using the @code{--localstatedir} option of the @command{configure}
|
|
script (@pxref{Directory Variables, @code{localstatedir},, standards,
|
|
GNU Coding Standards}). The @command{configure} script protects against
|
|
unintended misconfiguration of @var{localstatedir} so you do not
|
|
inadvertently corrupt your store (@pxref{The Store}).
|
|
|
|
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,
|
|
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
|
|
@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}.
|
|
Note that @code{--disable-daemon} is not required if
|
|
your goal is to share the store with Nix.
|
|
|
|
@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.
|
|
|
|
It is also possible to run a subset of the tests by defining the
|
|
@code{TESTS} makefile variable as in this example:
|
|
|
|
@example
|
|
make check TESTS="tests/store.scm tests/cpio.scm"
|
|
@end example
|
|
|
|
By default, tests results are displayed at a file level. In order to
|
|
see the details of every individual test cases, it is possible to define
|
|
the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
|
|
|
|
@example
|
|
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
|
|
@end example
|
|
|
|
Upon failure, please email @email{bug-guix@@gnu.org} and attach the
|
|
@file{test-suite.log} file. Please specify the Guix version being used
|
|
as well as version numbers of the dependencies (@pxref{Requirements}) in
|
|
your message.
|
|
|
|
Guix also comes with a whole-system test suite that tests complete
|
|
GuixSD operating system instances. It can only run on systems where
|
|
Guix is already installed, using:
|
|
|
|
@example
|
|
make check-system
|
|
@end example
|
|
|
|
@noindent
|
|
or, again, by defining @code{TESTS} to select a subset of tests to run:
|
|
|
|
@example
|
|
make check-system TESTS="basic mcron"
|
|
@end example
|
|
|
|
These system tests are defined in the @code{(gnu tests @dots{})}
|
|
modules. They work by running the operating systems under test with
|
|
lightweight instrumentation in a virtual machine (VM). They can be
|
|
computationally intensive or rather cheap, depending on whether
|
|
substitutes are available for their dependencies (@pxref{Substitutes}).
|
|
Some of them require a lot of storage space to hold VM images.
|
|
|
|
Again in case of test failures, please send @email{bug-guix@@gnu.org}
|
|
all the details.
|
|
|
|
@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. See 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.
|
|
@example
|
|
# groupadd --system guixbuild
|
|
# for i in `seq -w 1 10`;
|
|
do
|
|
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}}). To use
|
|
@command{guix system vm} and related commands, you may need to add the
|
|
build users to the @code{kvm} group so they can access @file{/dev/kvm},
|
|
using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
|
|
(@pxref{Invoking guix system}).
|
|
|
|
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. Similarly, if your
|
|
machine uses the Upstart init system, drop the
|
|
@file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
|
|
file in @file{/etc/init}.}:
|
|
|
|
@example
|
|
# guix-daemon --build-users-group=guixbuild
|
|
@end example
|
|
|
|
@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 processes of the container
|
|
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
|
|
|
|
You can influence the directory where the daemon stores build trees
|
|
@i{via} the @code{TMPDIR} environment variable. However, the build tree
|
|
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
|
|
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
|
|
This way, the value of @code{TMPDIR} does not leak inside build
|
|
environments, which avoids discrepancies in cases where build processes
|
|
capture the name of their build tree.
|
|
|
|
@vindex http_proxy
|
|
The daemon also honors the @code{http_proxy} environment variable for
|
|
HTTP downloads it performs, be it for fixed-output derivations
|
|
(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
|
|
|
|
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}; every time a build is requested, for
|
|
instance via @code{guix build}, the daemon attempts to offload it to one
|
|
of the machines that satisfy the constraints of the derivation, 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")
|
|
"/.lsh/identity-for-guix"))))
|
|
@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 to which the daemon may offload
|
|
builds. The important fields are:
|
|
|
|
@table @code
|
|
|
|
@item name
|
|
The host name of the remote machine.
|
|
|
|
@item system
|
|
The system type of the remote machine---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:
|
|
|
|
@table @code
|
|
|
|
@item port
|
|
Port number of SSH server on the machine (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
|
|
@end deftp
|
|
|
|
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 is 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}).
|
|
|
|
@item --no-substitutes
|
|
@cindex substitutes
|
|
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{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
|
|
(@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).
|
|
|
|
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.
|
|
|
|
When this option is used, @command{guix gc --list-failures} can be used
|
|
to query the set of store items marked as failed; @command{guix gc
|
|
--clear-failures} removes store items from the set of cached failures.
|
|
@xref{Invoking guix gc}.
|
|
|
|
@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 --rounds=@var{N}
|
|
Build each derivation @var{n} times in a row, and raise an error if
|
|
consecutive build results are not bit-for-bit identical. Note that this
|
|
setting can be overridden by clients such as @command{guix build}
|
|
(@pxref{Invoking guix build}).
|
|
|
|
When used in conjunction with @option{--keep-failed}, the differing
|
|
output is kept in the store, under @file{/gnu/store/@dots{}-check}.
|
|
This makes it easy to look for differences between the two results.
|
|
|
|
@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.
|
|
|
|
@item --disable-deduplication
|
|
@cindex deduplication
|
|
Disable automatic file ``deduplication'' in the store.
|
|
|
|
By default, files added to the store are automatically ``deduplicated'':
|
|
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
|
|
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.
|
|
@end table
|
|
|
|
|
|
@node Application Setup
|
|
@section Application Setup
|
|
|
|
@cindex foreign distro
|
|
When using Guix on top of GNU/Linux distribution other than GuixSD---a
|
|
so-called @dfn{foreign distro}---a few additional steps are needed to
|
|
get everything in place. Here are some of them.
|
|
|
|
@subsection Locales
|
|
|
|
@anchor{locales-and-locpath}
|
|
@cindex locales, when not on GuixSD
|
|
@vindex LOCPATH
|
|
@vindex GUIX_LOCPATH
|
|
Packages installed @i{via} Guix will not use the locale data of the
|
|
host system. Instead, you must first install one of the locale packages
|
|
available with Guix and then define the @code{GUIX_LOCPATH} environment
|
|
variable:
|
|
|
|
@example
|
|
$ guix package -i glibc-locales
|
|
$ export GUIX_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. Alternatively, the @code{glibc-utf8-locales} is smaller but
|
|
limited to a few UTF-8 locales.
|
|
|
|
The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
|
|
(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
|
|
Manual}). There are two important differences though:
|
|
|
|
@enumerate
|
|
@item
|
|
@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
|
|
provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
|
|
to make sure the programs of the foreign distro will not end up loading
|
|
incompatible locale data.
|
|
|
|
@item
|
|
libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
|
|
@code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
|
|
should your Guix profile contain a mixture of programs linked against
|
|
different libc version, each libc version will only try to load locale
|
|
data in the right format.
|
|
@end enumerate
|
|
|
|
This is important because the locale data format used by different libc
|
|
versions may be incompatible.
|
|
|
|
@subsection X11 Fonts
|
|
|
|
The majority of graphical applications use Fontconfig to locate and
|
|
load fonts and perform X11-client-side rendering. The @code{fontconfig}
|
|
package in Guix looks for fonts in @file{$HOME/.guix-profile}
|
|
by default. Thus, to allow graphical applications installed with Guix
|
|
to display fonts, you have to install fonts with Guix as well.
|
|
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
|
|
@code{font-gnu-freefont-ttf}.
|
|
|
|
To display text written in Chinese languages, Japanese, or Korean in
|
|
graphical applications, consider installing
|
|
@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
|
|
has multiple outputs, one per language family (@pxref{Packages with
|
|
Multiple Outputs}). For instance, the following command installs fonts
|
|
for Chinese languages:
|
|
|
|
@example
|
|
guix package -i font-adobe-source-han-sans:cn
|
|
@end example
|
|
|
|
Older programs such as @command{xterm} do not use Fontconfig and instead
|
|
rely on server-side font rendering. Such programs require to specify a
|
|
full name of a font using XLFD (X Logical Font Description), like this:
|
|
|
|
@example
|
|
-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
|
|
@end example
|
|
|
|
To be able to use such full names for the TrueType fonts installed in
|
|
your Guix profile, you need to extend the font path of the X server:
|
|
|
|
@example
|
|
xset +fp ~/.guix-profile/share/fonts/truetype
|
|
@end example
|
|
|
|
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
|
|
to make sure your TrueType fonts are listed there.
|
|
|
|
@subsection X.509 Certificates
|
|
|
|
The @code{nss-certs} package provides X.509 certificates, which allow
|
|
programs to authenticate Web servers accessed over HTTPS.
|
|
|
|
When using Guix on a foreign distro, you can install this package and
|
|
define the relevant environment variables so that packages know where to
|
|
look for certificates. @xref{X.509 Certificates}, for detailed
|
|
information.
|
|
|
|
@subsection Emacs Packages
|
|
|
|
When you install Emacs packages with Guix, the elisp files may be placed
|
|
either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
|
|
sub-directories of
|
|
@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
|
|
directory exists because potentially there may exist thousands of Emacs
|
|
packages and storing all their files in a single directory may be not
|
|
reliable (because of name conflicts). So we think using a separate
|
|
directory for each package is a good idea. It is very similar to how
|
|
the Emacs package system organizes the file structure (@pxref{Package
|
|
Files,,, emacs, The GNU Emacs Manual}).
|
|
|
|
By default, Emacs (installed with Guix) ``knows'' where these packages
|
|
are placed, so you do not need to perform any configuration. If, for
|
|
some reason, you want to avoid auto-loading Emacs packages installed
|
|
with Guix, you can do so by running Emacs with @code{--no-site-file}
|
|
option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
|
|
|
|
@c TODO What else?
|
|
|
|
@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
|
|
procedures 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
|
|
names, @pxref{Emacs Prettify}.)
|
|
|
|
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 the 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 on GuixSD is subject to
|
|
transactional upgrades and roll-back
|
|
(@pxref{Using the Configuration System}).
|
|
|
|
All packages in the package store may be @emph{garbage-collected}.
|
|
Guix can determine which packages are still referenced by 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}).
|
|
|
|
@cindex substitutes
|
|
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}). Because build results are usually bit-for-bit
|
|
reproducible, users do not have to trust servers that provide
|
|
substitutes: they can force a local build and @emph{challenge} providers
|
|
(@pxref{Invoking guix challenge}).
|
|
|
|
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 dependencies of the
|
|
package into 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}
|
|
@end example
|
|
|
|
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:
|
|
|
|
@table @code
|
|
|
|
@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 an at-sign 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).
|
|
|
|
@anchor{package-cmd-propagated-inputs}
|
|
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 by the user.
|
|
|
|
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.
|
|
|
|
@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{guix.scm} file
|
|
in the root of their project 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}
|
|
@itemx -m @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:
|
|
|
|
@findex packages->manifest
|
|
@example
|
|
(use-package-modules guile emacs)
|
|
|
|
(packages->manifest
|
|
(list emacs
|
|
guile-2.0
|
|
;; Use a specific package output.
|
|
(list guile-2.0 "debug")))
|
|
@end example
|
|
|
|
@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.
|
|
|
|
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 metadata.
|
|
|
|
After having rolled back, installing, removing, or upgrading packages
|
|
overwrites previous future generations. Thus, the history of the
|
|
generations in a profile 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}.
|
|
|
|
This option can also be used to compute the @emph{combined} search paths
|
|
of several profiles. Consider this example:
|
|
|
|
@example
|
|
$ guix package -p foo -i guile
|
|
$ guix package -p bar -i guile-json
|
|
$ guix package -p foo -p bar --search-paths
|
|
@end example
|
|
|
|
The last command above reports about the @code{GUILE_LOAD_PATH}
|
|
variable, even though, taken individually, neither @file{foo} nor
|
|
@file{bar} would lead to that recommendation.
|
|
|
|
|
|
@item --profile=@var{profile}
|
|
@itemx -p @var{profile}
|
|
Use @var{profile} instead of the user's default profile.
|
|
|
|
@item --verbose
|
|
Produce verbose output. In particular, emit the build log of the
|
|
environment 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:
|
|
|
|
@table @option
|
|
|
|
@item --search=@var{regexp}
|
|
@itemx -s @var{regexp}
|
|
@cindex searching for packages
|
|
List the available packages whose name, synopsis, or description matches
|
|
@var{regexp}. Print all the metadata 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
|
|
|
|
It is also possible to refine search results using several @code{-s}
|
|
flags. For example, the following command returns a list of board
|
|
games:
|
|
|
|
@example
|
|
$ guix package -s '\<board\>' -s game | recsel -p name
|
|
name: gnubg
|
|
@dots{}
|
|
@end example
|
|
|
|
If we were to omit @code{-s game}, we would also get software packages
|
|
that deal with printed circuit boards; removing the angle brackets
|
|
around @code{board} would further add packages that have to do with
|
|
keyboards.
|
|
|
|
And now for a more elaborate example. The following command searches
|
|
for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
|
|
libraries, and prints the name and synopsis of the matching packages:
|
|
|
|
@example
|
|
$ guix package -s crypto -s library | \
|
|
recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
|
|
@end example
|
|
|
|
@noindent
|
|
@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
|
|
information on @dfn{selection expressions} for @code{recsel -e}.
|
|
|
|
@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.4 | recsel -p name,version
|
|
name: python
|
|
version: 3.4.3
|
|
@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.
|
|
|
|
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 smaller 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
|
|
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}]
|
|
When @var{pattern} is omitted, delete all generations except the current
|
|
one.
|
|
|
|
This command accepts the same patterns as @option{--list-generations}.
|
|
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 rolling back to them.
|
|
Consequently, this command must be used with care.
|
|
|
|
@end table
|
|
|
|
Finally, since @command{guix package} may actually start build
|
|
processes, it supports all the common build options (@pxref{Common Build
|
|
Options}). It also supports package transformation options, such as
|
|
@option{--with-source} (@pxref{Package Transformation Options}).
|
|
However, note that package transformations are lost when upgrading; to
|
|
preserve transformations across upgrades, you should define your own
|
|
package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
|
|
(@pxref{Defining Packages}).
|
|
|
|
|
|
@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 (@pxref{Emacs
|
|
Hydra}, for information on how to query the continuous integration
|
|
server). 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}).
|
|
|
|
Substitute URLs can be either HTTP or HTTPS@footnote{For HTTPS access,
|
|
the Guile bindings of GnuTLS must be installed. @xref{Requirements}.}
|
|
HTTPS is recommended because communications are encrypted; conversely,
|
|
using HTTP makes all communications visible to an eavesdropper, who
|
|
could use the information gathered to determine, for instance, whether
|
|
your system has unpatched security vulnerabilities.
|
|
|
|
@cindex security
|
|
@cindex digital signatures
|
|
To allow Guix to download substitutes from @code{hydra.gnu.org} or a
|
|
mirror thereof, 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.
|
|
|
|
@vindex http_proxy
|
|
Substitutes are downloaded over HTTP or HTTPS.
|
|
The @code{http_proxy} environment
|
|
variable can be set in the environment of @command{guix-daemon} and is
|
|
honored for downloads of substitutes. Note that the value of
|
|
@code{http_proxy} in the environment where @command{guix build},
|
|
@command{guix package}, and other client commands are run has
|
|
@emph{absolutely no effect}.
|
|
|
|
When using HTTPS, the server's X.509 certificate is @emph{not} validated
|
|
(in other words, the server is not authenticated), contrary to what
|
|
HTTPS clients such as Web browsers usually do. This is because Guix
|
|
authenticates substitute information itself, as explained above, which
|
|
is what we care about (whereas X.509 certificates are about
|
|
authenticating bindings between domain names and public keys.)
|
|
|
|
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.
|
|
|
|
|
|
@unnumberedsubsec On Trusting Binaries
|
|
|
|
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. The @command{guix challenge} command aims to
|
|
help users assess substitute servers, and to assist developers in
|
|
finding out about non-deterministic package builds (@pxref{Invoking guix
|
|
challenge}). Similarly, the @option{--check} option of @command{guix
|
|
build} allows users to check whether previously-installed substitutes
|
|
are genuine by rebuilding them locally (@pxref{build-check,
|
|
@command{guix build --check}}).
|
|
|
|
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}.
|
|
|
|
|
|
@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 to 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 installs 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 --free-space=@var{free}
|
|
@itemx -F @var{free}
|
|
Collect garbage until @var{free} space is available under
|
|
@file{/gnu/store}, if possible; @var{free} denotes storage space, such
|
|
as @code{500MiB}, as described above.
|
|
|
|
When @var{free} or more is already available in @file{/gnu/store}, do
|
|
nothing and exit immediately.
|
|
|
|
@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-failures
|
|
List store items corresponding to cached build failures.
|
|
|
|
This prints nothing unless the daemon was started with
|
|
@option{--cache-failures} (@pxref{Invoking guix-daemon,
|
|
@option{--cache-failures}}).
|
|
|
|
@item --clear-failures
|
|
Remove the specified store items from the failed-build cache.
|
|
|
|
Again, this option only makes sense when the daemon is started with
|
|
@option{--cache-failures}. Otherwise, it does nothing.
|
|
|
|
@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.
|
|
|
|
@item --requisites
|
|
@itemx -R
|
|
@cindex closure
|
|
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 the closure
|
|
of an element. @xref{Invoking guix graph}, for a tool to visualize
|
|
the graph of references.
|
|
|
|
@end table
|
|
|
|
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
|
|
database of the daemon actually exist in @file{/gnu/store}.
|
|
|
|
When provided, @var{options} must be a comma-separated list containing one
|
|
or more of @code{contents} and @code{repair}.
|
|
|
|
When passing @option{--verify=contents}, the daemon computes the
|
|
content hash of each store item and compares 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
|
|
|
|
@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.
|
|
|
|
Any user can update their Guix copy using @command{guix pull}, and the
|
|
effect is limited to the user who run @command{guix pull}. For
|
|
instance, when user @code{root} runs @command{guix pull}, this has no
|
|
effect on the version of Guix that user @code{alice} sees, and vice
|
|
versa@footnote{Under the hood, @command{guix pull} updates the
|
|
@file{~/.config/guix/latest} symbolic link to point to the latest Guix,
|
|
and the @command{guix} command loads code from there.}.
|
|
|
|
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 the store on another machine.
|
|
|
|
To export store files as an archive to 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
|
|
common build options (@pxref{Common Build Options}).
|
|
|
|
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
|
|
@end example
|
|
|
|
@noindent
|
|
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 store on the
|
|
target machine. The @code{--missing} option can help figure out which
|
|
items are missing from the target 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 metadata 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}]
|
|
@cindex signing, archives
|
|
Generate a new key pair for the daemon. 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.
|
|
Alternatively, @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)}.
|
|
|
|
@item --extract=@var{directory}
|
|
@itemx -x @var{directory}
|
|
Read a single-item archive as served by substitute servers
|
|
(@pxref{Substitutes}) and extract it to @var{directory}. This is a
|
|
low-level operation needed in only very narrow use cases; see below.
|
|
|
|
For example, the following command extracts the substitute for Emacs
|
|
served by @code{hydra.gnu.org} to @file{/tmp/emacs}:
|
|
|
|
@example
|
|
$ wget -O - \
|
|
https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
|
|
| bunzip2 | guix archive -x /tmp/emacs
|
|
@end example
|
|
|
|
Single-item archives are different from multiple-item archives produced
|
|
by @command{guix archive --export}; they contain a single store item,
|
|
and they do @emph{not} embed a signature. Thus this operation does
|
|
@emph{no} signature verification and its output should be considered
|
|
unsafe.
|
|
|
|
The primary purpose of this operation is to facilitate inspection of
|
|
archive contents coming from possibly untrusted substitute servers.
|
|
|
|
@end table
|
|
|
|
@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.
|
|
|
|
@menu
|
|
* 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.
|
|
@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")
|
|
(version "2.10")
|
|
(source (origin
|
|
(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")))
|
|
(inputs `(("gawk" ,gawk)))
|
|
(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 the 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 in 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.
|
|
|
|
@cindex quote
|
|
@cindex quoting
|
|
@findex '
|
|
@findex quote
|
|
What about these quote (@code{'}) characters? They are Scheme syntax to
|
|
introduce a literal list; @code{'} is synonymous with @code{quote}.
|
|
@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
|
|
for details. Here the value of the @code{arguments} field is a list of
|
|
arguments passed to the build system down the road, as with @code{apply}
|
|
(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
|
|
Manual}).
|
|
|
|
The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
|
|
(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
|
|
@code{#:configure-flags} is a keyword used to pass a keyword argument
|
|
to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
|
|
Reference Manual}).
|
|
|
|
@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.
|
|
|
|
@cindex backquote (quasiquote)
|
|
@findex `
|
|
@findex quasiquote
|
|
@cindex comma (unquote)
|
|
@findex ,
|
|
@findex unquote
|
|
@findex ,@@
|
|
@findex unquote-splicing
|
|
Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
|
|
us to introduce a literal list in the @code{inputs} field, while
|
|
@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
|
|
value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
|
|
Reference Manual}).
|
|
|
|
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
|
|
|
|
@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.
|
|
|
|
Finally, 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
|
|
|
|
@cindex package transformations
|
|
@cindex input rewriting
|
|
@cindex dependency tree rewriting
|
|
Packages can be manipulated in arbitrary ways. An example of a useful
|
|
transformation is @dfn{input rewriting}, whereby the dependency tree of
|
|
a package is rewritten by replacing specific inputs by others:
|
|
|
|
@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
|
|
[@var{rewrite-name}]
|
|
Return a procedure that, when passed a package, replaces its direct and
|
|
indirect dependencies (but not its implicit inputs) according to
|
|
@var{replacements}. @var{replacements} is a list of package pairs; the
|
|
first element of each pair is the package to replace, and the second one
|
|
is the replacement.
|
|
|
|
Optionally, @var{rewrite-name} is a one-argument procedure that takes
|
|
the name of a package and returns its new name after rewrite.
|
|
@end deffn
|
|
|
|
@noindent
|
|
Consider this example:
|
|
|
|
@example
|
|
(define libressl-instead-of-openssl
|
|
;; This is a procedure to replace OPENSSL by LIBRESSL,
|
|
;; recursively.
|
|
(package-input-rewriting `((,openssl . ,libressl))))
|
|
|
|
(define git-with-libressl
|
|
(libressl-instead-of-openssl git))
|
|
@end example
|
|
|
|
@noindent
|
|
Here we first define a rewriting procedure that replaces @var{openssl}
|
|
with @var{libressl}. Then we use it to define a @dfn{variant} of the
|
|
@var{git} package that uses @var{libressl} instead of @var{openssl}.
|
|
This is exactly what the @option{--with-input} command-line option does
|
|
(@pxref{Package Transformation Options, @option{--with-input}}).
|
|
|
|
@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 object telling how the source code for the package should be
|
|
acquired. Most of the time, this is an @code{origin} object, which
|
|
denotes a file fetched from the Internet (@pxref{origin Reference}). It
|
|
can also be any other ``file-like'' object such as a @code{local-file},
|
|
which denotes a file from the local file system (@pxref{G-Expressions,
|
|
@code{local-file}}).
|
|
|
|
@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{'()})
|
|
@itemx @code{native-inputs} (default: @code{'()})
|
|
@itemx @code{propagated-inputs} (default: @code{'()})
|
|
@cindex inputs, of packages
|
|
These fields list dependencies of the package. Each one is a list of
|
|
tuples, where each tuple has a label for the input (a string) as its
|
|
first element, a package, origin, or derivation as its second element,
|
|
and optionally the name of the output thereof that should be used, which
|
|
defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
|
|
more on package outputs). For example, the list below specifies three
|
|
inputs:
|
|
|
|
@example
|
|
`(("libffi" ,libffi)
|
|
("libunistring" ,libunistring)
|
|
("glib:bin" ,glib "bin")) ;the "bin" output of Glib
|
|
@end example
|
|
|
|
@cindex cross compilation, package dependencies
|
|
The distinction between @code{native-inputs} and @code{inputs} is
|
|
necessary when considering cross-compilation. When cross-compiling,
|
|
dependencies listed in @code{inputs} are built for the @emph{target}
|
|
architecture; conversely, dependencies listed in @code{native-inputs}
|
|
are built for the architecture of the @emph{build} machine.
|
|
|
|
@code{native-inputs} is typically used to 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}).
|
|
|
|
@anchor{package-propagated-inputs}
|
|
Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
|
|
specified packages will be automatically 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 C/C++ library needs headers of
|
|
another library to compile, or when a pkg-config file refers to another
|
|
one @i{via} its @code{Requires} field.
|
|
|
|
Another example where @code{propagated-inputs} is useful is for languages
|
|
that lack a facility to record the run-time search path akin to the
|
|
@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, GHC, and
|
|
more. To ensure that libraries written in those languages can find
|
|
library code they depend on at run time, run-time dependencies must be
|
|
listed in @code{propagated-inputs} rather than @code{inputs}.
|
|
|
|
@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 be 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)},
|
|
or a list of such values.
|
|
|
|
@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"}.
|
|
|
|
@item @code{maintainers} (default: @code{'()})
|
|
The list of maintainers of the package, as @code{maintainer} objects.
|
|
|
|
@item @code{location} (default: source location of the @code{package} form)
|
|
The source location of the package. It is useful to override this when
|
|
inheriting from another package, in which case this field is not
|
|
automatically corrected.
|
|
@end table
|
|
@end deftp
|
|
|
|
|
|
@node origin Reference
|
|
@subsection @code{origin} Reference
|
|
|
|
This section summarizes all the options available in @code{origin}
|
|
declarations (@pxref{Defining Packages}).
|
|
|
|
@deftp {Data Type} origin
|
|
This is the data type representing a source code origin.
|
|
|
|
@table @asis
|
|
@item @code{uri}
|
|
An object containing the URI of the source. The object type depends on
|
|
the @code{method} (see below). For example, when using the
|
|
@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
|
|
values are: a URL represented as a string, or a list thereof.
|
|
|
|
@item @code{method}
|
|
A procedure that handles the URI.
|
|
|
|
Examples include:
|
|
|
|
@table @asis
|
|
@item @var{url-fetch} from @code{(guix download)}
|
|
download a file from the HTTP, HTTPS, or FTP URL specified in the
|
|
@code{uri} field;
|
|
|
|
@vindex git-fetch
|
|
@item @var{git-fetch} from @code{(guix git-download)}
|
|
clone the Git version control repository, and check out the revision
|
|
specified in the @code{uri} field as a @code{git-reference} object; a
|
|
@code{git-reference} looks like this:
|
|
|
|
@example
|
|
(git-reference
|
|
(url "git://git.debian.org/git/pkg-shadow/shadow")
|
|
(commit "v4.1.5.1"))
|
|
@end example
|
|
@end table
|
|
|
|
@item @code{sha256}
|
|
A bytevector containing the SHA-256 hash of the source. Typically the
|
|
@code{base32} form is used here to generate the bytevector from a
|
|
base-32 string.
|
|
|
|
You can obtain this information using @code{guix download}
|
|
(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
|
|
guix hash}).
|
|
|
|
@item @code{file-name} (default: @code{#f})
|
|
The file name under which the source code should be saved. When this is
|
|
@code{#f}, a sensible default value will be used in most cases. In case
|
|
the source is fetched from a URL, the file name from the URL will be
|
|
used. For version control checkouts, it is recommended to provide the
|
|
file name explicitly because the default is not very descriptive.
|
|
|
|
@item @code{patches} (default: @code{'()})
|
|
A list of file names containing patches to be applied to the source.
|
|
|
|
@item @code{snippet} (default: @code{#f})
|
|
A G-expression (@pxref{G-Expressions}) or S-expression that will be run
|
|
in the source directory. This is a convenient way to modify the source,
|
|
sometimes more convenient than a patch.
|
|
|
|
@item @code{patch-flags} (default: @code{'("-p1")})
|
|
A list of command-line flags that should be passed to the @code{patch}
|
|
command.
|
|
|
|
@item @code{patch-inputs} (default: @code{#f})
|
|
Input packages or derivations to the patching process. When this is
|
|
@code{#f}, the usual set of inputs necessary for patching are provided,
|
|
such as GNU@tie{}Patch.
|
|
|
|
@item @code{modules} (default: @code{'()})
|
|
A list of Guile modules that should be loaded during the patching
|
|
process and while running the code in the @code{snippet} field.
|
|
|
|
@item @code{patch-guile} (default: @code{#f})
|
|
The Guile package that should be used in the patching process. When
|
|
this is @code{#f}, a sensible default is used.
|
|
@end table
|
|
@end deftp
|
|
|
|
|
|
@node Build Systems
|
|
@section Build Systems
|
|
|
|
@cindex build system
|
|
Each package definition specifies a @dfn{build system} and arguments for
|
|
that build system (@pxref{Defining Packages}). This @code{build-system}
|
|
field represents the build procedure of the package, as well as implicit
|
|
dependencies of that build procedure.
|
|
|
|
Build systems are @code{<build-system>} objects. The interface to
|
|
create and manipulate them is provided by the @code{(guix build-system)}
|
|
module, and actual build systems are exported by specific modules.
|
|
|
|
@cindex bag (low-level package representation)
|
|
Under the hood, build systems first compile package objects to
|
|
@dfn{bags}. A @dfn{bag} is like a package, but with less
|
|
ornamentation---in other words, a bag is a lower-level representation of
|
|
a package, which includes all the inputs of that package, including some
|
|
that were implicitly added by the build system. This intermediate
|
|
representation is then compiled to a derivation (@pxref{Derivations}).
|
|
|
|
Build systems accept an optional list of @dfn{arguments}. In package
|
|
definitions, these are passed @i{via} the @code{arguments} field
|
|
(@pxref{Defining Packages}). They are typically keyword arguments
|
|
(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
|
|
Guile Reference Manual}). The value of these arguments is usually
|
|
evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
|
|
by the daemon (@pxref{Derivations}).
|
|
|
|
The main build system is @var{gnu-build-system}, which implements the
|
|
standard build procedure for GNU and many other packages. It
|
|
is provided by the @code{(guix build-system gnu)} module.
|
|
|
|
@defvr {Scheme Variable} gnu-build-system
|
|
@var{gnu-build-system} represents the GNU Build System, and variants
|
|
thereof (@pxref{Configuration, configuration and makefile conventions,,
|
|
standards, GNU Coding Standards}).
|
|
|
|
@cindex build phases
|
|
In a nutshell, packages using it are configured, built, and installed with
|
|
the usual @code{./configure && make && make check && make install}
|
|
command sequence. In practice, a few additional steps are often needed.
|
|
All these steps are split up in separate @dfn{phases},
|
|
notably@footnote{Please see the @code{(guix build gnu-build-system)}
|
|
modules for more details about the build phases.}:
|
|
|
|
@table @code
|
|
@item unpack
|
|
Unpack the source tarball, and change the current directory to the
|
|
extracted source tree. If the source is actually a directory, copy it
|
|
to the build tree, and enter that directory.
|
|
|
|
@item patch-source-shebangs
|
|
Patch shebangs encountered in source files so they refer to the right
|
|
store file names. For instance, this changes @code{#!/bin/sh} to
|
|
@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
|
|
|
|
@item configure
|
|
Run the @file{configure} script with a number of default options, such
|
|
as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
|
|
by the @code{#:configure-flags} argument.
|
|
|
|
@item build
|
|
Run @code{make} with the list of flags specified with
|
|
@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
|
|
(the default), build with @code{make -j}.
|
|
|
|
@item check
|
|
Run @code{make check}, or some other target specified with
|
|
@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
|
|
@code{#:parallel-tests?} argument is true (the default), run @code{make
|
|
check -j}.
|
|
|
|
@item install
|
|
Run @code{make install} with the flags listed in @code{#:make-flags}.
|
|
|
|
@item patch-shebangs
|
|
Patch shebangs on the installed executable files.
|
|
|
|
@item strip
|
|
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
|
|
is false), copying them to the @code{debug} output when available
|
|
(@pxref{Installing Debugging Files}).
|
|
@end table
|
|
|
|
@vindex %standard-phases
|
|
The build-side module @code{(guix build gnu-build-system)} defines
|
|
@var{%standard-phases} as the default list of build phases.
|
|
@var{%standard-phases} is a list of symbol/procedure pairs, where the
|
|
procedure implements the actual phase.
|
|
|
|
The list of phases used for a particular package can be changed with the
|
|
@code{#:phases} parameter. For instance, passing:
|
|
|
|
@example
|
|
#:phases (modify-phases %standard-phases (delete 'configure))
|
|
@end example
|
|
|
|
means that all the phases described above will be used, except the
|
|
@code{configure} phase.
|
|
|
|
In addition, this build system ensures that the ``standard'' environment
|
|
for GNU packages is available. This includes tools such as GCC, libc,
|
|
Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
|
|
build-system gnu)} module for a complete list). We call these the
|
|
@dfn{implicit inputs} of a package, because package definitions do not
|
|
have to mention them.
|
|
@end defvr
|
|
|
|
Other @code{<build-system>} objects are defined to support other
|
|
conventions and tools used by free software packages. They inherit most
|
|
of @var{gnu-build-system}, and differ mainly in the set of inputs
|
|
implicitly added to the build process, and in the list of phases
|
|
executed. Some of these build systems are listed below.
|
|
|
|
@defvr {Scheme Variable} ant-build-system
|
|
This variable is exported by @code{(guix build-system ant)}. It
|
|
implements the build procedure for Java packages that can be built with
|
|
@url{http://ant.apache.org/, Ant build tool}.
|
|
|
|
It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
|
|
provided by the @code{icedtea} package to the set of inputs. Different
|
|
packages can be specified with the @code{#:ant} and @code{#:jdk}
|
|
parameters, respectively.
|
|
|
|
When the original package does not provide a suitable Ant build file,
|
|
the parameter @code{#:jar-name} can be used to generate a minimal Ant
|
|
build file @file{build.xml} with tasks to build the specified jar
|
|
archive.
|
|
|
|
The parameter @code{#:build-target} can be used to specify the Ant task
|
|
that should be run during the @code{build} phase. By default the
|
|
``jar'' task will be run.
|
|
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} cmake-build-system
|
|
This variable is exported by @code{(guix build-system cmake)}. It
|
|
implements the build procedure for packages using the
|
|
@url{http://www.cmake.org, CMake build tool}.
|
|
|
|
It automatically adds the @code{cmake} package to the set of inputs.
|
|
Which package is used can be specified with the @code{#:cmake}
|
|
parameter.
|
|
|
|
The @code{#:configure-flags} parameter is taken as a list of flags
|
|
passed to the @command{cmake} command. The @code{#:build-type}
|
|
parameter specifies in abstract terms the flags passed to the compiler;
|
|
it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
|
|
debugging information''), which roughly means that code is compiled with
|
|
@code{-O2 -g}, as is the case for Autoconf-based packages by default.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} glib-or-gtk-build-system
|
|
This variable is exported by @code{(guix build-system glib-or-gtk)}. It
|
|
is intended for use with packages making use of GLib or GTK+.
|
|
|
|
This build system adds the following two phases to the ones defined by
|
|
@var{gnu-build-system}:
|
|
|
|
@table @code
|
|
@item glib-or-gtk-wrap
|
|
The phase @code{glib-or-gtk-wrap} ensures that programs in
|
|
@file{bin/} are able to find GLib ``schemas'' and
|
|
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
|
|
modules}. This is achieved by wrapping the programs in launch scripts
|
|
that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
|
|
environment variables.
|
|
|
|
It is possible to exclude specific package outputs from that wrapping
|
|
process by listing their names in the
|
|
@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
|
|
when an output is known not to contain any GLib or GTK+ binaries, and
|
|
where wrapping would gratuitously add a dependency of that output on
|
|
GLib and GTK+.
|
|
|
|
@item glib-or-gtk-compile-schemas
|
|
The phase @code{glib-or-gtk-compile-schemas} makes sure that all
|
|
@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
|
|
GSettings schemas} of GLib are compiled. Compilation is performed by the
|
|
@command{glib-compile-schemas} program. It is provided by the package
|
|
@code{glib:bin} which is automatically imported by the build system.
|
|
The @code{glib} package providing @command{glib-compile-schemas} can be
|
|
specified with the @code{#:glib} parameter.
|
|
@end table
|
|
|
|
Both phases are executed after the @code{install} phase.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} python-build-system
|
|
This variable is exported by @code{(guix build-system python)}. It
|
|
implements the more or less standard build procedure used by Python
|
|
packages, which consists in running @code{python setup.py build} and
|
|
then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
|
|
|
|
For packages that install stand-alone Python programs under @code{bin/},
|
|
it takes care of wrapping these programs so that their @code{PYTHONPATH}
|
|
environment variable points to all the Python libraries they depend on.
|
|
|
|
Which Python package is used to perform the build can be specified with
|
|
the @code{#:python} parameter. This is a useful way to force a package
|
|
to be built for a specific version of the Python interpreter, which
|
|
might be necessary if the package is only compatible with a single
|
|
interpreter version.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} perl-build-system
|
|
This variable is exported by @code{(guix build-system perl)}. It
|
|
implements the standard build procedure for Perl packages, which either
|
|
consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
|
|
followed by @code{Build} and @code{Build install}; or in running
|
|
@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
|
|
@code{make} and @code{make install}, depending on which of
|
|
@code{Build.PL} or @code{Makefile.PL} is present in the package
|
|
distribution. Preference is given to the former if both @code{Build.PL}
|
|
and @code{Makefile.PL} exist in the package distribution. This
|
|
preference can be reversed by specifying @code{#t} for the
|
|
@code{#:make-maker?} parameter.
|
|
|
|
The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
|
|
passes flags specified by the @code{#:make-maker-flags} or
|
|
@code{#:module-build-flags} parameter, respectively.
|
|
|
|
Which Perl package is used can be specified with @code{#:perl}.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} r-build-system
|
|
This variable is exported by @code{(guix build-system r)}. It
|
|
implements the build procedure used by @uref{http://r-project.org, R}
|
|
packages, which essentially is little more than running @code{R CMD
|
|
INSTALL --library=/gnu/store/@dots{}} in an environment where
|
|
@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
|
|
are run after installation using the R function
|
|
@code{tools::testInstalledPackage}.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} ruby-build-system
|
|
This variable is exported by @code{(guix build-system ruby)}. It
|
|
implements the RubyGems build procedure used by Ruby packages, which
|
|
involves running @code{gem build} followed by @code{gem install}.
|
|
|
|
The @code{source} field of a package that uses this build system
|
|
typically references a gem archive, since this is the format that Ruby
|
|
developers use when releasing their software. The build system unpacks
|
|
the gem archive, potentially patches the source, runs the test suite,
|
|
repackages the gem, and installs it. Additionally, directories and
|
|
tarballs may be referenced to allow building unreleased gems from Git or
|
|
a traditional source release tarball.
|
|
|
|
Which Ruby package is used can be specified with the @code{#:ruby}
|
|
parameter. A list of additional flags to be passed to the @command{gem}
|
|
command can be specified with the @code{#:gem-flags} parameter.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} waf-build-system
|
|
This variable is exported by @code{(guix build-system waf)}. It
|
|
implements a build procedure around the @code{waf} script. The common
|
|
phases---@code{configure}, @code{build}, and @code{install}---are
|
|
implemented by passing their names as arguments to the @code{waf}
|
|
script.
|
|
|
|
The @code{waf} script is executed by the Python interpreter. Which
|
|
Python package is used to run the script can be specified with the
|
|
@code{#:python} parameter.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} haskell-build-system
|
|
This variable is exported by @code{(guix build-system haskell)}. It
|
|
implements the Cabal build procedure used by Haskell packages, which
|
|
involves running @code{runhaskell Setup.hs configure
|
|
--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
|
|
Instead of installing the package by running @code{runhaskell Setup.hs
|
|
install}, to avoid trying to register libraries in the read-only
|
|
compiler store directory, the build system uses @code{runhaskell
|
|
Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
|
|
addition, the build system generates the package documentation by
|
|
running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
|
|
is passed. Optional Haddock parameters can be passed with the help of
|
|
the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
|
|
not found, the build system looks for @code{Setup.lhs} instead.
|
|
|
|
Which Haskell compiler is used can be specified with the @code{#:haskell}
|
|
parameter which defaults to @code{ghc}.
|
|
@end defvr
|
|
|
|
@defvr {Scheme Variable} emacs-build-system
|
|
This variable is exported by @code{(guix build-system emacs)}. It
|
|
implements an installation procedure similar to the packaging system
|
|
of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
|
|
|
|
It first creates the @code{@var{package}-autoloads.el} file, then it
|
|
byte compiles all Emacs Lisp files. Differently from the Emacs
|
|
packaging system, the Info documentation files are moved to the standard
|
|
documentation directory and the @file{dir} file is deleted. Each
|
|
package is installed in its own directory under
|
|
@file{share/emacs/site-lisp/guix.d}.
|
|
@end defvr
|
|
|
|
Lastly, for packages that do not need anything as sophisticated, a
|
|
``trivial'' build system is provided. It is trivial in the sense that
|
|
it provides basically no support: it does not pull any implicit inputs,
|
|
and does not have a notion of build phases.
|
|
|
|
@defvr {Scheme Variable} trivial-build-system
|
|
This variable is exported by @code{(guix build-system trivial)}.
|
|
|
|
This build system requires a @code{#:builder} argument. This argument
|
|
must be a Scheme expression that builds the package output(s)---as
|
|
with @code{build-expression->derivation} (@pxref{Derivations,
|
|
@code{build-expression->derivation}}).
|
|
@end defvr
|
|
|
|
@node The Store
|
|
@section The Store
|
|
|
|
@cindex store
|
|
@cindex store items
|
|
@cindex store paths
|
|
|
|
Conceptually, the @dfn{store} is the place where derivations that have
|
|
been built successfully are stored---by default, @file{/gnu/store}.
|
|
Sub-directories in the store are referred to as @dfn{store items} or
|
|
sometimes @dfn{store paths}. The store has an associated database that
|
|
contains information such as the store paths referred to by each store
|
|
path, and the list of @emph{valid} store items---results of successful
|
|
builds. This database resides in @file{@var{localstatedir}/guix/db},
|
|
where @var{localstatedir} is the state directory specified @i{via}
|
|
@option{--localstatedir} at configure time, usually @file{/var}.
|
|
|
|
The store is @emph{always} accessed by the daemon on behalf of its clients
|
|
(@pxref{Invoking guix-daemon}). To manipulate the store, clients
|
|
connect to the daemon over a Unix-domain socket, send requests to it,
|
|
and read the result---these are remote procedure calls, or RPCs.
|
|
|
|
@quotation Note
|
|
Users must @emph{never} modify files under @file{/gnu/store} directly.
|
|
This would lead to inconsistencies and break the immutability
|
|
assumptions of Guix's functional model (@pxref{Introduction}).
|
|
|
|
@xref{Invoking guix gc, @command{guix gc --verify}}, for information on
|
|
how to check the integrity of the store and attempt recovery from
|
|
accidental modifications.
|
|
@end quotation
|
|
|
|
The @code{(guix store)} module provides procedures to connect to the
|
|
daemon, and to perform RPCs. These are described below.
|
|
|
|
@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
|
|
Connect to the daemon over the Unix-domain socket at @var{file}. When
|
|
@var{reserve-space?} is true, instruct it to reserve a little bit of
|
|
extra space on the file system so that the garbage collector can still
|
|
operate should the disk become full. Return a server object.
|
|
|
|
@var{file} defaults to @var{%default-socket-path}, which is the normal
|
|
location given the options that were passed to @command{configure}.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} close-connection @var{server}
|
|
Close the connection to @var{server}.
|
|
@end deffn
|
|
|
|
@defvr {Scheme Variable} current-build-output-port
|
|
This variable is bound to a SRFI-39 parameter, which refers to the port
|
|
where build and error logs sent by the daemon should be written.
|
|
@end defvr
|
|
|
|
Procedures that make RPCs all take a server object as their first
|
|
argument.
|
|
|
|
@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
|
|
@cindex invalid store items
|
|
Return @code{#t} when @var{path} designates a valid store item and
|
|
@code{#f} otherwise (an invalid item may exist on disk but still be
|
|
invalid, for instance because it is the result of an aborted or failed
|
|
build.)
|
|
|
|
A @code{&nix-protocol-error} condition is raised if @var{path} is not
|
|
prefixed by the store directory (@file{/gnu/store}).
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
|
|
Add @var{text} under file @var{name} in the store, and return its store
|
|
path. @var{references} is the list of store paths referred to by the
|
|
resulting store path.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
|
|
Build @var{derivations} (a list of @code{<derivation>} objects or
|
|
derivation paths), and return when the worker is done building them.
|
|
Return @code{#t} on success.
|
|
@end deffn
|
|
|
|
Note that the @code{(guix monads)} module provides a monad as well as
|
|
monadic versions of the above procedures, with the goal of making it
|
|
more convenient to work with code that accesses the store (@pxref{The
|
|
Store Monad}).
|
|
|
|
@c FIXME
|
|
@i{This section is currently incomplete.}
|
|
|
|
@node Derivations
|
|
@section Derivations
|
|
|
|
@cindex derivations
|
|
Low-level build actions and the environment in which they are performed
|
|
are represented by @dfn{derivations}. A derivation contains the
|
|
following pieces of information:
|
|
|
|
@itemize
|
|
@item
|
|
The outputs of the derivation---derivations produce at least one file or
|
|
directory in the store, but may produce more.
|
|
|
|
@item
|
|
The inputs of the derivations, which may be other derivations or plain
|
|
files in the store (patches, build scripts, etc.)
|
|
|
|
@item
|
|
The system type targeted by the derivation---e.g., @code{x86_64-linux}.
|
|
|
|
@item
|
|
The file name of a build script in the store, along with the arguments
|
|
to be passed.
|
|
|
|
@item
|
|
A list of environment variables to be defined.
|
|
|
|
@end itemize
|
|
|
|
@cindex derivation path
|
|
Derivations allow clients of the daemon to communicate build actions to
|
|
the store. They exist in two forms: as an in-memory representation,
|
|
both on the client- and daemon-side, and as files in the store whose
|
|
name end in @code{.drv}---these files are referred to as @dfn{derivation
|
|
paths}. Derivations paths can be passed to the @code{build-derivations}
|
|
procedure to perform the build actions they prescribe (@pxref{The
|
|
Store}).
|
|
|
|
The @code{(guix derivations)} module provides a representation of
|
|
derivations as Scheme objects, along with procedures to create and
|
|
otherwise manipulate derivations. The lowest-level primitive to create
|
|
a derivation is the @code{derivation} procedure:
|
|
|
|
@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
|
|
@var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
|
|
[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
|
|
[#:system (%current-system)] [#:references-graphs #f] @
|
|
[#:allowed-references #f] [#:disallowed-references #f] @
|
|
[#:leaked-env-vars #f] [#:local-build? #f] @
|
|
[#:substitutable? #t]
|
|
Build a derivation with the given arguments, and return the resulting
|
|
@code{<derivation>} object.
|
|
|
|
When @var{hash} and @var{hash-algo} are given, a
|
|
@dfn{fixed-output derivation} is created---i.e., one whose result is
|
|
known in advance, such as a file download. If, in addition,
|
|
@var{recursive?} is true, then that fixed output may be an executable
|
|
file or a directory and @var{hash} must be the hash of an archive
|
|
containing this output.
|
|
|
|
When @var{references-graphs} is true, it must be a list of file
|
|
name/store path pairs. In that case, the reference graph of each store
|
|
path is exported in the build environment in the corresponding file, in
|
|
a simple text format.
|
|
|
|
When @var{allowed-references} is true, it must be a list of store items
|
|
or outputs that the derivation's output may refer to. Likewise,
|
|
@var{disallowed-references}, if true, must be a list of things the
|
|
outputs may @emph{not} refer to.
|
|
|
|
When @var{leaked-env-vars} is true, it must be a list of strings
|
|
denoting environment variables that are allowed to ``leak'' from the
|
|
daemon's environment to the build environment. This is only applicable
|
|
to fixed-output derivations---i.e., when @var{hash} is true. The main
|
|
use is to allow variables such as @code{http_proxy} to be passed to
|
|
derivations that download files.
|
|
|
|
When @var{local-build?} is true, declare that the derivation is not a
|
|
good candidate for offloading and should rather be built locally
|
|
(@pxref{Daemon Offload Setup}). This is the case for small derivations
|
|
where the costs of data transfers would outweigh the benefits.
|
|
|
|
When @var{substitutable?} is false, declare that substitutes of the
|
|
derivation's output should not be used (@pxref{Substitutes}). This is
|
|
useful, for instance, when building packages that capture details of the
|
|
host CPU instruction set.
|
|
@end deffn
|
|
|
|
@noindent
|
|
Here's an example with a shell script as its builder, assuming
|
|
@var{store} is an open connection to the daemon, and @var{bash} points
|
|
to a Bash executable in the store:
|
|
|
|
@lisp
|
|
(use-modules (guix utils)
|
|
(guix store)
|
|
(guix derivations))
|
|
|
|
(let ((builder ; add the Bash script to the store
|
|
(add-text-to-store store "my-builder.sh"
|
|
"echo hello world > $out\n" '())))
|
|
(derivation store "foo"
|
|
bash `("-e" ,builder)
|
|
#:inputs `((,bash) (,builder))
|
|
#:env-vars '(("HOME" . "/homeless"))))
|
|
@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
|
|
@end lisp
|
|
|
|
As can be guessed, this primitive is cumbersome to use directly. A
|
|
better approach is to write build scripts in Scheme, of course! The
|
|
best course of action for that is to write the build code as a
|
|
``G-expression'', and to pass it to @code{gexp->derivation}. For more
|
|
information, @pxref{G-Expressions}.
|
|
|
|
Once upon a time, @code{gexp->derivation} did not exist and constructing
|
|
derivations with build code written in Scheme was achieved with
|
|
@code{build-expression->derivation}, documented below. This procedure
|
|
is now deprecated in favor of the much nicer @code{gexp->derivation}.
|
|
|
|
@deffn {Scheme Procedure} build-expression->derivation @var{store} @
|
|
@var{name} @var{exp} @
|
|
[#:system (%current-system)] [#:inputs '()] @
|
|
[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
|
|
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
|
|
[#:references-graphs #f] [#:allowed-references #f] @
|
|
[#:disallowed-references #f] @
|
|
[#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
|
|
Return a derivation that executes Scheme expression @var{exp} as a
|
|
builder for derivation @var{name}. @var{inputs} must be a list of
|
|
@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
|
|
@code{"out"} is assumed. @var{modules} is a list of names of Guile
|
|
modules from the current search path to be copied in the store,
|
|
compiled, and made available in the load path during the execution of
|
|
@var{exp}---e.g., @code{((guix build utils) (guix build
|
|
gnu-build-system))}.
|
|
|
|
@var{exp} is evaluated in an environment where @code{%outputs} is bound
|
|
to a list of output/path pairs, and where @code{%build-inputs} is bound
|
|
to a list of string/output-path pairs made from @var{inputs}.
|
|
Optionally, @var{env-vars} is a list of string pairs specifying the name
|
|
and value of environment variables visible to the builder. The builder
|
|
terminates by passing the result of @var{exp} to @code{exit}; thus, when
|
|
@var{exp} returns @code{#f}, the build is considered to have failed.
|
|
|
|
@var{exp} is built using @var{guile-for-build} (a derivation). When
|
|
@var{guile-for-build} is omitted or is @code{#f}, the value of the
|
|
@code{%guile-for-build} fluid is used instead.
|
|
|
|
See the @code{derivation} procedure for the meaning of
|
|
@var{references-graphs}, @var{allowed-references},
|
|
@var{disallowed-references}, @var{local-build?}, and
|
|
@var{substitutable?}.
|
|
@end deffn
|
|
|
|
@noindent
|
|
Here's an example of a single-output derivation that creates a directory
|
|
containing one file:
|
|
|
|
@lisp
|
|
(let ((builder '(let ((out (assoc-ref %outputs "out")))
|
|
(mkdir out) ; create /gnu/store/@dots{}-goo
|
|
(call-with-output-file (string-append out "/test")
|
|
(lambda (p)
|
|
(display '(hello guix) p))))))
|
|
(build-expression->derivation store "goo" builder))
|
|
|
|
@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
|
|
@end lisp
|
|
|
|
|
|
@node The Store Monad
|
|
@section The Store Monad
|
|
|
|
@cindex monad
|
|
|
|
The procedures that operate on the store described in the previous
|
|
sections all take an open connection to the build daemon as their first
|
|
argument. Although the underlying model is functional, they either have
|
|
side effects or depend on the current state of the store.
|
|
|
|
The former is inconvenient: the connection to the build daemon has to be
|
|
carried around in all those functions, making it impossible to compose
|
|
functions that do not take that parameter with functions that do. The
|
|
latter can be problematic: since store operations have side effects
|
|
and/or depend on external state, they have to be properly sequenced.
|
|
|
|
@cindex monadic values
|
|
@cindex monadic functions
|
|
This is where the @code{(guix monads)} module comes in. This module
|
|
provides a framework for working with @dfn{monads}, and a particularly
|
|
useful monad for our uses, the @dfn{store monad}. Monads are a
|
|
construct that allows two things: associating ``context'' with values
|
|
(in our case, the context is the store), and building sequences of
|
|
computations (here computations include accesses to the store). Values
|
|
in a monad---values that carry this additional context---are called
|
|
@dfn{monadic values}; procedures that return such values are called
|
|
@dfn{monadic procedures}.
|
|
|
|
Consider this ``normal'' procedure:
|
|
|
|
@example
|
|
(define (sh-symlink store)
|
|
;; Return a derivation that symlinks the 'bash' executable.
|
|
(let* ((drv (package-derivation store bash))
|
|
(out (derivation->output-path drv))
|
|
(sh (string-append out "/bin/bash")))
|
|
(build-expression->derivation store "sh"
|
|
`(symlink ,sh %output))))
|
|
@end example
|
|
|
|
Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
|
|
as a monadic function:
|
|
|
|
@example
|
|
(define (sh-symlink)
|
|
;; Same, but return a monadic value.
|
|
(mlet %store-monad ((drv (package->derivation bash)))
|
|
(gexp->derivation "sh"
|
|
#~(symlink (string-append #$drv "/bin/bash")
|
|
#$output))))
|
|
@end example
|
|
|
|
There are several things to note in the second version: the @code{store}
|
|
parameter is now implicit and is ``threaded'' in the calls to the
|
|
@code{package->derivation} and @code{gexp->derivation} monadic
|
|
procedures, and the monadic value returned by @code{package->derivation}
|
|
is @dfn{bound} using @code{mlet} instead of plain @code{let}.
|
|
|
|
As it turns out, the call to @code{package->derivation} can even be
|
|
omitted since it will take place implicitly, as we will see later
|
|
(@pxref{G-Expressions}):
|
|
|
|
@example
|
|
(define (sh-symlink)
|
|
(gexp->derivation "sh"
|
|
#~(symlink (string-append #$bash "/bin/bash")
|
|
#$output)))
|
|
@end example
|
|
|
|
@c See
|
|
@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
|
|
@c for the funny quote.
|
|
Calling the monadic @code{sh-symlink} has no effect. As someone once
|
|
said, ``you exit a monad like you exit a building on fire: by running''.
|
|
So, to exit the monad and get the desired effect, one must use
|
|
@code{run-with-store}:
|
|
|
|
@example
|
|
(run-with-store (open-connection) (sh-symlink))
|
|
@result{} /gnu/store/...-sh-symlink
|
|
@end example
|
|
|
|
Note that the @code{(guix monad-repl)} module extends the Guile REPL with
|
|
new ``meta-commands'' to make it easier to deal with monadic procedures:
|
|
@code{run-in-store}, and @code{enter-store-monad}. The former is used
|
|
to ``run'' a single monadic value through the store:
|
|
|
|
@example
|
|
scheme@@(guile-user)> ,run-in-store (package->derivation hello)
|
|
$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
|
|
@end example
|
|
|
|
The latter enters a recursive REPL, where all the return values are
|
|
automatically run through the store:
|
|
|
|
@example
|
|
scheme@@(guile-user)> ,enter-store-monad
|
|
store-monad@@(guile-user) [1]> (package->derivation hello)
|
|
$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
|
|
store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
|
|
$3 = "/gnu/store/@dots{}-foo"
|
|
store-monad@@(guile-user) [1]> ,q
|
|
scheme@@(guile-user)>
|
|
@end example
|
|
|
|
@noindent
|
|
Note that non-monadic values cannot be returned in the
|
|
@code{store-monad} REPL.
|
|
|
|
The main syntactic forms to deal with monads in general are provided by
|
|
the @code{(guix monads)} module and are described below.
|
|
|
|
@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
|
|
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
|
|
in @var{monad}.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Syntax} return @var{val}
|
|
Return a monadic value that encapsulates @var{val}.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
|
|
@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
|
|
procedures @var{mproc}@dots{}@footnote{This operation is commonly
|
|
referred to as ``bind'', but that name denotes an unrelated procedure in
|
|
Guile. Thus we use this somewhat cryptic symbol inherited from the
|
|
Haskell language.}. There can be one @var{mproc} or several of them, as
|
|
in this example:
|
|
|
|
@example
|
|
(run-with-state
|
|
(with-monad %state-monad
|
|
(>>= (return 1)
|
|
(lambda (x) (return (+ 1 x)))
|
|
(lambda (x) (return (* 2 x)))))
|
|
'some-state)
|
|
|
|
@result{} 4
|
|
@result{} some-state
|
|
@end example
|
|
@end deffn
|
|
|
|
@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
|
|
@var{body} ...
|
|
@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
|
|
@var{body} ...
|
|
Bind the variables @var{var} to the monadic values @var{mval} in
|
|
@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
|
|
``normal'' value @var{val}, as per @code{let}.
|
|
|
|
@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
|
|
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
|
|
@end deffn
|
|
|
|
@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
|
|
Bind @var{mexp} and the following monadic expressions in sequence,
|
|
returning the result of the last expression.
|
|
|
|
This is akin to @code{mlet}, except that the return values of the
|