|
- \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 BCA689B636553801C3C62150197A5888235FACAC
-
- @copying
- Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017 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 Ricardo Wurmus@*
- Copyright @copyright{} 2016 Ben Woodcroft@*
- Copyright @copyright{} 2016 Chris Marusich@*
- Copyright @copyright{} 2016 Efraim Flashner@*
- Copyright @copyright{} 2016 John Darrington@*
- Copyright @copyright{} 2016 ng0@*
- Copyright @copyright{} 2016 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
-
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
- copy of the license is included in the section entitled ``GNU Free
- Documentation License''.
- @end copying
-
- @dircategory System administration
- @direntry
- * Guix: (guix). Manage installed software and system configuration.
- * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
- * guix build: (guix)Invoking guix build. Building packages.
- * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
- * guix pull: (guix)Invoking guix pull. Update the list of available packages.
- * guix system: (guix)Invoking guix system. Manage the operating system configuration.
- @end direntry
-
- @dircategory Software development
- @direntry
- * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
- @end direntry
-
- @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.
-
- 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.
-
- 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 @command{guix build}
-
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
-
- GNU Distribution
-
- * System Installation:: Installing the whole operating system.
- * System Configuration:: Configuring the operating system.
- * Installing Debugging Files:: Feeding the debugger.
- * Security Updates:: Deploying security fixes quickly.
- * Package Modules:: Packages from the programmer's viewpoint.
- * Packaging Guidelines:: Growing the distribution.
- * Bootstrapping:: GNU/Linux built from scratch.
- * Porting:: Targeting another platform or kernel.
-
- System Installation
-
- * Limitations:: What you can expect.
- * Hardware Considerations:: Supported hardware.
- * USB Stick Installation:: Preparing the installation medium.
- * Preparing for Installation:: Networking, partitioning, etc.
- * Proceeding with the Installation:: The real thing.
- * Installing GuixSD in a VM:: GuixSD playground.
- * Building the Installation Image:: How this comes to be.
-
- System Configuration
-
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * User Accounts:: Specifying user accounts.
- * Locales:: Language and cultural convention settings.
- * Services:: Specifying system services.
- * Setuid Programs:: Programs running with root privileges.
- * X.509 Certificates:: Authenticating HTTPS servers.
- * Name Service Switch:: Configuring libc's name service switch.
- * Initial RAM Disk:: Linux-Libre bootstrapping.
- * GRUB Configuration:: Configuring the boot loader.
- * Invoking guix system:: Instantiating a system configuration.
- * Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
- * Defining Services:: Adding new service definitions.
-
- Services
-
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * 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.
- * Mail Services:: IMAP, POP3, SMTP, and all that.
- * Messaging Services:: Messaging services.
- * Kerberos Services:: Kerberos services.
- * Web Services:: Web servers.
- * VPN Services:: VPN daemons.
- * Network File System:: NFS related services.
- * Continuous Integration:: The Cuirass service.
- * Miscellaneous Services:: Other services.
-
- Defining Services
-
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
-
- Packaging Guidelines
-
- * Software Freedom:: What may go into the distribution.
- * Package Naming:: What's in a name?
- * Version Numbers:: When the name is not enough.
- * Synopses and Descriptions:: Helping users find the right package.
- * Python Modules:: Taming the snake.
- * Perl Modules:: Little pearls.
- * Java Packages:: Coffee break.
- * Fonts:: Fond of fonts.
-
- Contributing
-
- * Building from Git:: The latest and greatest.
- * Running Guix Before It Is Installed:: Hacker tricks.
- * The Perfect Setup:: The right tools.
- * Coding Style:: Hygiene of the contributor.
- * Submitting Patches:: Share your work.
-
- Coding Style
-
- * Programming Paradigm:: How to compose your elements.
- * Modules:: Where to store your code?
- * Data Types and Pattern Matching:: Implementing data structures.
- * Formatting Code:: Writing conventions.
-
- @end detailmenu
- @end menu
-
- @c *********************************************************************
- @node Introduction
- @chapter Introduction
-
- @cindex purpose
- GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
- using the international phonetic alphabet (IPA).} is a package
- management tool for the GNU system. Guix makes it easy for unprivileged
- users to install, upgrade, or remove packages, to roll back to a
- previous package set, to build packages from source, and generally
- assists with the creation and maintenance of software environments.
-
- @cindex user interfaces
- Guix provides a command-line package management interface
- (@pxref{Invoking guix package}), a set of command-line utilities
- (@pxref{Utilities}), 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.
-
- 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
-
- @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
- @end enumerate
-
- This completes root-level install of Guix. Each user will need to
- perform additional steps to make their Guix environment ready for use,
- @pxref{Application Setup}.
-
- You can confirm that Guix is working by installing a sample package into
- the root profile:
-
- @example
- # guix package -i hello
- @end example
-
- The @code{guix} package must remain available in @code{root}'s profile,
- or it would become subject to garbage collection---in which case you
- would find yourself badly handicapped by the lack of the @command{guix}
- command. In other words, do not remove @code{guix} by running
- @code{guix package -r guix}.
-
- The binary installation tarball can be (re)produced and verified simply
- by running the following command in the Guix source tree:
-
- @example
- make guix-binary.@var{system}.tar.xz
- @end example
-
- @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.7 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 @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://zlib.net, zlib} is available, @command{guix publish}
- can compress build byproducts (@pxref{Invoking guix publish}).
- @end itemize
-
- Unless @code{--disable-daemon} was passed to @command{configure}, the
- following packages are also needed:
-
- @itemize
- @item @url{http://sqlite.org, SQLite 3};
- @item @url{http://www.bzip.org, libbz2};
- @item @url{http://gcc.gnu.org, GCC's g++}, with support for the
- C++11 standard.
- @end itemize
-
- @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.
- @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{~/.ssh/id_rsa})
- The SSH private key file to use when connecting to the machine, in
- OpenSSH format.
-
- @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
-
- @node Invoking guix-daemon
- @section Invoking @command{guix-daemon}
-
- The @command{guix-daemon} program implements all the functionality to
- access the store. This includes launching build processes, running the
- garbage collector, querying the availability of a build result, etc. It
- is normally run as @code{root} like this:
-
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
-
- @noindent
- For details on how to set it up, @pxref{Setting Up the Daemon}.
-
- @cindex chroot
- @cindex container, build environment
- @cindex build environment
- @cindex reproducible builds
- By default, @command{guix-daemon} launches build processes under
- different UIDs, taken from the build group specified with
- @code{--build-users-group}. In addition, each build process is run in a
- chroot environment that only contains the subset of the store that the
- build process depends on, as specified by its derivation
- (@pxref{Programming Interface, derivation}), plus a set of specific
- system directories. By default, the latter contains @file{/dev} and
- @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
- @dfn{container}: in addition to having its own file system tree, it has
- a separate mount name space, its own PID name space, network name space,
- etc. This helps achieve reproducible builds (@pxref{Features}).
-
- When the daemon performs a build on behalf of the user, it creates a
- build directory under @file{/tmp} or under the directory specified by
- its @code{TMPDIR} environment variable; this directory is shared with
- the container for the duration of the build. Be aware that using a
- directory other than @file{/tmp} can affect build results---for example,
- with a longer directory name, a build process that uses Unix-domain
- sockets might hit the name length limitation for @code{sun_path}, which
- it would otherwise not hit.
-
- The build directory is automatically deleted upon completion, unless the
- build failed and the client specified @option{--keep-failed}
- (@pxref{Invoking guix build, @option{--keep-failed}}).
-
- The following command-line options are supported:
-
- @table @code
- @item --build-users-group=@var{group}
- Take users from @var{group} to run build processes (@pxref{Setting Up
- the Daemon, build users}).
-
- @item --no-substitutes
- @cindex substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
-
- By default substitutes are used, unless the client---such as the
- @command{guix package} command---is explicitly invoked with
- @code{--no-substitutes}.
-
- When the daemon runs with @code{--no-substitutes}, clients can still
- explicitly enable substitution @i{via} the @code{set-build-options}
- remote procedure call (@pxref{The Store}).
-
- @item --substitute-urls=@var{urls}
- @anchor{daemon-substitute-urls}
- Consider @var{urls} the default whitespace-separated list of substitute
- source URLs. When this option is omitted,
- @indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
- (@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).
-
- This means that substitutes may be downloaded from @var{urls}, as long
- as they are signed by a trusted signature (@pxref{Substitutes}).
-
- @cindex build hook
- @item --no-build-hook
- Do not use the @dfn{build hook}.
-
- The build hook is a helper program that the daemon can start and to
- which it submits build requests. This mechanism is used to offload
- builds to other machines (@pxref{Daemon Offload Setup}).
-
- @item --cache-failures
- Cache build failures. By default, only successful builds are cached.
-
- When this option is used, @command{guix gc --list-failures} can be used
- to query the set of store items marked as failed; @command{guix gc
- --clear-failures} removes store items from the set of cached failures.
- @xref{Invoking guix gc}.
-
- @item --cores=@var{n}
- @itemx -c @var{n}
- Use @var{n} CPU cores to build each derivation; @code{0} means as many
- as available.
-
- The default value is @code{0}, but it may be overridden by clients, such
- as the @code{--cores} option of @command{guix build} (@pxref{Invoking
- guix build}).
-
- The effect is to define the @code{NIX_BUILD_CORES} environment variable
- in the build process, which can then use it to exploit internal
- parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
-
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. The default value is
- @code{1}. Setting it to @code{0} means that no builds will be performed
- locally; instead, the daemon will offload builds (@pxref{Daemon Offload
- Setup}), or simply fail.
-
- @item --rounds=@var{N}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical. Note that this
- setting can be overridden by clients such as @command{guix build}
- (@pxref{Invoking guix build}).
-
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
-
- @item --debug
- Produce debugging output.
-
- This is useful to debug daemon start-up issues, but then it may be
- overridden by clients, for example the @code{--verbosity} option of
- @command{guix build} (@pxref{Invoking guix build}).
-
- @item --chroot-directory=@var{dir}
- Add @var{dir} to the build chroot.
-
- Doing this may change the result of build processes---for instance if
- they use optional dependencies found in @var{dir} when it is available,
- and not otherwise. For that reason, it is not recommended to do so.
- Instead, make sure that each derivation declares all the inputs that it
- needs.
-
- @item --disable-chroot
- Disable chroot builds.
-
- Using this option is not recommended since, again, it would allow build
- processes to gain access to undeclared dependencies. It is necessary,
- though, when @command{guix-daemon} is running under an unprivileged user
- account.
-
- @item --disable-log-compression
- Disable compression of the build logs.
-
- Unless @code{--lose-logs} is used, all the build logs are kept in the
- @var{localstatedir}. To save space, the daemon automatically compresses
- them with bzip2 by default. This option disables that.
-
- @item --disable-deduplication
- @cindex deduplication
- Disable automatic file ``deduplication'' in the store.
-
- By default, files added to the store are automatically ``deduplicated'':
- if a newly added file is identical to another one found in the store,
- the daemon makes the new file a hard link to the other file. This can
- noticeably reduce disk usage, at the expense of slightly increased
- input/output load at the end of a build process. This option disables
- this optimization.
-
- @item --gc-keep-outputs[=yes|no]
- Tell whether the garbage collector (GC) must keep outputs of live
- derivations.
-
- When set to ``yes'', the GC will keep the outputs of any live derivation
- available in the store---the @code{.drv} files. The default is ``no'',
- meaning that derivation outputs are kept only if they are GC roots.
-
- @item --gc-keep-derivations[=yes|no]
- Tell whether the garbage collector (GC) must keep derivations
- corresponding to live outputs.
-
- When set to ``yes'', as is the case by default, the GC keeps
- derivations---i.e., @code{.drv} files---as long as at least one of their
- outputs is live. This allows users to keep track of the origins of
- items in their store. Setting it to ``no'' saves a bit of disk space.
-
- Note that when both @code{--gc-keep-derivations} and
- @code{--gc-keep-outputs} are used, the effect is to keep all the build
- prerequisites (the sources, compiler, libraries, and other build-time
- tools) of live objects in the store, regardless of whether these
- prerequisites are live. This is convenient for developers since it
- saves rebuilds or downloads.
-
- @item --impersonate-linux-2.6
- On Linux-based systems, impersonate Linux 2.6. This means that the
- kernel's @code{uname} system call will report 2.6 as the release number.
-
- This might be helpful to build programs that (usually wrongfully) depend
- on the kernel version number.
-
- @item --lose-logs
- Do not keep build logs. By default they are kept under
- @code{@var{localstatedir}/guix/log}.
-
- @item --system=@var{system}
- Assume @var{system} as the current system type. By default it is the
- architecture/kernel pair found at configure time, such as
- @code{x86_64-linux}.
-
- @item --listen=@var{socket}
- Listen for connections on @var{socket}, the file name of a Unix-domain
- socket. The default socket is
- @file{@var{localstatedir}/daemon-socket/socket}. This option is only
- useful in exceptional circumstances, such as if you need to run several
- daemons on the same machine.
- @end table
-
-
- @node Application Setup
- @section Application Setup
-
- @cindex foreign distro
- When using Guix on top of GNU/Linux distribution other than GuixSD---a
- so-called @dfn{foreign distro}---a few additional steps are needed to
- get everything in place. Here are some of them.
-
- @subsection Locales
-
- @anchor{locales-and-locpath}
- @cindex locales, when not on GuixSD
- @vindex LOCPATH
- @vindex GUIX_LOCPATH
- Packages installed @i{via} Guix will not use the locale data of the
- host system. Instead, you must first install one of the locale packages
- available with Guix and then define the @code{GUIX_LOCPATH} environment
- variable:
-
- @example
- $ guix package -i glibc-locales
- $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
- @end example
-
- Note that the @code{glibc-locales} package contains data for all the
- locales supported by the GNU@tie{}libc and weighs in at around
- 110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
- limited to a few UTF-8 locales.
-
- The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
- (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
- Manual}). There are two important differences though:
-
- @enumerate
- @item
- @code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
- provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
- to make sure the programs of the foreign distro will not end up loading
- incompatible locale data.
-
- @item
- libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
- @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
- should your Guix profile contain a mixture of programs linked against
- different libc version, each libc version will only try to load locale
- data in the right format.
- @end enumerate
-
- This is important because the locale data format used by different libc
- versions may be incompatible.
-
- @subsection 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.
-
- @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 be not
- reliable (because of name conflicts). So we think using a separate
- directory for each package is a good idea. It is very similar to how
- the Emacs package system organizes the file structure (@pxref{Package
- Files,,, emacs, The GNU Emacs Manual}).
-
- By default, Emacs (installed with Guix) ``knows'' where these packages
- are placed, so you do not need to perform any configuration. If, for
- some reason, you want to avoid auto-loading Emacs packages installed
- with Guix, you can do so by running Emacs with @code{--no-site-file}
- option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
-
- @c TODO What else?
-
- @c *********************************************************************
- @node Package Management
- @chapter Package Management
-
- @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 Emacs Interface, 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}/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 specification->package+output
- 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{specification->package-output} look up the corresponding package
- objects, like this:
-
- @example
- (packages->manifest
- (map (compose list specification->package+output)
- '("emacs" "guile@@2.0" "guile@@2.0: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}. Print all the metadata of matching packages in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
- GNU recutils manual}).
-
- This allows specific fields to be extracted using the @command{recsel}
- command, for instance:
-
- @example
- $ guix package -s malloc | recsel -p name,version
- name: glibc
- version: 2.17
-
- name: libgc
- version: 7.2alpha6
- @end example
-
- Similarly, to show the name of all the packages available under the
- terms of the GNU@tie{}LGPL version 3:
-
- @example
- $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
- name: elfutils
-
- name: gmp
- @dots{}
- @end example
-
- It is also possible to refine search results using several @code{-s}
- flags. For example, the following command returns a list of board
- games:
-
- @example
- $ guix package -s '\<board\>' -s game | recsel -p name
- name: gnubg
- @dots{}
- @end example
-
- If we were to omit @code{-s game}, we would also get software packages
- that deal with printed circuit boards; removing the angle brackets
- around @code{board} would further add packages that have to do with
- keyboards.
-
- And now for a more elaborate example. The following command searches
- for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
- libraries, and prints the name and synopsis of the matching packages:
-
- @example
- $ guix package -s crypto -s library | \
- recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
- @end example
-
- @noindent
- @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
- information on @dfn{selection expressions} for @code{recsel -e}.
-
- @item --show=@var{package}
- Show details about @var{package}, taken from the list of available packages, in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
- recutils manual}).
-
- @example
- $ guix package --show=python | recsel -p name,version
- name: python
- version: 2.7.6
-
- name: python
- version: 3.3.5
- @end example
-
- You may also specify the full name of a package to only get details about a
- specific version of it:
- @example
- $ guix package --show=python@@3.4 | recsel -p name,version
- name: python
- version: 3.4.3
- @end example
-
-
-
- @item --list-installed[=@var{regexp}]
- @itemx -I [@var{regexp}]
- List the currently installed packages in the specified profile, with the
- most recently installed packages shown last. When @var{regexp} is
- specified, list only installed packages whose name matches @var{regexp}.
-
- For each installed package, print the following items, separated by
- tabs: the package name, its version string, the part of the package that
- is installed (for instance, @code{out} for the default output,
- @code{include} for its headers, etc.), and the path of this package in
- the store.
-
- @item --list-available[=@var{regexp}]
- @itemx -A [@var{regexp}]
- List packages currently available in the distribution for this system
- (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
- installed packages whose name matches @var{regexp}.
-
- For each package, print the following items separated by tabs: its name,
- its version string, the parts of the package (@pxref{Packages with
- Multiple Outputs}), and the source location of its definition.
-
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- @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. We call these pre-built items @dfn{substitutes}---they are
- substitutes for local build results. In many cases, downloading a
- substitute is much faster than building things locally.
-
- Substitutes can be anything resulting from a derivation build
- (@pxref{Derivations}). Of course, in the common case, they are
- pre-built package binaries, but source tarballs, for instance, which
- also result from derivation builds, can be available as substitutes.
-
- The @code{hydra.gnu.org} server is a front-end to a build farm that
- builds packages from the GNU distribution continuously for some
- architectures, and makes them available as substitutes. This is the
- default source of substitutes; it can be overridden by passing the
- @option{--substitute-urls} option either to @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
- or to client tools such as @command{guix package}
- (@pxref{client-substitute-urls,, client @option{--substitute-urls}
- option}).
-
- 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.
-
- @cindex security
- @cindex digital signatures
- @cindex substitutes, authorization thereof
- To allow Guix to download substitutes from @code{hydra.gnu.org} or a
- mirror thereof, you
- must add its public key to the access control list (ACL) of archive
- imports, using the @command{guix archive} command (@pxref{Invoking guix
- archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
- be compromised and to serve genuine substitutes.
-
- This public key is installed along with Guix, in
- @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
- the installation prefix of Guix. If you installed Guix from source,
- make sure you checked the GPG signature of
- @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
- Then, you can run something like this:
-
- @example
- # guix archive --authorize < hydra.gnu.org.pub
- @end example
-
- Once this is in place, the output of a command like @code{guix build}
- should change from something like:
-
- @example
- $ guix build emacs --dry-run
- The following derivations would be built:
- /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
- /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
- /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
- /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
- @dots{}
- @end example
-
- @noindent
- to something like:
-
- @example
- $ guix build emacs --dry-run
- The following files would be downloaded:
- /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
- /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
- /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
- /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
- @dots{}
- @end example
-
- @noindent
- This indicates that substitutes from @code{hydra.gnu.org} are usable and
- will be downloaded, when possible, for future builds.
-
- Guix ignores substitutes that are not signed, or that are not signed by
- one of the keys listed in the ACL. It also detects and raises an error
- when attempting to use a substitute that has been tampered with.
-
- @vindex http_proxy
- Substitutes are downloaded over HTTP or HTTPS.
- The @code{http_proxy} environment
- variable can be set in the environment of @command{guix-daemon} and is
- honored for downloads of substitutes. Note that the value of
- @code{http_proxy} in the environment where @command{guix build},
- @command{guix package}, and other client commands are run has
- @emph{absolutely no effect}.
-
- When using HTTPS, the server's X.509 certificate is @emph{not} validated
- (in other words, the server is not authenticated), contrary to what
- HTTPS clients such as Web browsers usually do. This is because Guix
- authenticates substitute information itself, as explained above, which
- is what we care about (whereas X.509 certificates are about
- authenticating bindings between domain names and public keys.)
-
- The substitute mechanism can be disabled globally by running
- @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
- guix-daemon}). It can also be disabled temporarily by passing the
- @code{--no-substitutes} option to @command{guix package}, @command{guix
- build}, and other command-line tools.
-
-
- @unnumberedsubsec On Trusting Binaries
-
- Today, each individual's control over their own computing is at the
- mercy of institutions, corporations, and groups with enough power and
- determination to subvert the computing infrastructure and exploit its
- weaknesses. While using @code{hydra.gnu.org} substitutes can be
- convenient, we encourage users to also build on their own, or even run
- their own build farm, such that @code{hydra.gnu.org} is less of an
- interesting target. One way to help is by publishing the software you
- build using @command{guix publish} so that others have one more choice
- of server to download substitutes from (@pxref{Invoking guix publish}).
-
- Guix has the foundations to maximize build reproducibility
- (@pxref{Features}). In most cases, independent builds of a given
- package or derivation should yield bit-identical results. Thus, through
- a diverse set of independent package builds, we can strengthen the
- integrity of our systems. The @command{guix challenge} command aims to
- help users assess substitute servers, and to assist developers in
- finding out about non-deterministic package builds (@pxref{Invoking guix
- challenge}). Similarly, the @option{--check} option of @command{guix
- build} allows users to check whether previously-installed substitutes
- are genuine by rebuilding them locally (@pxref{build-check,
- @command{guix build --check}}).
-
- In the future, we want Guix to have support to publish and retrieve
- binaries to/from other users, in a peer-to-peer fashion. If you would
- like to discuss this project, join us on @email{guix-devel@@gnu.org}.
-
-
- @node Packages with Multiple Outputs
- @section Packages with Multiple Outputs
-
- @cindex multiple-output packages
- @cindex package outputs
- @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!
-
- The garbage collector has a set of known @dfn{roots}: any file under
- @file{/gnu/store} reachable from a root is considered @dfn{live} and
- cannot be deleted; any other file is considered @dfn{dead} and may be
- deleted. The set of garbage collector roots includes default user
- profiles, and may be augmented with @command{guix build --root}, for
- example (@pxref{Invoking guix build}).
-
- Prior to running @code{guix gc --collect-garbage} to make space, it is
- often useful to remove old generations from user profiles; that way, old
- package builds referenced by those generations can be reclaimed. This
- is achieved by running @code{guix package --delete-generations}
- (@pxref{Invoking guix package}).
-
- The @command{guix gc} command has three modes of operation: it can be
- used to garbage-collect any dead files (the default), to delete specific
- files (the @code{--delete} option), to print garbage-collector
- information, or for more advanced queries. The garbage collection
- options are as follows:
-
- @table @code
- @item --collect-garbage[=@var{min}]
- @itemx -C [@var{min}]
- Collect garbage---i.e., unreachable @file{/gnu/store} files and
- sub-directories. This is the default operation when no option is
- specified.
-
- When @var{min} is given, stop once @var{min} bytes have been collected.
- @var{min} may be a number of bytes, or it may include a unit as a
- suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
- (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
-
- When @var{min} is omitted, collect all the garbage.
-
- @item --free-space=@var{free}
- @itemx -F @var{free}
- Collect garbage until @var{free} space is available under
- @file{/gnu/store}, if possible; @var{free} denotes storage space, such
- as @code{500MiB}, as described above.
-
- When @var{free} or more is already available in @file{/gnu/store}, do
- nothing and exit immediately.
-
- @item --delete
- @itemx -d
- Attempt to delete all the store files and directories specified as
- arguments. This fails if some of the files are not in the store, or if
- they are still live.
-
- @item --list-failures
- List store items corresponding to cached build failures.
-
- This prints nothing unless the daemon was started with
- @option{--cache-failures} (@pxref{Invoking guix-daemon,
- @option{--cache-failures}}).
-
- @item --clear-failures
- Remove the specified store items from the failed-build cache.
-
- Again, this option only makes sense when the daemon is started with
- @option{--cache-failures}. Otherwise, it does nothing.
-
- @item --list-dead
- Show the list of dead files and directories still present in the
- store---i.e., files and directories no longer reachable from any root.
-
- @item --list-live
- Show the list of live store files and directories.
-
- @end table
-
- In addition, the references among existing store files can be queried:
-
- @table @code
-
- @item --references
- @itemx --referrers
- @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.
-
- 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 the source tarball of Guix from @var{url}.
-
- By default, the tarball is taken from its canonical address at
- @code{gnu.org}, for the stable branch of Guix.
-
- With some Git servers, this can be used to deploy any version of Guix.
- For example, to download and deploy version 0.12.0 of Guix from the
- canonical Git repo:
-
- @example
- guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz
- @end example
-
- It can also be used to deploy arbitrary Git revisions:
-
- @example
- guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz
- @end example
-
- @item --bootstrap
- Use the bootstrap Guile to build the latest Guix. This option is only
- useful to Guix developers.
- @end table
-
-
- @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.
-
- @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.
-
- 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.
-
- Several command-line options allow you to customize your pack:
-
- @table @code
- @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 --compression=@var{tool}
- @itemx -C @var{tool}
- Compress the resulting tarball using @var{tool}---one of @code{gzip},
- @code{bzip2}, @code{xz}, or @code{lzip}.
-
- @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.
- In particular, it allows store files to be transferred from one machine
- to the store on another machine.
-
- @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)
- By default 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.
-
- Optionally, archives can be exported as a Docker image in the tar
- archive format using @code{--format=docker}.
-
- 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 -f
- @item --format=@var{FMT}
- @cindex docker, export
- @cindex export format
- Specify the export format. Acceptable arguments are @code{nar} and
- @code{docker}. The default is the nar format. When the format is
- @code{docker}, recursively export the specified store directory as a
- Docker image in tar archive format, as specified in
- @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
- version 1.2.0 of the Docker Image Specification}. Using
- @code{--format=docker} implies @code{--recursive}. The generated
- archive can be loaded by Docker using @command{docker load}.
-
- @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}). You can easily jump back to the
- package definition using the @command{guix edit} command
- (@pxref{Invoking guix edit}).
- @xref{Packaging Guidelines}, for
- more information on how to test package definitions, and
- @ref{Invoking guix lint}, for information on how to check a definition
- for style conformance.
-
- Finally, updating the package definition to a new upstream version
- can be partly automated by the @command{guix refresh} command
- (@pxref{Invoking guix refresh}).
-
- Behind the scenes, a derivation corresponding to the @code{<package>}
- object is first computed by the @code{package-derivation} procedure.
- That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
- The build actions it prescribes may then be realized by using the
- @code{build-derivations} procedure (@pxref{The Store}).
-
- @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
- Return the @code{<derivation>} object of @var{package} for @var{system}
- (@pxref{Derivations}).
-
- @var{package} must be a valid @code{<package>} object, and @var{system}
- must be a string denoting the target system type---e.g.,
- @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
- must be a connection to the daemon, which operates on the store
- (@pxref{The Store}).
- @end deffn
-
- @noindent
- @cindex cross-compilation
- Similarly, it is possible to compute a derivation that cross-builds a
- package for some other system:
-
- @deffn {Scheme Procedure} package-cross-derivation @var{store} @
- @var{package} @var{target} [@var{system}]
- Return the @code{<derivation>} object of @var{package} cross-built from
- @var{system} to @var{target}.
-
- @var{target} must be a valid GNU triplet denoting the target hardware
- and operating system, such as @code{"mips64el-linux-gnu"}
- (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
- Configure and Build System}).
- @end deffn
-
- @cindex package transformations
- @cindex input rewriting
- @cindex dependency tree rewriting
- Packages can be manipulated in arbitrary ways. An example of a useful
- transformation is @dfn{input rewriting}, whereby the dependency tree of
- a package is rewritten by replacing specific inputs by others:
-
- @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}]
- Return a procedure that, when passed a package, replaces its direct and
- indirect dependencies (but not its implicit inputs) according to
- @var{replacements}. @var{replacements} is a list of package pairs; the
- first element of each pair is the package to replace, and the second one
- is the replacement.
-
- Optionally, @var{rewrite-name} is a one-argument procedure that takes
- the name of a package and returns its new name after rewrite.
- @end deffn
-
- @noindent
- Consider this example:
-
- @example
- (define libressl-instead-of-openssl
- ;; This is a procedure to replace OPENSSL by LIBRESSL,
- ;; recursively.
- (package-input-rewriting `((,openssl . ,libressl))))
-
- (define git-with-libressl
- (libressl-instead-of-openssl git))
- @end example
-
- @noindent
- Here we first define a rewriting procedure that replaces @var{openssl}
- with @var{libressl}. Then we use it to define a @dfn{variant} of the
- @var{git} package that uses @var{libressl} instead of @var{openssl}.
- This is exactly what the @option{--with-input} command-line option does
- (@pxref{Package Transformation Options, @option{--with-input}}).
-
- @menu
- * package Reference :: The package data type.
- * origin Reference:: The origin data type.
- @end menu
-
-
- @node package Reference
- @subsection @code{package} Reference
-
- This section summarizes all the options available in @code{package}
- declarations (@pxref{Defining Packages}).
-
- @deftp {Data Type} package
- This is the data type representing a package recipe.
-
- @table @asis
- @item @code{name}
- The name of the package, as a string.
-
- @item @code{version}
- The version of the package, as a string.
-
- @item @code{source}
- An object telling how the source code for the package should be
- acquired. Most of the time, this is an @code{origin} object, which
- denotes a file fetched from the Internet (@pxref{origin Reference}). It
- can also be any other ``file-like'' object such as a @code{local-file},
- which denotes a file from the local file system (@pxref{G-Expressions,
- @code{local-file}}).
-
- @item @code{build-system}
- The build system that should be used to build the package (@pxref{Build
- Systems}).
-
- @item @code{arguments} (default: @code{'()})
- The arguments that should be passed to the build system. This is a
- list, typically containing sequential keyword-value pairs.
-
- @item @code{inputs} (default: @code{'()})
- @itemx @code{native-inputs} (default: @code{'()})
- @itemx @code{propagated-inputs} (default: @code{'()})
- @cindex inputs, of packages
- These fields list dependencies of the package. Each one is a list of
- tuples, where each tuple has a label for the input (a string) as its
- first element, a package, origin, or derivation as its second element,
- and optionally the name of the output thereof that should be used, which
- defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
- more on package outputs). For example, the list below specifies three
- inputs:
-
- @example
- `(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
- @end example
-
- @cindex cross compilation, package dependencies
- The distinction between @code{native-inputs} and @code{inputs} is
- necessary when considering cross-compilation. When cross-compiling,
- dependencies listed in @code{inputs} are built for the @emph{target}
- architecture; conversely, dependencies listed in @code{native-inputs}
- are built for the architecture of the @emph{build} machine.
-
- @code{native-inputs} is typically used to list tools needed at
- build time, but not at run time, such as Autoconf, Automake, pkg-config,
- Gettext, or Bison. @command{guix lint} can report likely mistakes in
- this area (@pxref{Invoking guix lint}).
-
- @anchor{package-propagated-inputs}
- Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
- specified packages will be automatically installed alongside the package
- they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
- package}}, for information on how @command{guix package} deals with
- propagated inputs.)
-
- For example this is necessary when a C/C++ library needs headers of
- another library to compile, or when a pkg-config file refers to another
- one @i{via} its @code{Requires} field.
-
- Another example where @code{propagated-inputs} is useful is for languages
- that lack a facility to record the run-time search path akin to the
- @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, 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 containing 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.
-
- @cindex bag (low-level package representation)
- Under the hood, build systems first compile package objects to
- @dfn{bags}. A @dfn{bag} is like a package, but with less
- ornamentation---in other words, a bag is a lower-level representation of
- a package, which includes all the inputs of that package, including some
- that were implicitly added by the build system. This intermediate
- representation is then compiled to a derivation (@pxref{Derivations}).
-
- Build systems accept an optional list of @dfn{arguments}. In package
- definitions, these are passed @i{via} the @code{arguments} field
- (@pxref{Defining Packages}). They are typically keyword arguments
- (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
- Guile Reference Manual}). The value of these arguments is usually
- evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
- by the daemon (@pxref{Derivations}).
-
- The main build system is @var{gnu-build-system}, which implements the
- standard build procedure for GNU and many other packages. It
- is provided by the @code{(guix build-system gnu)} module.
-
- @defvr {Scheme Variable} gnu-build-system
- @var{gnu-build-system} represents the GNU Build System, and variants
- thereof (@pxref{Configuration, configuration and makefile conventions,,
- standards, GNU Coding Standards}).
-
- @cindex build phases
- In a nutshell, packages using it are configured, built, and installed with
- the usual @code{./configure && make && make check && make install}
- command sequence. In practice, a few additional steps are often needed.
- All these steps are split up in separate @dfn{phases},
- notably@footnote{Please see the @code{(guix build gnu-build-system)}
- modules for more details about the build phases.}:
-
- @table @code
- @item unpack
- Unpack the source tarball, and change the current directory to the
- extracted source tree. If the source is actually a directory, copy it
- to the build tree, and enter that directory.
-
- @item patch-source-shebangs
- Patch shebangs encountered in source files so they refer to the right
- store file names. For instance, this changes @code{#!/bin/sh} to
- @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
-
- @item configure
- Run the @file{configure} script with a number of default options, such
- as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
- by the @code{#:configure-flags} argument.
-
- @item build
- Run @code{make} with the list of flags specified with
- @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
- (the default), build with @code{make -j}.
-
- @item check
- Run @code{make check}, or some other target specified with
- @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
- @code{#:parallel-tests?} argument is true (the default), run @code{make
- check -j}.
-
- @item install
- Run @code{make install} with the flags listed in @code{#:make-flags}.
-
- @item patch-shebangs
- Patch shebangs on the installed executable files.
-
- @item strip
- Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
- is false), copying them to the @code{debug} output when available
- (@pxref{Installing Debugging Files}).
- @end table
-
- @vindex %standard-phases
- The build-side module @code{(guix build gnu-build-system)} defines
- @var{%standard-phases} as the default list of build phases.
- @var{%standard-phases} is a list of symbol/procedure pairs, where the
- procedure implements the actual phase.
-
- The list of phases used for a particular package can be changed with the
- @code{#:phases} parameter. For instance, passing:
-
- @example
- #:phases (modify-phases %standard-phases (delete 'configure))
- @end example
-
- means that all the phases described above will be used, except the
- @code{configure} phase.
-
- In addition, this build system ensures that the ``standard'' environment
- for GNU packages is available. This includes tools such as GCC, libc,
- Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
- build-system gnu)} module for a complete list). We call these the
- @dfn{implicit inputs} of a package, because package definitions do not
- have to mention them.
- @end defvr
-
- Other @code{<build-system>} objects are defined to support other
- conventions and tools used by free software packages. They inherit most
- of @var{gnu-build-system}, and differ mainly in the set of inputs
- implicitly added to the build process, and in the list of phases
- executed. Some of these build systems are listed below.
-
- @defvr {Scheme Variable} ant-build-system
- This variable is exported by @code{(guix build-system ant)}. It
- implements the build procedure for Java packages that can be built with
- @url{http://ant.apache.org/, Ant build tool}.
-
- It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
- provided by the @code{icedtea} package to the set of inputs. Different
- packages can be specified with the @code{#:ant} and @code{#:jdk}
- parameters, respectively.
-
- When the original package does not provide a suitable Ant build file,
- the parameter @code{#:jar-name} can be used to generate a minimal Ant
- build file @file{build.xml} with tasks to build the specified jar
- archive.
-
- The parameter @code{#:build-target} can be used to specify the Ant task
- that should be run during the @code{build} phase. By default the
- ``jar'' task will be run.
-
- @end defvr
-
- @defvr {Scheme Variable} asdf-build-system/source
- @defvrx {Scheme Variable} asdf-build-system/sbcl
- @defvrx {Scheme Variable} asdf-build-system/ecl
-
- These variables, exported by @code{(guix build-system asdf)}, implement
- build procedures for Common Lisp packages using
- @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
- definition facility for Common Lisp programs and libraries.
-
- The @code{asdf-build-system/source} system installs the packages in
- source form, and can be loaded using any common lisp implementation, via
- ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
- systems in the format which a particular implementation understands.
- These build systems can also be used to produce executable programs, or
- lisp images which contain a set of packages pre-loaded.
-
- The build system uses naming conventions. For binary packages, the
- package itself as well as its run-time dependencies should begin their
- name with the lisp implementation, such as @code{sbcl-} for
- @code{asdf-build-system/sbcl}. Beginning the input name with this
- prefix will allow the build system to encode its location into the
- resulting library, so that the input can be found at run-time.
-
- If dependencies are used only for tests, it is convenient to use a
- different prefix in order to avoid having a run-time dependency on such
- systems. For example,
-
- @example
- (define-public sbcl-bordeaux-threads
- (package
- ...
- (native-inputs `(("tests:cl-fiveam" ,sbcl-fiveam)))
- ...))
- @end example
-
- Additionally, the corresponding source package should be labeled using
- the same convention as python packages (see @ref{Python Modules}), using
- the @code{cl-} prefix.
-
- For binary packages, each system should be defined as a Guix package.
- If one package @code{origin} contains several systems, package variants
- can be created in order to build all the systems. Source packages,
- which use @code{asdf-build-system/source}, may contain several systems.
-
- In order to create executable programs and images, the build-side
- procedures @code{build-program} and @code{build-image} can be used.
- They should be called in a build phase after the @code{create-symlinks}
- phase, so that the system which was just built can be used within the
- resulting image. @code{build-program} requires a list of Common Lisp
- expressions to be passed as the @code{#:entry-program} argument.
-
- If the system is not defined within its own @code{.asd} file of the same
- name, then the @code{#:asd-file} parameter should be used to specify
- which file the system is defined in.
-
- @end defvr
-
- @defvr {Scheme Variable} cargo-build-system
- @cindex Rust programming language
- @cindex Cargo (Rust build system)
- This variable is exported by @code{(guix build-system cargo)}. It
- supports builds of packages using Cargo, the build tool of the
- @uref{https://www.rust-lang.org, Rust programming language}.
-
- In its @code{configure} phase, this build system replaces dependencies
- specified in the @file{Carto.toml} file with inputs to the Guix package.
- The @code{install} phase installs the binaries, and it also installs the
- source code and @file{Cargo.toml} file.
- @end defvr
-
- @defvr {Scheme Variable} cmake-build-system
- This variable is exported by @code{(guix build-system cmake)}. It
- implements the build procedure for packages using the
- @url{http://www.cmake.org, CMake build tool}.
-
- It automatically adds the @code{cmake} package to the set of inputs.
- Which packa
|