Newer
Older
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@c %**end of header
@include version.texi
@c Identifier of the OpenPGP key used to sign tarballs and such.
@set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
@set BASE-URL https://ftp.gnu.org/gnu/guix
@c The official substitute server used by default.
@set SUBSTITUTE-SERVER ci.guix.gnu.org
@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Taylan Ulrich Bayırlı/Kammer
committed
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, 2019, 2020, 2021 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
Copyright @copyright{} 2018 Alex Vong@*
Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
Copyright @copyright{} 2019 Jakob L. Kreuze@*
Copyright @copyright{} 2019 Kyle Andrews@*
Copyright @copyright{} 2019 Alex Griffin@*
Copyright @copyright{} 2019, 2020, 2021 Guillaume Le Vaillant@*
Copyright @copyright{} 2020 Leo Prikler@*
Copyright @copyright{} 2019, 2020 Simon Tournier@*
Copyright @copyright{} 2020 Wiktor Żelazny@*
Copyright @copyright{} 2020 Damien Cassou@*
Copyright @copyright{} 2020 Jakub Kądziołka@*
Copyright @copyright{} 2020 Jack Hill@*
Copyright @copyright{} 2020 Brice Waegeneire@*
Copyright @copyright{} 2020 R Veera Kumar@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 André Batista@*
Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
Copyright @copyright{} 2020 raingloom@*
Copyright @copyright{} 2020 Daniel Brooks@*
Copyright @copyright{} 2020 John Soo@*
Copyright @copyright{} 2020 Jonathan Brielmaier@*
Copyright @copyright{} 2020 Edgar Vincent@*
Copyright @copyright{} 2021 Maxime Devos@*
Copyright @copyright{} 2021 B. Wilson@*
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
* 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.
* guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
@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.
@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} @*
@end titlepage
@contents
@c *********************************************************************
@node Top
This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
would like to translate it in your native language, consider joining
@uref{https://translate.fedoraproject.org/projects/guix/documentation-manual,
Weblate} (@pxref{Translating Guix}).
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
* Getting Started:: Your first steps.
* Package Management:: Package installation, upgrade, etc.
* Channels:: Customizing the package collection.
* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* System Configuration:: Configuring the operating system.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
* 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 ---
Introduction
* Managing Software the Guix Way:: What's special.
* GNU Distribution:: The packages and tools.
* 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.
* Upgrading Guix:: Upgrading Guix and its build daemon.
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.
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.
* Guided Graphical Installation:: Easy graphical installation.
* Manual Installation:: Manual installation for wizards.
* After System Installation:: When installation succeeded.
* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
Manual Installation
* Keyboard Layout and Networking and Partitioning:: Initial setup.
* Proceeding with the Installation:: Installing.
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 time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
* Official Substitute Server:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Getting Substitutes from Other Servers:: Substitute diversity.
* 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?
Channels
* Specifying Additional Channels:: Extending the package collection.
* Using a Custom Guix Channel:: Using a customized Guix.
* Replicating Guix:: Running the @emph{exact same} Guix.
* Channel Authentication:: How Guix verifies what it fetches.
* Channels with Substitutes:: Using channels with available substitutes.
* Creating a Channel:: How to write your custom channel.
* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
* Declaring Channel Dependencies:: How to depend on other channels.
* Specifying Channel Authorizations:: Defining channel authors authorizations.
* Primary URL:: Distinguishing mirror to original.
* Writing Channel News:: Communicating information to channel's users.
Development
* Invoking guix environment:: Setting up development environments.
* Invoking guix pack:: Creating software bundles.
* The GCC toolchain:: Working with languages supported by GCC.
* Invoking guix git authenticate:: Authenticating Git repositories.
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Defining Package Variants:: Customizing packages.
* Build Systems:: Specifying how packages are built.
* Build Phases:: Phases of the build process of a package.
* Build Utilities:: Helpers for your package definitions and more.
* 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.
* Invoking guix repl:: Programming Guix in Guile.
* package Reference:: The package data type.
* origin Reference:: The origin data type.
Utilities
* Invoking guix build:: Building packages from the command line.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix 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 guix processes:: Listing client processes.
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.
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.
* Keyboard Layout:: How the system interprets key strokes.
* 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.
* Invoking guix deploy:: Deploying a system configuration to a remote host.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
Services
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
* Networking Services:: Network setup, SSH daemon, etc.
* Unattended Upgrades:: Automated system upgrades.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Monitoring Services:: Monitoring services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* Network File System:: NFS related services.
* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Linux Services:: Services tied to the Linux kernel.
* Hurd Services:: Services specific for a Hurd System.
* 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.
Installing Debugging Files
* Separate Debug Info:: Installing 'debug' outputs.
* Rebuilding Debug Info:: Building missing debug info.
Bootstrapping
* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
@end menu
@c *********************************************************************
@node Introduction
@chapter Introduction
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
using the international phonetic alphabet (IPA).} is a package
management tool for and distribution of the GNU system.
Guix makes it easy for unprivileged
users to install, upgrade, or remove software 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 Guix System
@cindex GuixSD, now Guix System
@cindex Guix System Distribution, now Guix System
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 a standalone operating system distribution,
@dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
System Distribution'' or ``GuixSD''. We now consider it makes more sense to
group everything under the ``Guix'' banner since, after all, Guix System is
readily available through the @command{guix system} command, even if you're
using a different distro underneath!}. @xref{GNU Distribution}.
@menu
* Managing Software the Guix Way:: What's special.
* GNU Distribution:: The packages and tools.
@end menu
@node Managing Software the Guix Way
@section Managing Software the Guix Way
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Package Management}), tools to help with software development
(@pxref{Development}), command-line utilities for more advanced usage
(@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
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}).
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,
Nikita Karetnikov
committed
such as build scripts, a compiler, and libraries, and
returns an installed package. As a pure function, its result depends
solely on its inputs---for instance, it cannot refer to software or
scripts that were not explicitly passed as inputs. A build function
Nikita Karetnikov
committed
always produces the same result when passed a given set of inputs. It
cannot alter the 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
Nikita Karetnikov
committed
explicit inputs are visible.
The result of package build functions is @dfn{cached} in the file
system, in a special directory called @dfn{the store} (@pxref{The
Store}). Each package is installed in a directory of its own in the
store---by default under @file{/gnu/store}. The directory name contains
a hash of all the inputs used to build that package; thus, changing an
input yields a different directory name.
This approach is the foundation for the salient features of Guix: support
for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
@node GNU Distribution
@section GNU Distribution
@cindex Guix System
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}). When we need to
distinguish between the two, we refer to the standalone distribution as
Guix@tie{}System.
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
@url{https://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
@example
guix package --list-available
@end example
Our goal is to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
Packages are currently available on the following platforms:
@table @code
@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel.
@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.
@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
@item i586-gnu
@uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
(IA32).
This configuration is experimental and under development. The easiest
way for you to give it a try is by setting up an instance of
@code{hurd-vm-service-type} on your GNU/Linux machine
(@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
@xref{Contributing}, on how to help!
@item mips64el-linux (deprecated)
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
supported; in particular, there is no ongoing work to ensure that this
architecture still works. Should someone decide they wish to revive this
architecture then the code is still available.
@item powerpc64le-linux
little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
includes POWER9 systems such as the
@uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
RYF Talos II mainboard}. This platform is available as a "technology
preview": although it is supported, substitutes are not yet available
from the build farm (@pxref{Substitutes}), and some packages may fail to
build (@pxref{Tracking Bugs and Patches}). That said, the Guix
community is actively working on improving this support, and now is a
great time to try it and get involved!
@end table
With Guix@tie{}System, 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}). Guix System uses the Linux-libre kernel, the Shepherd
initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
Manual}), the well-known GNU utilities and tool chain, as well as the
graphical environment or system services of your choice.
Guix System is available on all the above platforms except
@code{mips64el-linux} and @code{powerpc64le-linux}.
@noindent
For information on porting to other architectures or kernels,
@pxref{Porting}.
Building this distribution is a cooperative effort, and you are invited
to join! @xref{Contributing}, for information about how you can help.
@c *********************************************************************
@node Installation
@chapter Installation
@quotation Note
We recommend the use of this
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
shell installer script} to install Guix on top of a running GNU/Linux system,
thereafter called a @dfn{foreign distro}.@footnote{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}.} The script automates the
download, installation, and initial configuration of Guix. It should be run
as the root user.
@end quotation
@cindex foreign distro
When installed on a 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}).
If you prefer to perform the installation steps manually or want to tweak
them, you may find the following subsections useful. They describe the
software requirements of Guix, as well as how to install it manually and get
ready to use it.
* 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.
* Upgrading Guix:: Upgrading Guix and its build daemon.
@node Binary Installation
@section Binary Installation
This section describes how to install Guix on an arbitrary system from a
self-contained tarball providing binaries for Guix and for all its
dependencies. This is often quicker than installing from source, which
is described in the next sections. The only requirement is to have
GNU@tie{}tar and Xz.
@c Note duplicated from the ``Installation'' node.
@quotation Note
We recommend the use of this
@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
shell installer script}. The script automates the download, installation, and
initial configuration steps described below. It should be run as the root
user. As root, you can thus run this:
@example
cd /tmp
wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
chmod +x guix-install.sh
./guix-install.sh
@end example
When you're done, @pxref{Application Setup} for extra configuration you
might need, and @ref{Getting Started} for your first steps!
@end quotation
Installing goes along these lines:
@enumerate
@item
Download the binary tarball from
@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
@code{i686} (32-bits) machine already running the kernel Linux, and so on
(@pxref{GNU Distribution}).
@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 @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
If that command fails because you do not have the required public key,
then run this command to import it:
$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-qO - | gpg --import -
@end example
@noindent
and rerun the @code{gpg --verify} command.
Take note that a warning like ``This key is not certified with a trusted
signature!'' is normal.
@c end authentication part
Now, you need to become the @code{root} user. Depending on your distribution,
you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
# tar --warning=no-timestamp -xf \
/path/to/guix-binary-@value{VERSION}.x86_64-linux.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
Do @emph{not} unpack the tarball on a working Guix system since that
would overwrite its own essential files.
The @option{--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
They stem from the fact that all the
files in the archive have their modification time set to 1 (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.
Make the profile available under @file{~root/.config/guix/current}, which is
where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
# mkdir -p ~root/.config/guix
# ln -sf /var/guix/profiles/per-user/root/current-guix \
~root/.config/guix/current
Source @file{etc/profile} to augment @env{PATH} and other relevant
environment variables:
@example
# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
source $GUIX_PROFILE/etc/profile
@end example
@item
Create the group and user accounts for build users as explained below
(@pxref{Build Environment Setup}).
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 https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
# systemctl enable --now gnu-store.mount guix-daemon
@end example
If your host distro uses the Upstart init system:
# initctl reload-configuration
# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
/etc/init/
# start guix-daemon
@end example
Otherwise, you can still start the daemon manually with:
@example
# ~root/.config/guix/current/bin/guix-daemon \
--build-users-group=guixbuild
@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/current-guix/bin/guix
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/current-guix/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
@cindex substitutes, authorization thereof
To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its mirrors
(@pxref{Substitutes}), authorize them:
# guix archive --authorize < \
~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub
@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:
# guix install hello
@end example
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
guix pack -s @var{system} --localstatedir \
--profile-name=current-guix 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.
@cindex official website
GNU Guix is available for download from its website at
@url{https://www.gnu.org/software/guix/}.
GNU Guix depends on the following packages:
@itemize
@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x or
2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
version 0.1.0 or later;
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@c FIXME: We need the #:fetch-options parameter of 'submodule-update',
@c which appeared in 0.5.0. Change below after string freeze.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.0
or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
4.3.0 or later;
@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
@itemize
@c Note: We need at least 0.13.0 for #:nodelay.
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},
@item
@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
compression and decompression in @command{guix publish} and for
substitutes (@pxref{Invoking guix publish}).
@item
@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
the @code{crate} importer (@pxref{Invoking guix import}).
@item
@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
the @code{go} importer (@pxref{Invoking guix import}) and for some of
the ``updaters'' (@pxref{Invoking guix refresh}).
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
Unless @option{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:
@itemize
@item @url{https://gnupg.org/, GNU libgcrypt};
@item @url{https://sqlite.org, SQLite 3};
@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
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 @option{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
GNU Coding Standards}). Usually, this @var{localstatedir} option is
set to the value @file{/var}. The @command{configure} script protects
against unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).
@node Running the Test Suite
@section Running the Test Suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite. It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software. To run the test
suite, type:
@example
make check
@end example
Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up. The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
that is created for test purposes will already have various things in
cache.
It is also possible to run a subset of the tests by defining the
@code{TESTS} makefile variable as in this example:
@example
make check TESTS="tests/store.scm tests/cpio.scm"
@end example
By default, tests results are displayed at a file level. In order to
see the details of every individual test cases, it is possible to define
the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
@example
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
@end example
The underlying SRFI 64 custom Automake test driver used for the 'check'
test suite (located at @file{build-aux/test-driver.scm}) also allows
selecting which test cases to run at a finer level, via its
@option{--select} and @option{--exclude} options. Here's an example, to
run all the test cases from the @file{tests/packages.scm} test file
whose names start with ``transaction-upgrade-entry'':
@example
export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
make check TESTS="tests/packages.scm"
@end example
Those wishing to inspect the results of failed tests directly from the
command line can add the @option{--errors-only=yes} option to the
@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
Automake makefile variable, as in:
@example
make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
@end example
The @option{--show-duration=yes} option can be used to print the
duration of the individual test cases, when used in combination with
@option{--brief=no}:
@example
make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
@end example
@xref{Parallel Test Harness,,,automake,GNU Automake} for more
information about the Automake Parallel Test Harness.
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
Guix 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