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.
21065 lines
769 KiB
21065 lines
769 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 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
|
|
|
|
@copying
|
|
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 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, 2017 Leo Famulari@*
|
|
Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
|
|
Copyright @copyright{} 2016 Ben Woodcroft@*
|
|
Copyright @copyright{} 2016, 2017 Chris Marusich@*
|
|
Copyright @copyright{} 2016, 2017 Efraim Flashner@*
|
|
Copyright @copyright{} 2016 John Darrington@*
|
|
Copyright @copyright{} 2016, 2017 ng0@*
|
|
Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@*
|
|
Copyright @copyright{} 2016 Julien Lepiller@*
|
|
Copyright @copyright{} 2016 Alex ter Weele@*
|
|
Copyright @copyright{} 2017 Clément Lassieur@*
|
|
Copyright @copyright{} 2017 Mathieu Othacehe@*
|
|
Copyright @copyright{} 2017 Federico Beffa@*
|
|
Copyright @copyright{} 2017 Carlo Zancanaro@*
|
|
Copyright @copyright{} 2017 Thomas Danckaert@*
|
|
Copyright @copyright{} 2017 humanitiesNerd@*
|
|
Copyright @copyright{} 2017 Christopher Allan Webber@*
|
|
Copyright @copyright{} 2017 Marius Bakke@*
|
|
Copyright @copyright{} 2017 Hartmut Goebel@*
|
|
Copyright @copyright{} 2017 Maxim Cournoyer@*
|
|
Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
|
|
Copyright @copyright{} 2017 George Clemmer@*
|
|
Copyright @copyright{} 2017 Andy Wingo@*
|
|
Copyright @copyright{} 2017, 2018 Arun Isaac@*
|
|
Copyright @copyright{} 2017 nee@*
|
|
Copyright @copyright{} 2018 Rutger Helling
|
|
|
|
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 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.
|
|
* guix build: (guix)Invoking guix build. Building packages.
|
|
* guix pack: (guix)Invoking guix pack. Creating binary bundles.
|
|
@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.
|
|
* 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.
|
|
* SELinux Support:: Using an SELinux policy for the daemon.
|
|
|
|
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 pack:: Creating software bundles.
|
|
* Invoking guix archive:: Exporting and importing store files.
|
|
|
|
Substitutes
|
|
|
|
* Official Substitute Server:: One particular source of substitutes.
|
|
* Substitute Server Authorization:: How to enable or disable substitutes.
|
|
* Substitute Authentication:: How Guix verifies substitutes.
|
|
* Proxy Settings:: How to get substitutes via proxy.
|
|
* Substitution Failure:: What happens when substitution fails.
|
|
* On Trusting Binaries:: How can you trust that binary blob?
|
|
|
|
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 copy:: Copying to and from a remote store.
|
|
* Invoking guix container:: Process isolation.
|
|
* Invoking guix weather:: Assessing substitute availability.
|
|
|
|
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'.
|
|
* Debugging Build Failures:: Real life packaging experience.
|
|
|
|
GNU Distribution
|
|
|
|
* System Installation:: Installing the whole operating system.
|
|
* System Configuration:: Configuring the operating system.
|
|
* Documentation:: Browsing software user manuals.
|
|
* 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 and DVD 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.
|
|
* Bootloader 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.
|
|
* Log Rotation:: The rottlog service.
|
|
* Networking Services:: Network setup, SSH daemon, etc.
|
|
* X Window:: Graphical display.
|
|
* Printing Services:: Local and remote printer support.
|
|
* Desktop Services:: D-Bus and desktop services.
|
|
* Database Services:: SQL databases, key-value stores, etc.
|
|
* Mail Services:: IMAP, POP3, SMTP, and all that.
|
|
* Messaging Services:: Messaging services.
|
|
* Telephony Services:: Telephony services.
|
|
* Monitoring Services:: Monitoring services.
|
|
* Kerberos Services:: Kerberos services.
|
|
* Web Services:: Web servers.
|
|
* Certificate Services:: TLS certificates via Let's Encrypt.
|
|
* DNS Services:: DNS daemons.
|
|
* VPN Services:: VPN daemons.
|
|
* Network File System:: NFS related services.
|
|
* Continuous Integration:: The Cuirass service.
|
|
* Power management Services:: The TLP tool.
|
|
* Audio Services:: The MPD.
|
|
* Virtualization Services:: Virtualization services.
|
|
* Version Control Services:: Providing remote access to Git repositories.
|
|
* Game Services:: Game 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:: A touch of British comedy.
|
|
* 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}), 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
|
|
|
|
@cindex installing Guix
|
|
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.
|
|
|
|
Once installed, Guix can be updated by running @command{guix pull}
|
|
(@pxref{Invoking guix pull}).
|
|
|
|
@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
|
|
|
|
@cindex installing Guix from binaries
|
|
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.
|
|
|
|
We provide a
|
|
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
|
|
shell installer script}, which automates the download, installation, and
|
|
initial configuration of Guix. It should be run as the root user.
|
|
|
|
Installing goes along these lines:
|
|
|
|
@enumerate
|
|
@item
|
|
@cindex downloading Guix binary
|
|
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
|
|
|
|
Source @file{etc/profile} to augment @code{PATH} and other relevant
|
|
environment variables:
|
|
|
|
@example
|
|
# GUIX_PROFILE=$HOME/.guix-profile ; \
|
|
source $GUIX_PROFILE/etc/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:
|
|
|
|
@c Versions of systemd that supported symlinked service files are not
|
|
@c yet widely deployed, so we should suggest that users copy the service
|
|
@c files into place.
|
|
@c
|
|
@c See this thread for more information:
|
|
@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
|
|
|
|
@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
|
|
# initctl reload-configuration
|
|
# 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
|
|
@cindex substitutes, authorization thereof
|
|
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
|
|
|
|
@item
|
|
Each user may need to perform a few additional steps to make their Guix
|
|
environment ready for use, @pxref{Application Setup}.
|
|
@end enumerate
|
|
|
|
Voilà, the installation is complete!
|
|
|
|
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
|
|
|
|
@noindent
|
|
... which, in turn, runs:
|
|
|
|
@example
|
|
guix pack -s @var{system} --localstatedir guix
|
|
@end example
|
|
|
|
@xref{Invoking guix pack}, for more info on this handy tool.
|
|
|
|
@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.9 or
|
|
later, including 2.2.x;
|
|
@item @url{http://gnupg.org/, GNU libgcrypt};
|
|
@item
|
|
@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
|
|
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
|
|
Guile,, gnutls-guile, GnuTLS-Guile});
|
|
@item
|
|
@c FIXME: Specify a version number once a release has been made.
|
|
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
|
|
2017 or later;
|
|
@item @url{http://zlib.net, zlib};
|
|
@item @url{http://www.gnu.org/software/make/, GNU Make}.
|
|
@end itemize
|
|
|
|
The following dependencies are optional:
|
|
|
|
@itemize
|
|
@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
|
|
@c Note: We need at least 0.10.2 for 'channel-send-eof'.
|
|
Support for build offloading (@pxref{Daemon Offload Setup}) and
|
|
@command{guix copy} (@pxref{Invoking guix copy}) depends on
|
|
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
|
|
version 0.10.2 or later.
|
|
|
|
@item
|
|
When @url{http://www.bzip.org, libbz2} is available,
|
|
@command{guix-daemon} can use it to compress build logs.
|
|
@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://gcc.gnu.org, GCC's g++}, with support for the
|
|
C++11 standard.
|
|
@end itemize
|
|
|
|
@cindex state directory
|
|
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}).
|
|
|
|
@cindex Nix, compatibility
|
|
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
|
|
|
|
@cindex 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.
|
|
* SELinux Support:: Using an SELinux policy for the daemon.
|
|
@end menu
|
|
|
|
@node Build Environment Setup
|
|
@subsection Build Environment Setup
|
|
|
|
@cindex build environment
|
|
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}@footnote{This feature is available only when
|
|
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
|
|
present.}. 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")
|
|
(host-key "ssh-ed25519 AAAAC3Nza@dots{}")
|
|
(user "bob")
|
|
(speed 2.)) ;incredibly fast!
|
|
|
|
(build-machine
|
|
(name "meeps.example.org")
|
|
(system "mips64el-linux")
|
|
(host-key "ssh-rsa AAAAB3Nza@dots{}")
|
|
(user "alice")
|
|
(private-key
|
|
(string-append (getenv "HOME")
|
|
"/.ssh/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.
|
|
|
|
@item host-key
|
|
This must be the machine's SSH @dfn{public host key} in OpenSSH format.
|
|
This is used to authenticate the machine when we connect to it. It is a
|
|
long string that looks like this:
|
|
|
|
@example
|
|
ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
|
|
@end example
|
|
|
|
If the machine is running the OpenSSH daemon, @command{sshd}, the host
|
|
key can be found in a file such as
|
|
@file{/etc/ssh/ssh_host_ed25519_key.pub}.
|
|
|
|
If the machine is running the SSH daemon of GNU@tie{}lsh,
|
|
@command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
|
|
similar file. It can be converted to the OpenSSH format using
|
|
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
|
|
|
|
@example
|
|
$ lsh-export-key --openssh < /etc/lsh/host-key.pub
|
|
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
|
|
@end example
|
|
|
|
@end table
|
|
|
|
A number of optional fields may be specified:
|
|
|
|
@table @asis
|
|
|
|
@item @code{port} (default: @code{22})
|
|
Port number of SSH server on the machine.
|
|
|
|
@item @code{private-key} (default: @file{~root/.ssh/id_rsa})
|
|
The SSH private key file to use when connecting to the machine, in
|
|
OpenSSH format.
|
|
|
|
Note that the default value is the private key @emph{of the root
|
|
account}. Make sure it exists if you use the default.
|
|
|
|
@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
|
|
@itemx @code{compression-level} (default: @code{3})
|
|
The SSH-level compression methods and compression level requested.
|
|
|
|
Note that offloading relies on SSH compression to reduce bandwidth usage
|
|
when transferring files to and from build machines.
|
|
|
|
@item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
|
|
File name of the Unix-domain socket @command{guix-daemon} is listening
|
|
to on that machine.
|
|
|
|
@item @code{parallel-builds} (default: @code{1})
|
|
The number of builds that may run in parallel on the machine.
|
|
|
|
@item @code{speed} (default: @code{1.0})
|
|
A ``relative speed factor''. The offload scheduler will tend to prefer
|
|
machines with a higher speed factor.
|
|
|
|
@item @code{features} (default: @code{'()})
|
|
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{guile} command must be in the search path on the build
|
|
machines. 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
|
|
ssh 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.
|
|
|
|
@cindex offload test
|
|
To test whether your setup is operational, run this command on the
|
|
master node:
|
|
|
|
@example
|
|
# guix offload test
|
|
@end example
|
|
|
|
This will attempt to connect to each of the build machines specified in
|
|
@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are
|
|
available on each machine, attempt to export to the machine and import
|
|
from it, and report any error in the process.
|
|
|
|
If you want to test a different machine file, just specify it on the
|
|
command line:
|
|
|
|
@example
|
|
# guix offload test machines-qualif.scm
|
|
@end example
|
|
|
|
Last, you can test the subset of the machines whose name matches a
|
|
regular expression like this:
|
|
|
|
@example
|
|
# guix offload test machines.scm '\.gnu\.org$'
|
|
@end example
|
|
|
|
@cindex offload status
|
|
To display the current load of all build hosts, run this command on the
|
|
main node:
|
|
|
|
@example
|
|
# guix offload status
|
|
@end example
|
|
|
|
|
|
@node SELinux Support
|
|
@subsection SELinux Support
|
|
|
|
@cindex SELinux, daemon policy
|
|
@cindex mandatory access control, SELinux
|
|
@cindex security, guix-daemon
|
|
Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
|
|
can be installed on a system where SELinux is enabled, in order to label
|
|
Guix files and to specify the expected behavior of the daemon. Since
|
|
GuixSD does not provide an SELinux base policy, the daemon policy cannot
|
|
be used on GuixSD.
|
|
|
|
@subsubsection Installing the SELinux policy
|
|
@cindex SELinux, policy installation
|
|
To install the policy run this command as root:
|
|
|
|
@example
|
|
semodule -i etc/guix-daemon.cil
|
|
@end example
|
|
|
|
Then relabel the file system with @code{restorecon} or by a different
|
|
mechanism provided by your system.
|
|
|
|
Once the policy is installed, the file system has been relabeled, and
|
|
the daemon has been restarted, it should be running in the
|
|
@code{guix_daemon_t} context. You can confirm this with the following
|
|
command:
|
|
|
|
@example
|
|
ps -Zax | grep guix-daemon
|
|
@end example
|
|
|
|
Monitor the SELinux log files as you run a command like @code{guix build
|
|
hello} to convince yourself that SELinux permits all necessary
|
|
operations.
|
|
|
|
@subsubsection Limitations
|
|
@cindex SELinux, limitations
|
|
|
|
This policy is not perfect. Here is a list of limitations or quirks
|
|
that should be considered when deploying the provided SELinux policy for
|
|
the Guix daemon.
|
|
|
|
@enumerate
|
|
@item
|
|
@code{guix_daemon_socket_t} isn’t actually used. None of the socket
|
|
operations involve contexts that have anything to do with
|
|
@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
|
|
but it would be preferrable to define socket rules for only this label.
|
|
|
|
@item
|
|
@code{guix gc} cannot access arbitrary links to profiles. By design,
|
|
the file label of the destination of a symlink is independent of the
|
|
file label of the link itself. Although all profiles under
|
|
$localstatedir are labelled, the links to these profiles inherit the
|
|
label of the directory they are in. For links in the user’s home
|
|
directory this will be @code{user_home_t}. But for links from the root
|
|
user’s home directory, or @file{/tmp}, or the HTTP server’s working
|
|
directory, etc, this won’t work. @code{guix gc} would be prevented from
|
|
reading and following these links.
|
|
|
|
@item
|
|
The daemon’s feature to listen for TCP connections might no longer work.
|
|
This might require extra rules, because SELinux treats network sockets
|
|
differently from files.
|
|
|
|
@item
|
|
Currently all files with a name matching the regular expression
|
|
@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
|
|
label @code{guix_daemon_exec_t}; this means that @emph{any} file with
|
|
that name in any profile would be permitted to run in the
|
|
@code{guix_daemon_t} domain. This is not ideal. An attacker could
|
|
build a package that provides this executable and convince a user to
|
|
install and run it, which lifts it into the @code{guix_daemon_t} domain.
|
|
At that point SELinux could not prevent it from accessing files that are
|
|
allowed for processes in that domain.
|
|
|
|
We could generate a much more restrictive policy at installation time,
|
|
so that only the @emph{exact} file name of the currently installed
|
|
@code{guix-daemon} executable would be labelled with
|
|
@code{guix_daemon_exec_t}, instead of using a broad regular expression.
|
|
The downside is that root would have to install or upgrade the policy at
|
|
installation time whenever the Guix package that provides the
|
|
effectively running @code{guix-daemon} executable is upgraded.
|
|
@end enumerate
|
|
|
|
@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}).
|
|
|
|
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 --max-silent-time=@var{seconds}
|
|
When the build or substitution process remains silent for more than
|
|
@var{seconds}, terminate it and report a build failure.
|
|
|
|
The default value is @code{0}, which disables the timeout.
|
|
|
|
The value specified here can be overridden by clients (@pxref{Common
|
|
Build Options, @code{--max-silent-time}}).
|
|
|
|
@item --timeout=@var{seconds}
|
|
Likewise, when the build or substitution process lasts for more than
|
|
@var{seconds}, terminate it and report a build failure.
|
|
|
|
The default value is @code{0}, which disables the timeout.
|
|
|
|
The value specified here can be overridden by clients (@pxref{Common
|
|
Build Options, @code{--timeout}}).
|
|
|
|
@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 --log-compression=@var{type}
|
|
Compress build logs according to @var{type}, one of @code{gzip},
|
|
@code{bzip2}, or @code{none}.
|
|
|
|
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.
|
|
|
|
@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.
|
|
|
|
@cindex GC roots
|
|
@cindex garbage collector roots
|
|
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.
|
|
@xref{Invoking guix gc}, for more on 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{endpoint}
|
|
Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
|
|
as the file name of a Unix-domain socket if it starts with
|
|
@code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
|
|
host name or host name and port to listen to. Here are a few examples:
|
|
|
|
@table @code
|
|
@item --listen=/gnu/var/daemon
|
|
Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
|
|
creating it if needed.
|
|
|
|
@item --listen=localhost
|
|
@cindex daemon, remote access
|
|
@cindex remote access to the daemon
|
|
@cindex daemon, cluster setup
|
|
@cindex clusters, daemon setup
|
|
Listen for TCP connections on the network interface corresponding to
|
|
@code{localhost}, on port 44146.
|
|
|
|
@item --listen=128.0.0.42:1234
|
|
Listen for TCP connections on the network interface corresponding to
|
|
@code{128.0.0.42}, on port 1234.
|
|
@end table
|
|
|
|
This option can be repeated multiple times, in which case
|
|
@command{guix-daemon} accepts connections on all the specified
|
|
endpoints. Users can tell client commands what endpoint to connect to
|
|
by setting the @code{GUIX_DAEMON_SOCKET} environment variable
|
|
(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).
|
|
|
|
@quotation Note
|
|
The daemon protocol is @emph{unauthenticated and unencrypted}. Using
|
|
@code{--listen=@var{host}} is suitable on local networks, such as
|
|
clusters, where only trusted nodes may connect to the build daemon. In
|
|
other cases where remote access to the daemon is needed, we recommend
|
|
using Unix-domain sockets along with SSH.
|
|
@end quotation
|
|
|
|
When @code{--listen} is omitted, @command{guix-daemon} listens for
|
|
connections on the Unix-domain socket located at
|
|
@file{@var{localstatedir}/guix/daemon-socket/socket}.
|
|
@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 Name Service Switch
|
|
|
|
@cindex name service switch, glibc
|
|
@cindex NSS (name service switch), glibc
|
|
@cindex nscd (name service caching daemon)
|
|
@cindex name service caching daemon (nscd)
|
|
When using Guix on a foreign distro, we @emph{strongly recommend} that
|
|
the system run the GNU C library's @dfn{name service cache daemon},
|
|
@command{nscd}, which should be listening on the
|
|
@file{/var/run/nscd/socket} socket. Failing to do that, applications
|
|
installed with Guix may fail to look up host names or user accounts, or
|
|
may even crash. The next paragraphs explain why.
|
|
|
|
@cindex @file{nsswitch.conf}
|
|
The GNU C library implements a @dfn{name service switch} (NSS), which is
|
|
an extensible mechanism for ``name lookups'' in general: host name
|
|
resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
|
|
The GNU C Library Reference Manual}).
|
|
|
|
@cindex Network information service (NIS)
|
|
@cindex NIS (Network information service)
|
|
Being extensible, the NSS supports @dfn{plugins}, which provide new name
|
|
lookup implementations: for example, the @code{nss-mdns} plugin allow
|
|
resolution of @code{.local} host names, the @code{nis} plugin allows
|
|
user account lookup using the Network information service (NIS), and so
|
|
on. These extra ``lookup services'' are configured system-wide in
|
|
@file{/etc/nsswitch.conf}, and all the programs running on the system
|
|
honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
|
|
Reference Manual}).
|
|
|
|
When they perform a name lookup---for instance by calling the
|
|
@code{getaddrinfo} function in C---applications first try to connect to
|
|
the nscd; on success, nscd performs name lookups on their behalf. If
|
|
the nscd is not running, then they perform the name lookup by
|
|
themselves, by loading the name lookup services into their own address
|
|
space and running it. These name lookup services---the
|
|
@file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
|
|
the host system's C library, rather than from the C library the
|
|
application is linked against (the C library coming from Guix).
|
|
|
|
And this is where the problem is: if your application is linked against
|
|
Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
|
|
another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
|
|
likely crash or have its name lookups fail unexpectedly.
|
|
|
|
Running @command{nscd} on the system, among other advantages, eliminates
|
|
this binary incompatibility problem because those @code{libnss_*.so}
|
|
files are loaded in the @command{nscd} process, not in applications
|
|
themselves.
|
|
|
|
@subsection X11 Fonts
|
|
|
|
@cindex 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
|
|
|
|
@cindex @code{xterm}
|
|
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
|
|
|
|
@cindex @code{xlsfonts}
|
|
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
|
|
to make sure your TrueType fonts are listed there.
|
|
|
|
@cindex @code{fc-cache}
|
|
@cindex font cache
|
|
After installing fonts you may have to refresh the font cache to use
|
|
them in applications. The same applies when applications installed via
|
|
Guix do not seem to find fonts. To force rebuilding of the font cache
|
|
run @code{fc-cache -f}. The @code{fc-cache} command is provided by the
|
|
@code{fontconfig} package.
|
|
|
|
@subsection X.509 Certificates
|
|
|
|
@cindex @code{nss-certs}
|
|
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
|
|
|
|
@cindex @code{emacs}
|
|
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 not be
|
|
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}).
|
|
|
|
@subsection The GCC toolchain
|
|
|
|
@cindex GCC
|
|
@cindex ld-wrapper
|
|
|
|
Guix offers individual compiler packages such as @code{gcc} but if you
|
|
are in need of a complete toolchain for compiling and linking source
|
|
code what you really want is the @code{gcc-toolchain} package. This
|
|
package provides a complete GCC toolchain for C/C++ development,
|
|
including GCC itself, the GNU C Library (headers and binaries, plus
|
|
debugging symbols in the @code{debug} output), Binutils, and a linker
|
|
wrapper.
|
|
|
|
@cindex attempt to use impure library, error message
|
|
|
|
The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
|
|
passed to the linker, add corresponding @code{-rpath} arguments, and
|
|
invoke the actual linker with this new set of arguments. By default,
|
|
the linker wrapper refuses to link to libraries outside the store to
|
|
ensure ``purity''. This can be annoying when using the toolchain to
|
|
link with local libraries. To allow references to libraries outside the
|
|
store you need to define the environment variable
|
|
@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.
|
|
|
|
@c TODO What else?
|
|
|
|
@c *********************************************************************
|
|
@node Package Management
|
|
@chapter Package Management
|
|
|
|
@cindex packages
|
|
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. Along with the command-line
|
|
interface described below (@pxref{Invoking guix package, @code{guix
|
|
package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
|
|
emacs-guix, The Emacs-Guix Reference Manual}), after installing
|
|
@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
|
|
with it):
|
|
|
|
@example
|
|
guix package -i emacs-guix
|
|
@end example
|
|
|
|
@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 pack:: Creating software bundles.
|
|
* 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.
|
|
|
|
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}.
|
|
|
|
@cindex transactions
|
|
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}
|
|
|
|
@cindex installing packages
|
|
@cindex removing packages
|
|
@cindex package installation
|
|
@cindex package removal
|
|
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
|
|
@cindex transactions
|
|
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}}).
|
|
|
|
@cindex profile
|
|
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}/guix/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{}]
|
|
@cindex upgrading packages
|
|
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
|
|
|
|
@findex specifications->manifest
|
|
In this example we have to know which modules define the @code{emacs}
|
|
and @code{guile-2.0} variables to provide the right
|
|
@code{use-package-modules} line, which can be cumbersome. We can
|
|
instead provide regular package specifications and let
|
|
@code{specifications->manifest} look up the corresponding package
|
|
objects, like this:
|
|
|
|
@example
|
|
(specifications->manifest
|
|
'("emacs" "guile@@2.2" "guile@@2.2:debug"))
|
|
@end example
|
|
|
|
@item --roll-back
|
|
@cindex rolling back
|
|
@cindex undoing transactions
|
|
@cindex transactions, undoing
|
|
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}
|
|
@cindex generations
|
|
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}, sorted by relevance. 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,relevance
|
|
name: jemalloc
|
|
version: 4.5.0
|
|
relevance: 6
|
|
|
|
name: glibc
|
|
version: 2.25
|
|
relevance: 1
|
|
|
|
name: libgc
|
|
version: 7.6.0
|
|
relevance: 1
|
|
@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}]
|
|
@cindex generations
|
|
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, or both. 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.
|
|
|
|
@menu
|
|
* Official Substitute Server:: One particular source of substitutes.
|
|
* Substitute Server Authorization:: How to enable or disable substitutes.
|
|
* Substitute Authentication:: How Guix verifies substitutes.
|
|
* Proxy Settings:: How to get substitutes via proxy.
|
|
* Substitution Failure:: What happens when substitution fails.
|
|
* On Trusting Binaries:: How can you trust that binary blob?
|
|
@end menu
|
|
|
|
@node Official Substitute Server
|
|
@subsection Official Substitute Server
|
|
|
|
@cindex hydra
|
|
@cindex build farm
|
|
The @code{mirror.hydra.gnu.org} server is a front-end to an official build farm
|
|
that builds packages from Guix continuously for some
|
|
architectures, and makes them available as substitutes. This is the
|
|
default source of substitutes; it can be overridden by passing the
|
|
@option{--substitute-urls} option either to @command{guix-daemon}
|
|
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
|
|
or to client tools such as @command{guix package}
|
|
(@pxref{client-substitute-urls,, client @option{--substitute-urls}
|
|
option}).
|
|
|
|
Substitute URLs can be either HTTP or HTTPS.
|
|
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.
|
|
|
|
Substitutes from the official build farm are enabled by default when
|
|
using the Guix System Distribution (@pxref{GNU Distribution}). However,
|
|
they are disabled by default when using Guix on a foreign distribution,
|
|
unless you have explicitly enabled them via one of the recommended
|
|
installation steps (@pxref{Installation}). The following paragraphs
|
|
describe how to enable or disable substitutes for the official build
|
|
farm; the same procedure can also be used to enable substitutes for any
|
|
other substitute server.
|
|
|
|
@node Substitute Server Authorization
|
|
@subsection Substitute Server Authorization
|
|
|
|
@cindex security
|
|
@cindex substitutes, authorization thereof
|
|
@cindex access control list (ACL), for substitutes
|
|
@cindex ACL (access control list), for substitutes
|
|
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.
|
|
|
|
The public key for @code{hydra.gnu.org} 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 < @var{prefix}/share/guix/hydra.gnu.org.pub
|
|
@end example
|
|
|
|
@quotation Note
|
|
Similarly, the @file{berlin.guixsd.org.pub} file contains the public key
|
|
for the project's new build farm, reachable at
|
|
@indicateurl{https://berlin.guixsd.org}.
|
|
|
|
As of this writing @code{berlin.guixsd.org} is being upgraded so it can
|
|
better scale up, but you might want to give it a try. It is backed by
|
|
20 x86_64/i686 build nodes and may be able to provide substitutes more
|
|
quickly than @code{mirror.hydra.gnu.org}.
|
|
@end quotation
|
|
|
|
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
|
|
112.3 MB 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.
|
|
|
|
@cindex substitutes, how to disable
|
|
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.
|
|
|
|
@node Substitute Authentication
|
|
@subsection Substitute Authentication
|
|
|
|
@cindex digital signatures
|
|
Guix detects and raises an error when attempting to use a substitute
|
|
that has been tampered with. Likewise, it ignores substitutes that are
|
|
not signed, or that are not signed by one of the keys listed in the ACL.
|
|
|
|
There is one exception though: if an unauthorized server provides
|
|
substitutes that are @emph{bit-for-bit identical} to those provided by
|
|
an authorized server, then the unauthorized server becomes eligible for
|
|
downloads. For example, assume we have chosen two substitute servers
|
|
with this option:
|
|
|
|
@example
|
|
--substitute-urls="https://a.example.org https://b.example.org"
|
|
@end example
|
|
|
|
@noindent
|
|
@cindex reproducible builds
|
|
If the ACL contains only the key for @code{b.example.org}, and if
|
|
@code{a.example.org} happens to serve the @emph{exact same} substitutes,
|
|
then Guix will download substitutes from @code{a.example.org} because it
|
|
comes first in the list and can be considered a mirror of
|
|
@code{b.example.org}. In practice, independent build machines usually
|
|
produce the same binaries, thanks to bit-reproducible builds (see
|
|
below).
|
|
|
|
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.)
|
|
|
|
@node Proxy Settings
|
|
@subsection Proxy Settings
|
|
|
|
@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}.
|
|
|
|
@node Substitution Failure
|
|
@subsection Substitution Failure
|
|
|
|
Even when a substitute for a derivation is available, sometimes the
|
|
substitution attempt will fail. This can happen for a variety of
|
|
reasons: the substitute server might be offline, the substitute may
|
|
recently have been deleted, the connection might have been interrupted,
|
|
etc.
|
|
|
|
When substitutes are enabled and a substitute for a derivation is
|
|
available, but the substitution attempt fails, Guix will attempt to
|
|
build the derivation locally depending on whether or not
|
|
@code{--fallback} was given (@pxref{fallback-option,, common build
|
|
option @code{--fallback}}). Specifically, if @code{--fallback} was
|
|
omitted, then no local build will be performed, and the derivation is
|
|
considered to have failed. However, if @code{--fallback} was given,
|
|
then Guix will attempt to build the derivation locally, and the success
|
|
or failure of the derivation depends on the success or failure of the
|
|
local build. Note that when substitutes are disabled or no substitute
|
|
is available for the derivation in question, a local build will
|
|
@emph{always} be performed, regardless of whether or not
|
|
@code{--fallback} was given.
|
|
|
|
To get an idea of how many substitutes are available right now, you can
|
|
try running the @command{guix weather} command (@pxref{Invoking guix
|
|
weather}). This command provides statistics on the substitutes provided
|
|
by a server.
|
|
|
|
@node On Trusting Binaries
|
|
@subsection On Trusting Binaries
|
|
|
|
@cindex trust, of pre-built 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
|
|
@cindex 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
|
|
|
|
@cindex documentation
|
|
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
|
|
@cindex disk space
|
|
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!
|
|
|
|
@cindex GC roots
|
|
@cindex garbage collector roots
|
|
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 (``GC roots'' for short)
|
|
includes default user profiles; by default, the symlinks under
|
|
@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
|
|
added 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}).
|
|
|
|
Our recommendation is to run a garbage collection periodically, or when
|
|
you are short on disk space. For instance, to guarantee that at least
|
|
5@tie{}GB are available on your disk, simply run:
|
|
|
|
@example
|
|
guix gc -F 5G
|
|
@end example
|
|
|
|
It is perfectly safe to run as a non-interactive periodic job
|
|
(@pxref{Scheduled Job Execution}, for how to set up such a job on
|
|
GuixSD). Running @command{guix gc} with no arguments will collect as
|
|
much garbage as it can, but that is often inconvenient: you may find
|
|
yourself having to rebuild or re-download software that is ``dead'' from
|
|
the GC viewpoint but that is necessary to build other pieces of
|
|
software---e.g., the compiler tool chain.
|
|
|
|
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
|
|
@cindex package dependencies
|
|
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
|
|
@cindex corruption, recovering from
|
|
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. A lightweight alternative, when you know exactly
|
|
which items in the store are corrupt, is @command{guix build --repair}
|
|
(@pxref{Invoking guix build}).
|
|
|
|
@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}
|
|
|
|
@cindex upgrading Guix
|
|
@cindex updating Guix
|
|
@cindex @command{guix pull}
|
|
@cindex 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. Source code is downloaded from a
|
|
@uref{https://git-scm.com, Git} repository.
|
|
|
|
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. Currently, the
|
|
only way to roll back an invocation of @command{guix pull} is to
|
|
manually update this symlink to point to the previous Guix.}.
|
|
|
|
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 Guix from the Git repository at @var{url}.
|
|
|
|
@vindex GUIX_PULL_URL
|
|
By default, the source is taken from its canonical Git repository at
|
|
@code{gnu.org}, for the stable branch of Guix. To use a different source,
|
|
set the @code{GUIX_PULL_URL} environment variable.
|
|
|
|
@item --commit=@var{commit}
|
|
Deploy @var{commit}, a valid Git commit ID represented as a hexadecimal
|
|
string.
|
|
|
|
@item --branch=@var{branch}
|
|
Deploy the tip of @var{branch}, the name of a Git branch available on
|
|
the repository at @var{url}.
|
|
|
|
@item --bootstrap
|
|
Use the bootstrap Guile to build the latest Guix. This option is only
|
|
useful to Guix developers.
|
|
@end table
|
|
|
|
In addition, @command{guix pull} supports all the common build options
|
|
(@pxref{Common Build Options}).
|
|
|
|
@node Invoking guix pack
|
|
@section Invoking @command{guix pack}
|
|
|
|
Occasionally you want to pass software to people who are not (yet!)
|
|
lucky enough to be using Guix. You'd tell them to run @command{guix
|
|
package -i @var{something}}, but that's not possible in this case. This
|
|
is where @command{guix pack} comes in.
|
|
|
|
@quotation Note
|
|
If you are looking for ways to exchange binaries among machines that
|
|
already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
|
|
publish}, and @ref{Invoking guix archive}.
|
|
@end quotation
|
|
|
|
@cindex pack
|
|
@cindex bundle
|
|
@cindex application bundle
|
|
@cindex software bundle
|
|
The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
|
|
@dfn{software bundle}: it creates a tarball or some other archive
|
|
containing the binaries of the software you're interested in, and all
|
|
its dependencies. The resulting archive can be used on any machine that
|
|
does not have Guix, and people can run the exact same binaries as those
|
|
you have with Guix. The pack itself is created in a bit-reproducible
|
|
fashion, so anyone can verify that it really contains the build results
|
|
that you pretend to be shipping.
|
|
|
|
For example, to create a bundle containing Guile, Emacs, Geiser, and all
|
|
their dependencies, you can run:
|
|
|
|
@example
|
|
$ guix pack guile emacs geiser
|
|
@dots{}
|
|
/gnu/store/@dots{}-pack.tar.gz
|
|
@end example
|
|
|
|
The result here is a tarball containing a @file{/gnu/store} directory
|
|
with all the relevant packages. The resulting tarball contains a
|
|
@dfn{profile} with the three packages of interest; the profile is the
|
|
same as would be created by @command{guix package -i}. It is this
|
|
mechanism that is used to create Guix's own standalone binary tarball
|
|
(@pxref{Binary Installation}).
|
|
|
|
Users of this pack would have to run
|
|
@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
|
|
find inconvenient. To work around it, you can create, say, a
|
|
@file{/opt/gnu/bin} symlink to the profile:
|
|
|
|
@example
|
|
guix pack -S /opt/gnu/bin=bin guile emacs geiser
|
|
@end example
|
|
|
|
@noindent
|
|
That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
|
|
|
|
Alternatively, you can produce a pack in the Docker image format using
|
|
the following command:
|
|
|
|
@example
|
|
guix pack -f docker guile emacs geiser
|
|
@end example
|
|
|
|
@noindent
|
|
The result is a tarball that can be passed to the @command{docker load}
|
|
command. See the
|
|
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
|
|
documentation} for more information.
|
|
|
|
Several command-line options allow you to customize your pack:
|
|
|
|
@table @code
|
|
@item --format=@var{format}
|
|
@itemx -f @var{format}
|
|
Produce a pack in the given @var{format}.
|
|
|
|
The available formats are:
|
|
|
|
@table @code
|
|
@item tarball
|
|
This is the default format. It produces a tarball containing all the
|
|
specified binaries and symlinks.
|
|
|
|
@item docker
|
|
This produces a tarball that follows the
|
|
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
|
|
Docker Image Specification}.
|
|
@end table
|
|
|
|
@item --expression=@var{expr}
|
|
@itemx -e @var{expr}
|
|
Consider the package @var{expr} evaluates to.
|
|
|
|
This has the same purpose as the same-named option in @command{guix
|
|
build} (@pxref{Additional Build Options, @code{--expression} in
|
|
@command{guix build}}).
|
|
|
|
@item --system=@var{system}
|
|
@itemx -s @var{system}
|
|
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
|
|
the system type of the build host.
|
|
|
|
@item --target=@var{triplet}
|
|
@cindex cross-compilation
|
|
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
|
|
as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
|
|
configuration triplets,, autoconf, Autoconf}).
|
|
|
|
@item --compression=@var{tool}
|
|
@itemx -C @var{tool}
|
|
Compress the resulting tarball using @var{tool}---one of @code{gzip},
|
|
@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
|
|
|
|
@item --symlink=@var{spec}
|
|
@itemx -S @var{spec}
|
|
Add the symlinks specified by @var{spec} to the pack. This option can
|
|
appear several times.
|
|
|
|
@var{spec} has the form @code{@var{source}=@var{target}}, where
|
|
@var{source} is the symlink that will be created and @var{target} is the
|
|
symlink target.
|
|
|
|
For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
|
|
symlink pointing to the @file{bin} sub-directory of the profile.
|
|
|
|
@item --localstatedir
|
|
Include the ``local state directory'', @file{/var/guix}, in the
|
|
resulting pack.
|
|
|
|
@file{/var/guix} contains the store database (@pxref{The Store}) as well
|
|
as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
|
|
the pack means that the store is ``complete'' and manageable by Guix;
|
|
not providing it pack means that the store is ``dead'': items cannot be
|
|
added to it or removed from it after extraction of the pack.
|
|
|
|
One use case for this is the Guix self-contained binary tarball
|
|
(@pxref{Binary Installation}).
|
|
@end table
|
|
|
|
In addition, @command{guix pack} supports all the common build options
|
|
(@pxref{Common Build Options}) and all the package transformation
|
|
options (@pxref{Package Transformation Options}).
|
|
|
|
|
|
@node Invoking guix archive
|
|
@section Invoking @command{guix archive}
|
|
|
|
@cindex @command{guix archive}
|
|
@cindex 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 on
|
|
a machine that runs Guix.
|
|
In particular, it allows store files to be transferred from one machine
|
|
to the store on another machine.
|
|
|
|
@quotation Note
|
|
If you're looking for a way to produce archives in a format suitable for
|
|
tools other than Guix, @pxref{Invoking guix pack}.
|
|
@end quotation
|
|
|
|
@cindex exporting store items
|
|
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. The @command{guix copy}
|
|
command simplifies and optimizes this whole process, so this is probably
|
|
what you should use in this case (@pxref{Invoking guix copy}).
|
|
|
|
@cindex nar, archive format
|
|
@cindex normalized archive (nar)
|
|
Archives are stored in the ``normalized archive'' or ``nar'' format, which is
|
|
comparable in spirit to `tar', but with 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 *********************************************************************
|
|
@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}), troubleshooting any build failures
|
|
you encounter (@pxref{Debugging Build Failures}). 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.
|
|
@vindex GUIX_PACKAGE_PATH
|
|
Lastly, @pxref{Package Modules}, for information
|
|
on how to extend the distribution by adding your own package definitions
|
|
to @code{GUIX_PACKAGE_PATH}.
|
|
|
|
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}}).
|
|
|
|
A more generic procedure to rewrite a package dependency graph is
|
|
@code{package-mapping}: it supports arbitrary changes to nodes in the
|
|
graph.
|
|
|
|
@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
|
|
Return a procedure that, given a package, applies @var{proc} to all the packages
|
|
depended on and returns the resulting package. The procedure stops recursion
|
|
when @var{cut?} returns true for a given package.
|
|
@end deffn
|
|
|
|
@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, 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}
|
|
@cindex license, of packages
|
|
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, origins, or file-like objects (@pxref{G-Expressions,
|
|
file-like objects}) pointing to patches to be applied to the source.
|
|
|
|
This list of patches must be unconditional. In particular, it cannot
|
|
depend on the value of @code{%current-system} or
|
|
@code{%current-target-system}.
|
|
|
|
@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.
|
|