[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
03/03: doc: Add a "Development" chapter.
|
From: |
guix-commits |
|
Subject: |
03/03: doc: Add a "Development" chapter. |
|
Date: |
Wed, 13 Feb 2019 10:20:10 -0500 (EST) |
civodul pushed a commit to branch master
in repository guix.
commit d423d6892a187c7b365e89964de77879748e4e40
Author: Ludovic Courtès <address@hidden>
Date: Wed Feb 13 16:14:40 2019 +0100
doc: Add a "Development" chapter.
* doc/guix.texi (Managing Software the Guix Way): Add reference to the
"Development" section.
(Invoking guix environment, Invoking guix pack): Move to...
(Development): ... here. New node.
---
doc/guix.texi | 7962 +++++++++++++++++++++++++++++----------------------------
1 file changed, 3998 insertions(+), 3964 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index 6980672..1ac077d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -119,6 +119,7 @@ Project}.
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
* Package Management:: Package installation, upgrade, etc.
+* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* System Configuration:: Configuring the operating system.
@@ -137,6 +138,11 @@ Project}.
@detailmenu
--- The Detailed Node Listing ---
+Introduction
+
+* Managing Software the Guix Way:: What's special.
+* GNU Distribution:: The packages and tools.
+
Installation
* Binary Installation:: Getting Guix running in no time!
@@ -159,7 +165,7 @@ System Installation
* USB Stick and DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
-* Installing Guix in a VM:: Guix System playground.
+* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
Package Management
@@ -173,7 +179,6 @@ Package Management
* Channels:: Customizing the package collection.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
-* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
Substitutes
@@ -185,6 +190,11 @@ Substitutes
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
+Development
+
+* Invoking guix environment:: Setting up development environments.
+* Invoking guix pack:: Creating software bundles.
+
Programming Interface
* Package Modules:: Packages from the programmer's viewpoint.
@@ -212,7 +222,6 @@ Utilities
* 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.
@@ -242,7 +251,7 @@ System Configuration
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
-* Running Guix in a VM:: How to run Guix System in a virtual machine.
+* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
Services
@@ -309,12 +318,18 @@ group everything under the ``Guix'' banner since, after
all, Guix System is
readily available through the @command{guix system} command, even if you're
using a different distro underneath!}. @xref{GNU Distribution}.
address@hidden
+* Managing Software the Guix Way:: What's special.
+* GNU Distribution:: The packages and tools.
address@hidden menu
+
@node Managing Software the Guix Way
@section Managing Software the Guix Way
@cindex user interfaces
Guix provides a command-line package management interface
-(@pxref{Invoking guix package}), a set of command-line utilities
+(@pxref{Package Management}), tools to help with software development
+(@pxref{Development}), command-line utilities for more advanced usage,
(@pxref{Utilities}), as well as Scheme programming interfaces
(@pxref{Programming Interface}).
@cindex build daemon
@@ -1762,7 +1777,7 @@ available.
* USB Stick and DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
-* Installing Guix in a VM:: Guix System playground.
+* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
@end menu
@@ -2431,7 +2446,6 @@ guix package -i emacs-guix
* Channels:: Customizing the package collection.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
-* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
@end menu
@@ -4040,233 +4054,6 @@ produce a list of channel specifications in Recutils
format.
Display information about @var{profile}.
@end table
address@hidden Invoking guix pack
address@hidden 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.
-
address@hidden Note
-If you are looking for ways to exchange binaries among machines that
-already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
-publish}, and @ref{Invoking guix archive}.
address@hidden quotation
-
address@hidden pack
address@hidden bundle
address@hidden application bundle
address@hidden software bundle
-The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
address@hidden bundle}: it creates a tarball or some other archive
-containing the binaries of the software you're interested in, and all
-its dependencies. The resulting archive can be used on any machine that
-does not have Guix, and people can run the exact same binaries as those
-you have with Guix. The pack itself is created in a bit-reproducible
-fashion, so anyone can verify that it really contains the build results
-that you pretend to be shipping.
-
-For example, to create a bundle containing Guile, Emacs, Geiser, and all
-their dependencies, you can run:
-
address@hidden
-$ guix pack guile emacs geiser
address@hidden
-/gnu/store/@dots{}-pack.tar.gz
address@hidden example
-
-The result here is a tarball containing a @file{/gnu/store} directory
-with all the relevant packages. The resulting tarball contains a
address@hidden 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
address@hidden/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
-find inconvenient. To work around it, you can create, say, a
address@hidden/opt/gnu/bin} symlink to the profile:
-
address@hidden
-guix pack -S /opt/gnu/bin=bin guile emacs geiser
address@hidden example
-
address@hidden
-That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
-
address@hidden relocatable binaries, with @command{guix pack}
-What if the recipient of your pack does not have root privileges on
-their machine, and thus cannot unpack it in the root file system? In
-that case, you will want to use the @code{--relocatable} option (see
-below). This option produces @dfn{relocatable binaries}, meaning they
-they can be placed anywhere in the file system hierarchy: in the example
-above, users can unpack your tarball in their home directory and
-directly run @file{./opt/gnu/bin/guile}.
-
address@hidden Docker, build an image with guix pack
-Alternatively, you can produce a pack in the Docker image format using
-the following command:
-
address@hidden
-guix pack -f docker guile emacs geiser
address@hidden example
-
address@hidden
-The result is a tarball that can be passed to the @command{docker load}
-command. See the
address@hidden://docs.docker.com/engine/reference/commandline/load/, Docker
-documentation} for more information.
-
address@hidden Singularity, build an image with guix pack
address@hidden SquashFS, build an image with guix pack
-Yet another option is to produce a SquashFS image with the following
-command:
-
address@hidden
-guix pack -f squashfs guile emacs geiser
address@hidden example
-
address@hidden
-The result is a SquashFS file system image that can either be mounted or
-directly be used as a file system container image with the
address@hidden://singularity.lbl.gov, Singularity container execution
-environment}, using commands like @command{singularity shell} or
address@hidden exec}.
-
-Several command-line options allow you to customize your pack:
-
address@hidden @code
address@hidden address@hidden
address@hidden -f @var{format}
-Produce a pack in the given @var{format}.
-
-The available formats are:
-
address@hidden @code
address@hidden tarball
-This is the default format. It produces a tarball containing all the
-specified binaries and symlinks.
-
address@hidden docker
-This produces a tarball that follows the
address@hidden://github.com/docker/docker/blob/master/image/spec/v1.2.md,
-Docker Image Specification}.
-
address@hidden squashfs
-This produces a SquashFS image containing all the specified binaries and
-symlinks, as well as empty mount points for virtual file systems like
-procfs.
address@hidden table
-
address@hidden --relocatable
address@hidden -R
-Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
-anywhere in the file system hierarchy and run from there. For example,
-if you create a pack containing Bash with:
-
address@hidden
-guix pack -R -S /mybin=bin bash
address@hidden example
-
address@hidden
-...@: you can copy that pack to a machine that lacks Guix, and from your
-home directory as a normal user, run:
-
address@hidden
-tar xf pack.tar.gz
-./mybin/sh
address@hidden example
-
address@hidden
-In that shell, if you type @code{ls /gnu/store}, you'll notice that
address@hidden/gnu/store} shows up and contains all the dependencies of
address@hidden, even though the machine actually lacks @file{/gnu/store}
-altogether! That is probably the simplest way to deploy Guix-built
-software on a non-Guix machine.
-
-There's a gotcha though: this technique relies on the @dfn{user
-namespace} feature of the kernel Linux, which allows unprivileged users
-to mount or change root. Old versions of Linux did not support it, and
-some GNU/Linux distributions turn it off; on these systems, programs
-from the pack @emph{will fail to run}, unless they are unpacked in the
-root file system.
-
address@hidden address@hidden
address@hidden -e @var{expr}
-Consider the package @var{expr} evaluates to.
-
-This has the same purpose as the same-named option in @command{guix
-build} (@pxref{Additional Build Options, @code{--expression} in
address@hidden build}}).
-
address@hidden address@hidden
address@hidden -m @var{file}
-Use the packages contained in the manifest object returned by the Scheme
-code in @var{file}.
-
-This has a similar purpose as the same-named option in @command{guix
-package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
-same manifest files. It allows you to define a collection of packages
-once and use it both for creating profiles and for creating archives
-for use on machines that do not have Guix installed. Note that you can
-specify @emph{either} a manifest file @emph{or} a list of packages,
-but not both.
-
address@hidden address@hidden
address@hidden -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
-
address@hidden address@hidden
address@hidden cross-compilation
-Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
-configuration triplets,, autoconf, Autoconf}).
-
address@hidden address@hidden
address@hidden -C @var{tool}
-Compress the resulting tarball using @var{tool}---one of @code{gzip},
address@hidden, @code{xz}, @code{lzip}, or @code{none} for no compression.
-
address@hidden address@hidden
address@hidden -S @var{spec}
-Add the symlinks specified by @var{spec} to the pack. This option can
-appear several times.
-
address@hidden has the form @address@hidden@var{target}}, where
address@hidden 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.
-
address@hidden --localstatedir
address@hidden address@hidden
-Include the ``local state directory'', @file{/var/guix}, in the resulting
-pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
-profile---by default @var{name} is @code{guix-profile}, which corresponds to
address@hidden/.guix-profile}.
-
address@hidden/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}).
-
address@hidden --bootstrap
-Use the bootstrap binaries to build the pack. This option is only
-useful to Guix developers.
address@hidden 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}
@@ -4431,4785 +4218,5032 @@ archive contents coming from possibly untrusted
substitute servers.
@end table
+
@c *********************************************************************
address@hidden Programming Interface
address@hidden Programming Interface
address@hidden Development
address@hidden Development
-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.
address@hidden software development
+If you are a software developer, Guix provides tools that you should find
+helpful---independently of the language you're developing in. This is what
+this chapter is about.
-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
address@hidden/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.
-
address@hidden 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.
+The @command{guix environment} command provides a convenient way to set up
address@hidden environments} containing all the dependencies and tools
+necessary to work on the software package of your choice. The @command{guix
+pack} command allows you to create @dfn{application bundles} that can be
+easily distributed to users who do not run Guix.
@menu
-* Package Modules:: Packages from the programmer's viewpoint.
-* 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.
-* Invoking guix repl:: Fiddling with Guix interactively.
+* Invoking guix environment:: Setting up development environments.
+* Invoking guix pack:: Creating software bundles.
@end menu
address@hidden Package Modules
address@hidden Package Modules
address@hidden Invoking guix environment
address@hidden Invoking @command{guix environment}
-From a programming viewpoint, the package definitions of the
-GNU distribution are provided by Guile modules in the @code{(gnu packages
address@hidden)} name address@hidden that packages under the @code{(gnu
-packages @dots{})} module name space are not necessarily ``GNU
-packages''. This module naming scheme follows the usual Guile module
-naming convention: @code{gnu} means that these modules are distributed
-as part of the GNU system, and @code{packages} identifies modules that
-define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
-Reference Manual}). For instance, the @code{(gnu packages emacs)}
-module exports a variable named @code{emacs}, which is bound to a
address@hidden<package>} object (@pxref{Defining Packages}).
address@hidden reproducible build environments
address@hidden development environments
address@hidden @command{guix environment}
address@hidden environment, package build environment
+The purpose of @command{guix environment} is to assist hackers in
+creating reproducible development environments without polluting their
+package profile. The @command{guix environment} tool takes one or more
+packages, builds all of their inputs, and creates a shell
+environment to use them.
-The @code{(gnu packages @dots{})} module name space is
-automatically scanned for packages by the command-line tools. For
-instance, when running @code{guix package -i emacs}, all the @code{(gnu
-packages @dots{})} modules are scanned until one that exports a package
-object whose name is @code{emacs} is found. This package search
-facility is implemented in the @code{(gnu packages)} module.
+The general syntax is:
address@hidden customization, of packages
address@hidden package module search path
-Users can store package definitions in modules with different
-names---e.g., @code{(my-packages emacs)address@hidden that the file
-name and module name must match. For instance, the @code{(my-packages
-emacs)} module must be stored in a @file{my-packages/emacs.scm} file
-relative to the load path specified with @option{--load-path} or
address@hidden @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
-these package definitions visible to the user interfaces:
address@hidden
+guix environment @var{options} @address@hidden
address@hidden example
address@hidden
address@hidden
-By adding the directory containing your package modules to the search path
-with the @code{-L} flag of @command{guix package} and other commands
-(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
-environment variable described below.
+The following example spawns a new shell set up for the development of
address@hidden:
address@hidden
-By defining a @dfn{channel} and configuring @command{guix pull} so that it
-pulls from it. A channel is essentially a Git repository containing package
-modules. @xref{Channels}, for more information on how to define and use
-channels.
address@hidden enumerate
address@hidden
+guix environment guile
address@hidden example
address@hidden works similarly to other search path variables:
+If the needed dependencies are not built yet, @command{guix environment}
+automatically builds them. The environment of the new shell is an augmented
+version of the environment that @command{guix environment} was run in.
+It contains the necessary search paths for building the given package
+added to the existing environment variables. To create a ``pure''
+environment, in which the original environment variables have been unset,
+use the @code{--pure} address@hidden sometimes wrongfully augment
+environment variables such as @code{PATH} in their @file{~/.bashrc}
+file. As a consequence, when @code{guix environment} launches it, Bash
+may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
+environment variables. It is an error to define such environment
+variables in @file{.bashrc}; instead, they should be defined in
address@hidden, which is sourced only by log-in shells.
address@hidden Startup Files,,, bash, The GNU Bash Reference Manual}, for
+details on Bash start-up files.}.
address@hidden {Environment Variable} GUIX_PACKAGE_PATH
-This is a colon-separated list of directories to search for additional
-package modules. Directories listed in this variable take precedence
-over the own modules of the distribution.
address@hidden defvr
address@hidden GUIX_ENVIRONMENT
address@hidden environment} defines the @code{GUIX_ENVIRONMENT}
+variable in the shell it spawns; its value is the file name of the
+profile of this environment. This allows users to, say, define a
+specific prompt for development environments in their @file{.bashrc}
+(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
-The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
-each package is built based solely on other packages in the
-distribution. The root of this dependency graph is a small set of
address@hidden binaries}, provided by the @code{(gnu packages
-bootstrap)} module. For more information on bootstrapping,
address@hidden
address@hidden
+if [ -n "$GUIX_ENVIRONMENT" ]
+then
+ export PS1="\u@@\h \w [dev]\$ "
+fi
address@hidden example
address@hidden Defining Packages
address@hidden Defining Packages
address@hidden
+...@: or to browse the profile:
-The high-level interface to package definitions is implemented in the
address@hidden(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:
address@hidden
+$ ls "$GUIX_ENVIRONMENT/bin"
address@hidden example
+
+Additionally, more than one package may be specified, in which case the
+union of the inputs for the given packages are used. For example, the
+command below spawns a shell where all of the dependencies of both Guile
+and Emacs are available:
@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))
+guix environment guile emacs
address@hidden example
-(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+)))
+Sometimes an interactive shell session is not desired. An arbitrary
+command may be invoked by placing the @code{--} token to separate the
+command from the rest of the arguments:
+
address@hidden
+guix environment guile -- make -j4
@end example
address@hidden
-Without being a Scheme expert, the reader may have guessed the meaning
-of the various fields here. This expression binds the variable
address@hidden 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
address@hidden(guix packages)} module; for instance, @code{(package-name hello)}
address@hidden"hello"}.
+In other situations, it is more convenient to specify the list of
+packages needed in the environment. For example, the following command
+runs @command{python} from an environment containing address@hidden and
+NumPy:
-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
address@hidden import} command (@pxref{Invoking guix import}).
address@hidden
+guix environment --ad-hoc python2-numpy python-2.7 -- python
address@hidden example
-In the example above, @var{hello} is defined in a module of its own,
address@hidden(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}).
+Furthermore, one might want the dependencies of a package and also some
+additional packages that are not build-time or runtime dependencies, but
+are useful when developing nonetheless. Because of this, the
address@hidden flag is positional. Packages appearing before
address@hidden are interpreted as packages whose dependencies will be
+added to the environment. Packages appearing after are interpreted as
+packages that will be added to the environment directly. For example,
+the following command creates a Guix development environment that
+additionally includes Git and strace:
-There are a few points worth noting in the above package definition:
address@hidden
+guix environment guix --ad-hoc git strace
address@hidden example
address@hidden
address@hidden
-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.
+Sometimes it is desirable to isolate the environment as much as
+possible, for maximal purity and reproducibility. In particular, when
+using Guix on a host distro that is not Guix System, it is desirable to
+prevent access to @file{/usr/bin} and other system-wide resources from
+the development environment. For example, the following command spawns
+a Guile REPL in a ``container'' where only the store and the current
+working directory are mounted:
-The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
-the GNU mirrors defined in @code{(guix download)}.
address@hidden
+guix environment --ad-hoc --container guile -- guile
address@hidden example
-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
address@hidden download} (@pxref{Invoking guix download}) and @code{guix
-hash} (@pxref{Invoking guix hash}).
address@hidden Note
+The @code{--container} option requires Linux-libre 3.19 or newer.
address@hidden quotation
address@hidden 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.
+The available options are summarized below.
address@hidden
address@hidden 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.
address@hidden @code
address@hidden address@hidden
address@hidden -r @var{file}
address@hidden persistent environment
address@hidden garbage collector root, for environments
+Make @var{file} a symlink to the profile for this environment, and
+register it as a garbage collector root.
address@hidden
-The @code{arguments} field specifies options for the build system
-(@pxref{Build Systems}). Here it is interpreted by
address@hidden as a request run @file{configure} with the
address@hidden flag.
+This is useful if you want to protect your environment from garbage
+collection, to make it ``persistent''.
address@hidden quote
address@hidden quoting
address@hidden '
address@hidden quote
-What about these quote (@code{'}) characters? They are Scheme syntax to
-introduce a literal list; @code{'} is synonymous with @code{quote}.
address@hidden 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
address@hidden:configure-flags} is a keyword used to pass a keyword argument
-to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
-Reference Manual}).
-
address@hidden
-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.
+When this option is omitted, the environment is protected from garbage
+collection only for the duration of the @command{guix environment}
+session. This means that next time you recreate the same environment,
+you could have to rebuild or re-download packages. @xref{Invoking guix
+gc}, for more on GC roots.
address@hidden backquote (quasiquote)
address@hidden `
address@hidden quasiquote
address@hidden comma (unquote)
address@hidden ,
address@hidden unquote
address@hidden ,@@
address@hidden unquote-splicing
-Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
-us to introduce a literal list in the @code{inputs} field, while
address@hidden,} (a comma, synonymous with @code{unquote}) allows us to insert a
-value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
-Reference Manual}).
address@hidden address@hidden
address@hidden -e @var{expr}
+Create an environment for the package or list of packages that
address@hidden evaluates to.
-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}).
+For example, running:
-However, any other dependencies need to be specified in the
address@hidden field. Any dependency not specified here will simply be
-unavailable to the build process, possibly leading to a build failure.
address@hidden itemize
address@hidden
+guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
address@hidden example
address@hidden Reference}, for a full description of possible fields.
+starts a shell with the environment for this specific variant of the
+PETSc package.
-Once a package definition is in place, the
-package may actually be built using the @code{guix build} command-line
-tool (@pxref{Invoking guix build}), troubleshooting any build failures
-you encounter (@pxref{Debugging Build Failures}). You can easily jump back to
the
-package definition using the @command{guix edit} command
-(@pxref{Invoking guix edit}).
address@hidden Guidelines}, for
-more information on how to test package definitions, and
address@hidden guix lint}, for information on how to check a definition
-for style conformance.
address@hidden GUIX_PACKAGE_PATH
-Lastly, @pxref{Channels}, for information
-on how to extend the distribution by adding your own package definitions
-in a ``channel''.
+Running:
-Finally, updating the package definition to a new upstream version
-can be partly automated by the @command{guix refresh} command
-(@pxref{Invoking guix refresh}).
address@hidden
+guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
address@hidden example
-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
address@hidden procedure (@pxref{The Store}).
+starts a shell with all the base system packages available.
address@hidden {Scheme Procedure} package-derivation @var{store} @var{package}
address@hidden
-Return the @code{<derivation>} object of @var{package} for @var{system}
-(@pxref{Derivations}).
+The above commands only use the default output of the given packages.
+To select other outputs, two element tuples can be specified:
address@hidden must be a valid @code{<package>} object, and @var{system}
-must be a string denoting the target system type---e.g.,
address@hidden"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}).
address@hidden deffn
address@hidden
+guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
address@hidden example
address@hidden
address@hidden cross-compilation
-Similarly, it is possible to compute a derivation that cross-builds a
-package for some other system:
address@hidden address@hidden
address@hidden -l @var{file}
+Create an environment for the package or list of packages that the code
+within @var{file} evaluates to.
address@hidden {Scheme Procedure} package-cross-derivation @var{store} @
- @var{package} @var{target} address@hidden
-Return the @code{<derivation>} object of @var{package} cross-built from
address@hidden to @var{target}.
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
address@hidden 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}).
address@hidden deffn
address@hidden
address@hidden environment-gdb.scm
address@hidden example
address@hidden package transformations
address@hidden input rewriting
address@hidden 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:
address@hidden address@hidden
address@hidden -m @var{file}
+Create an environment for the packages contained in the manifest object
+returned by the Scheme code in @var{file}.
address@hidden {Scheme Procedure} package-input-rewriting @var{replacements} @
- address@hidden
-Return a procedure that, when passed a package, replaces its direct and
-indirect dependencies (but not its implicit inputs) according to
address@hidden @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.
+This is similar to the same-named option in @command{guix package}
+(@pxref{profile-manifest, @option{--manifest}}) and uses the same
+manifest files.
-Optionally, @var{rewrite-name} is a one-argument procedure that takes
-the name of a package and returns its new name after rewrite.
address@hidden deffn
address@hidden --ad-hoc
+Include all specified packages in the resulting environment, as if an
address@hidden hoc} package were defined with them as inputs. This option is
+useful for quickly creating an environment without having to write a
+package expression to contain the desired inputs.
address@hidden
-Consider this example:
+For instance, the command:
@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))
+guix environment --ad-hoc guile guile-sdl -- guile
@end example
address@hidden
-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
address@hidden 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}}).
+runs @command{guile} in an environment where Guile and Guile-SDL are
+available.
-A more generic procedure to rewrite a package dependency graph is
address@hidden: it supports arbitrary changes to nodes in the
-graph.
+Note that this example implicitly asks for the default output of
address@hidden and @code{guile-sdl}, but it is possible to ask for a
+specific output---e.g., @code{glib:bin} asks for the @code{bin} output
+of @code{glib} (@pxref{Packages with Multiple Outputs}).
address@hidden {Scheme Procedure} package-mapping @var{proc} address@hidden
-Return a procedure that, given a package, applies @var{proc} to all the
packages
-depended on and returns the resulting package. The procedure stops recursion
-when @var{cut?} returns true for a given package.
address@hidden deffn
+This option may be composed with the default behavior of @command{guix
+environment}. Packages appearing before @code{--ad-hoc} are interpreted
+as packages whose dependencies will be added to the environment, the
+default behavior. Packages appearing after are interpreted as packages
+that will be added to the environment directly.
address@hidden
-* package Reference:: The package data type.
-* origin Reference:: The origin data type.
address@hidden menu
address@hidden --pure
+Unset existing environment variables when building the new environment.
+This has the effect of creating an environment in which search paths
+only contain package inputs.
address@hidden --search-paths
+Display the environment variable definitions that make up the
+environment.
address@hidden package Reference
address@hidden @code{package} Reference
address@hidden address@hidden
address@hidden -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}.
-This section summarizes all the options available in @code{package}
-declarations (@pxref{Defining Packages}).
address@hidden --container
address@hidden -C
address@hidden container
+Run @var{command} within an isolated container. The current working
+directory outside the container is mapped inside the container.
+Additionally, unless overridden with @code{--user}, a dummy home
+directory is created that matches the current user's home directory, and
address@hidden/etc/passwd} is configured accordingly. The spawned process runs
+as the current user outside the container, but has root privileges in
+the context of the container.
address@hidden {Data Type} package
-This is the data type representing a package recipe.
address@hidden --network
address@hidden -N
+For containers, share the network namespace with the host system.
+Containers created without this flag only have access to the loopback
+device.
address@hidden @asis
address@hidden @code{name}
-The name of the package, as a string.
address@hidden --link-profile
address@hidden -P
+For containers, link the environment profile to
address@hidden/.guix-profile} within the container. This is equivalent to
+running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
+within the container. Linking will fail and abort the environment if
+the directory already exists, which will certainly be the case if
address@hidden environment} was invoked in the user's home directory.
address@hidden @code{version}
-The version of the package, as a string.
+Certain packages are configured to look in
address@hidden/.guix-profile} for configuration files and data;@footnote{For
+example, the @code{fontconfig} package inspects
address@hidden/.guix-profile/share/fonts} for additional fonts.}
address@hidden allows these programs to behave as expected within
+the environment.
address@hidden @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,
address@hidden).
address@hidden address@hidden
address@hidden -u @var{user}
+For containers, use the username @var{user} in place of the current
+user. The generated @file{/etc/passwd} entry within the container will
+contain the name @var{user}; the home directory will be
address@hidden/home/USER}; and no user GECOS data will be copied. @var{user}
+need not exist on the system.
address@hidden @code{build-system}
-The build system that should be used to build the package (@pxref{Build
-Systems}).
-
address@hidden @code{arguments} (default: @code{'()})
-The arguments that should be passed to the build system. This is a
-list, typically containing sequential keyword-value pairs.
-
address@hidden @code{inputs} (default: @code{'()})
address@hidden @code{native-inputs} (default: @code{'()})
address@hidden @code{propagated-inputs} (default: @code{'()})
address@hidden 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:
+Additionally, any shared or exposed path (see @code{--share} and
address@hidden respectively) whose target is within the current user's
+home directory will be remapped relative to @file{/home/USER}; this
+includes the automatic mapping of the current working directory.
@example
-`(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
+# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
+cd $HOME/wd
+guix environment --container --user=foo \
+ --expose=$HOME/test \
+ --expose=/tmp/target=$HOME/target
@end example
address@hidden 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.
-
address@hidden 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}).
-
address@hidden
-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.)
+While this will limit the leaking of user identity through home paths
+and each of the user fields, this is only one useful component of a
+broader privacy/anonymity solution---not one in and of itself.
-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.
address@hidden address@hidden@var{target}]
+For containers, expose the file system @var{source} from the host system
+as the read-only file system @var{target} within the container. If
address@hidden is not specified, @var{source} is used as the target mount
+point in the container.
-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
address@hidden 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}.
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible read-only via the @file{/exchange}
+directory:
address@hidden @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.
address@hidden
+guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
address@hidden example
address@hidden @code{outputs} (default: @code{'("out")})
-The list of output names of the package. @xref{Packages with Multiple
-Outputs}, for typical uses of additional outputs.
address@hidden address@hidden@var{target}]
+For containers, share the file system @var{source} from the host system
+as the writable file system @var{target} within the container. If
address@hidden is not specified, @var{source} is used as the target mount
+point in the container.
address@hidden @code{native-search-paths} (default: @code{'()})
address@hidden @code{search-paths} (default: @code{'()})
-A list of @code{search-path-specification} objects describing
-search-path environment variables honored by the package.
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible for both reading and writing via the
address@hidden/exchange} directory:
address@hidden @code{replacement} (default: @code{#f})
-This must be either @code{#f} or a package object that will be used as a
address@hidden for this package. @xref{Security Updates, grafts},
-for details.
address@hidden
+guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
address@hidden example
address@hidden table
address@hidden @code{synopsis}
-A one-line description of the package.
address@hidden environment}
+also supports all of the common build options that @command{guix
+build} supports (@pxref{Common Build Options}) as well as package
+transformation options (@pxref{Package Transformation Options}).
address@hidden @code{description}
-A more elaborate description of the package.
address@hidden Invoking guix pack
address@hidden Invoking @command{guix pack}
address@hidden @code{license}
address@hidden license, of packages
-The license of the package; a value from @code{(guix licenses)},
-or a list of such values.
+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.
address@hidden @code{home-page}
-The URL to the home-page of the package, as a string.
address@hidden Note
+If you are looking for ways to exchange binaries among machines that
+already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
+publish}, and @ref{Invoking guix archive}.
address@hidden quotation
address@hidden @code{supported-systems} (default: @var{%supported-systems})
-The list of systems supported by the package, as strings of the form
address@hidden, for example @code{"x86_64-linux"}.
address@hidden pack
address@hidden bundle
address@hidden application bundle
address@hidden software bundle
+The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
address@hidden bundle}: it creates a tarball or some other archive
+containing the binaries of the software you're interested in, and all
+its dependencies. The resulting archive can be used on any machine that
+does not have Guix, and people can run the exact same binaries as those
+you have with Guix. The pack itself is created in a bit-reproducible
+fashion, so anyone can verify that it really contains the build results
+that you pretend to be shipping.
address@hidden @code{maintainers} (default: @code{'()})
-The list of maintainers of the package, as @code{maintainer} objects.
+For example, to create a bundle containing Guile, Emacs, Geiser, and all
+their dependencies, you can run:
address@hidden @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.
address@hidden table
address@hidden deftp
address@hidden
+$ guix pack guile emacs geiser
address@hidden
+/gnu/store/@dots{}-pack.tar.gz
address@hidden example
+The result here is a tarball containing a @file{/gnu/store} directory
+with all the relevant packages. The resulting tarball contains a
address@hidden 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}).
address@hidden origin Reference
address@hidden @code{origin} Reference
+Users of this pack would have to run
address@hidden/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
+find inconvenient. To work around it, you can create, say, a
address@hidden/opt/gnu/bin} symlink to the profile:
-This section summarizes all the options available in @code{origin}
-declarations (@pxref{Defining Packages}).
address@hidden
+guix pack -S /opt/gnu/bin=bin guile emacs geiser
address@hidden example
address@hidden {Data Type} origin
-This is the data type representing a source code origin.
address@hidden
+That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
address@hidden @asis
address@hidden @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
address@hidden method of @code{(guix download)}, the valid @code{uri}
-values are: a URL represented as a string, or a list thereof.
address@hidden relocatable binaries, with @command{guix pack}
+What if the recipient of your pack does not have root privileges on
+their machine, and thus cannot unpack it in the root file system? In
+that case, you will want to use the @code{--relocatable} option (see
+below). This option produces @dfn{relocatable binaries}, meaning they
+they can be placed anywhere in the file system hierarchy: in the example
+above, users can unpack your tarball in their home directory and
+directly run @file{./opt/gnu/bin/guile}.
address@hidden @code{method}
-A procedure that handles the URI.
address@hidden Docker, build an image with guix pack
+Alternatively, you can produce a pack in the Docker image format using
+the following command:
-Examples include:
address@hidden
+guix pack -f docker guile emacs geiser
address@hidden example
address@hidden @asis
address@hidden @var{url-fetch} from @code{(guix download)}
-download a file from the HTTP, HTTPS, or FTP URL specified in the
address@hidden field;
address@hidden
+The result is a tarball that can be passed to the @command{docker load}
+command. See the
address@hidden://docs.docker.com/engine/reference/commandline/load/, Docker
+documentation} for more information.
address@hidden git-fetch
address@hidden @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
address@hidden looks like this:
address@hidden Singularity, build an image with guix pack
address@hidden SquashFS, build an image with guix pack
+Yet another option is to produce a SquashFS image with the following
+command:
@example
-(git-reference
- (url "git://git.debian.org/git/pkg-shadow/shadow")
- (commit "v4.1.5.1"))
+guix pack -f squashfs guile emacs geiser
@end example
address@hidden table
address@hidden @code{sha256}
-A bytevector containing the SHA-256 hash of the source. Typically the
address@hidden form is used here to generate the bytevector from a
-base-32 string.
address@hidden
+The result is a SquashFS file system image that can either be mounted or
+directly be used as a file system container image with the
address@hidden://singularity.lbl.gov, Singularity container execution
+environment}, using commands like @command{singularity shell} or
address@hidden exec}.
-You can obtain this information using @code{guix download}
-(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
-guix hash}).
+Several command-line options allow you to customize your pack:
address@hidden @code{file-name} (default: @code{#f})
-The file name under which the source code should be saved. When this is
address@hidden, 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.
address@hidden @code
address@hidden address@hidden
address@hidden -f @var{format}
+Produce a pack in the given @var{format}.
address@hidden @code{patches} (default: @code{'()})
-A list of file names, origins, or file-like objects (@pxref{G-Expressions,
-file-like objects}) pointing to patches to be applied to the source.
+The available formats are:
-This list of patches must be unconditional. In particular, it cannot
-depend on the value of @code{%current-system} or
address@hidden
address@hidden @code
address@hidden tarball
+This is the default format. It produces a tarball containing all the
+specified binaries and symlinks.
address@hidden @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.
address@hidden docker
+This produces a tarball that follows the
address@hidden://github.com/docker/docker/blob/master/image/spec/v1.2.md,
+Docker Image Specification}.
address@hidden @code{patch-flags} (default: @code{'("-p1")})
-A list of command-line flags that should be passed to the @code{patch}
-command.
address@hidden squashfs
+This produces a SquashFS image containing all the specified binaries and
+symlinks, as well as empty mount points for virtual file systems like
+procfs.
address@hidden table
address@hidden @code{patch-inputs} (default: @code{#f})
-Input packages or derivations to the patching process. When this is
address@hidden, the usual set of inputs necessary for patching are provided,
-such as address@hidden
address@hidden --relocatable
address@hidden -R
+Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
+anywhere in the file system hierarchy and run from there. For example,
+if you create a pack containing Bash with:
address@hidden @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.
address@hidden
+guix pack -R -S /mybin=bin bash
address@hidden example
address@hidden @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.
address@hidden table
address@hidden deftp
address@hidden
+...@: you can copy that pack to a machine that lacks Guix, and from your
+home directory as a normal user, run:
address@hidden
+tar xf pack.tar.gz
+./mybin/sh
address@hidden example
address@hidden Build Systems
address@hidden Build Systems
address@hidden
+In that shell, if you type @code{ls /gnu/store}, you'll notice that
address@hidden/gnu/store} shows up and contains all the dependencies of
address@hidden, even though the machine actually lacks @file{/gnu/store}
+altogether! That is probably the simplest way to deploy Guix-built
+software on a non-Guix machine.
address@hidden 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.
+There's a gotcha though: this technique relies on the @dfn{user
+namespace} feature of the kernel Linux, which allows unprivileged users
+to mount or change root. Old versions of Linux did not support it, and
+some GNU/Linux distributions turn it off; on these systems, programs
+from the pack @emph{will fail to run}, unless they are unpacked in the
+root file system.
-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.
address@hidden address@hidden
address@hidden -e @var{expr}
+Consider the package @var{expr} evaluates to.
address@hidden bag (low-level package representation)
-Under the hood, build systems first compile package objects to
address@hidden 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}).
+This has the same purpose as the same-named option in @command{guix
+build} (@pxref{Additional Build Options, @code{--expression} in
address@hidden build}}).
-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}).
address@hidden address@hidden
address@hidden -m @var{file}
+Use the packages contained in the manifest object returned by the Scheme
+code in @var{file}.
-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.
+This has a similar purpose as the same-named option in @command{guix
+package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
+same manifest files. It allows you to define a collection of packages
+once and use it both for creating profiles and for creating archives
+for use on machines that do not have Guix installed. Note that you can
+specify @emph{either} a manifest file @emph{or} a list of packages,
+but not both.
address@hidden {Scheme Variable} gnu-build-system
address@hidden represents the GNU Build System, and variants
-thereof (@pxref{Configuration, configuration and makefile conventions,,
-standards, GNU Coding Standards}).
address@hidden address@hidden
address@hidden -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
+the system type of the build host.
address@hidden 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},
address@hidden see the @code{(guix build gnu-build-system)}
-modules for more details about the build phases.}:
address@hidden address@hidden
address@hidden cross-compilation
+Cross-build for @var{triplet}, which must be a valid GNU triplet, such
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+configuration triplets,, autoconf, Autoconf}).
address@hidden @code
address@hidden 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.
address@hidden address@hidden
address@hidden -C @var{tool}
+Compress the resulting tarball using @var{tool}---one of @code{gzip},
address@hidden, @code{xz}, @code{lzip}, or @code{none} for no compression.
address@hidden 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
address@hidden/gnu/store/@dots{}-bash-4.3/bin/sh}.
address@hidden address@hidden
address@hidden -S @var{spec}
+Add the symlinks specified by @var{spec} to the pack. This option can
+appear several times.
address@hidden 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.
address@hidden has the form @address@hidden@var{target}}, where
address@hidden is the symlink that will be created and @var{target} is the
+symlink target.
address@hidden build
-Run @code{make} with the list of flags specified with
address@hidden:make-flags}. If the @code{#:parallel-build?} argument is true
-(the default), build with @code{make -j}.
+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.
address@hidden check
-Run @code{make check}, or some other target specified with
address@hidden:test-target}, unless @code{#:tests? #f} is passed. If the
address@hidden:parallel-tests?} argument is true (the default), run @code{make
-check -j}.
address@hidden --localstatedir
address@hidden address@hidden
+Include the ``local state directory'', @file{/var/guix}, in the resulting
+pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
+profile---by default @var{name} is @code{guix-profile}, which corresponds to
address@hidden/.guix-profile}.
address@hidden install
-Run @code{make install} with the flags listed in @code{#:make-flags}.
address@hidden/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.
address@hidden patch-shebangs
-Patch shebangs on the installed executable files.
+One use case for this is the Guix self-contained binary tarball
+(@pxref{Binary Installation}).
address@hidden 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}).
address@hidden --bootstrap
+Use the bootstrap binaries to build the pack. This option is only
+useful to Guix developers.
@end table
address@hidden %standard-phases
-The build-side module @code{(guix build gnu-build-system)} defines
address@hidden as the default list of build phases.
address@hidden is a list of symbol/procedure pairs, where the
-procedure implements the actual phase.
+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}).
-The list of phases used for a particular package can be changed with the
address@hidden:phases} parameter. For instance, passing:
address@hidden
-#:phases (modify-phases %standard-phases (delete 'configure))
address@hidden example
address@hidden
*********************************************************************
address@hidden Programming Interface
address@hidden Programming Interface
-means that all the phases described above will be used, except the
address@hidden phase.
+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.
-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
address@hidden inputs} of a package, because package definitions do not
-have to mention them.
address@hidden defvr
+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
address@hidden/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.
-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.
address@hidden 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.
address@hidden {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
address@hidden://ant.apache.org/, Ant build tool}.
+This chapter describes all these APIs in turn, starting from high-level
+package definitions.
-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.
address@hidden
+* Package Modules:: Packages from the programmer's viewpoint.
+* 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.
+* Invoking guix repl:: Fiddling with Guix interactively.
address@hidden menu
-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. In this case the parameter @code{#:source-dir} can be used to
-specify the source sub-directory, defaulting to ``src''.
address@hidden Package Modules
address@hidden Package Modules
-The @code{#:main-class} parameter can be used with the minimal ant
-buildfile to specify the main class of the resulting jar. This makes the
-jar file executable. The @code{#:test-include} parameter can be used to
-specify the list of junit tests to run. It defaults to
address@hidden(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
-disable some tests. It defaults to @code{(list "**/Abstract*.java")},
-because abstract classes cannot be run as tests.
+From a programming viewpoint, the package definitions of the
+GNU distribution are provided by Guile modules in the @code{(gnu packages
address@hidden)} name address@hidden that packages under the @code{(gnu
+packages @dots{})} module name space are not necessarily ``GNU
+packages''. This module naming scheme follows the usual Guile module
+naming convention: @code{gnu} means that these modules are distributed
+as part of the GNU system, and @code{packages} identifies modules that
+define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
+Reference Manual}). For instance, the @code{(gnu packages emacs)}
+module exports a variable named @code{emacs}, which is bound to a
address@hidden<package>} object (@pxref{Defining Packages}).
-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.
+The @code{(gnu packages @dots{})} module name space is
+automatically scanned for packages by the command-line tools. For
+instance, when running @code{guix package -i emacs}, all the @code{(gnu
+packages @dots{})} modules are scanned until one that exports a package
+object whose name is @code{emacs} is found. This package search
+facility is implemented in the @code{(gnu packages)} module.
+
address@hidden customization, of packages
address@hidden package module search path
+Users can store package definitions in modules with different
+names---e.g., @code{(my-packages emacs)address@hidden that the file
+name and module name must match. For instance, the @code{(my-packages
+emacs)} module must be stored in a @file{my-packages/emacs.scm} file
+relative to the load path specified with @option{--load-path} or
address@hidden @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
+these package definitions visible to the user interfaces:
+
address@hidden
address@hidden
+By adding the directory containing your package modules to the search path
+with the @code{-L} flag of @command{guix package} and other commands
+(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+environment variable described below.
+
address@hidden
+By defining a @dfn{channel} and configuring @command{guix pull} so that it
+pulls from it. A channel is essentially a Git repository containing package
+modules. @xref{Channels}, for more information on how to define and use
+channels.
address@hidden enumerate
+
address@hidden works similarly to other search path variables:
address@hidden {Environment Variable} GUIX_PACKAGE_PATH
+This is a colon-separated list of directories to search for additional
+package modules. Directories listed in this variable take precedence
+over the own modules of the distribution.
@end defvr
address@hidden {Scheme Variable} android-ndk-build-system
address@hidden Android distribution
address@hidden Android NDK build system
-This variable is exported by @code{(guix build-system android-ndk)}. It
-implements a build procedure for Android NDK (native development kit)
-packages using a Guix-specific build process.
+The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
+each package is built based solely on other packages in the
+distribution. The root of this dependency graph is a small set of
address@hidden binaries}, provided by the @code{(gnu packages
+bootstrap)} module. For more information on bootstrapping,
address@hidden
-The build system assumes that packages install their public interface
-(header) files to the subdirectory "include" of the "out" output and
-their libraries to the subdirectory "lib" of the "out" output.
address@hidden Defining Packages
address@hidden Defining Packages
-It's also assumed that the union of all the dependencies of a package
-has no conflicting files.
+The high-level interface to package definitions is implemented in the
address@hidden(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:
-For the time being, cross-compilation is not supported - so right now
-the libraries and header files are assumed to be host tools.
address@hidden
+(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))
address@hidden defvr
+(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+)))
address@hidden example
address@hidden {Scheme Variable} asdf-build-system/source
address@hidden {Scheme Variable} asdf-build-system/sbcl
address@hidden {Scheme Variable} asdf-build-system/ecl
address@hidden
+Without being a Scheme expert, the reader may have guessed the meaning
+of the various fields here. This expression binds the variable
address@hidden 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
address@hidden(guix packages)} module; for instance, @code{(package-name hello)}
address@hidden"hello"}.
-These variables, exported by @code{(guix build-system asdf)}, implement
-build procedures for Common Lisp packages using
address@hidden://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
-definition facility for Common Lisp programs and libraries.
+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
address@hidden import} command (@pxref{Invoking guix import}).
-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.
+In the example above, @var{hello} is defined in a module of its own,
address@hidden(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}).
-The build system uses naming conventions. For binary packages, the
-package name should be prefixed with the lisp implementation, such as
address@hidden for @code{asdf-build-system/sbcl}.
+There are a few points worth noting in the above package definition:
-Additionally, the corresponding source package should be labeled using
-the same convention as python packages (see @ref{Python Modules}), using
-the @code{cl-} prefix.
address@hidden
address@hidden
+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.
-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.
+The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
+the GNU mirrors defined in @code{(guix download)}.
-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.
+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
address@hidden download} (@pxref{Invoking guix download}) and @code{guix
+hash} (@pxref{Invoking guix hash}).
-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. Furthermore, if the package
-defines a system for its tests in a separate file, it will be loaded
-before the tests are run if it is specified by the
address@hidden:test-asd-file} parameter. If it is not set, the files
address@hidden<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
-and @code{test.asd} will be tried if they exist.
address@hidden 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.
-If for some reason the package must be named in a different way than the
-naming conventions suggest, the @code{#:asd-system-name} parameter can
-be used to specify the name of the system.
address@hidden
address@hidden 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.
address@hidden defvr
address@hidden
+The @code{arguments} field specifies options for the build system
+(@pxref{Build Systems}). Here it is interpreted by
address@hidden as a request run @file{configure} with the
address@hidden flag.
address@hidden {Scheme Variable} cargo-build-system
address@hidden Rust programming language
address@hidden 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
address@hidden://www.rust-lang.org, Rust programming language}.
address@hidden quote
address@hidden quoting
address@hidden '
address@hidden quote
+What about these quote (@code{'}) characters? They are Scheme syntax to
+introduce a literal list; @code{'} is synonymous with @code{quote}.
address@hidden 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}).
-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.
address@hidden defvr
+The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
+(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
address@hidden:configure-flags} is a keyword used to pass a keyword argument
+to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
+Reference Manual}).
address@hidden Clojure (programming language)
address@hidden simple Clojure build system
address@hidden {Scheme Variable} clojure-build-system
-This variable is exported by @code{(guix build-system clojure)}. It implements
-a simple build procedure for @uref{https://clojure.org/, Clojure} packages
-using plain old @code{compile} in Clojure. Cross-compilation is not supported
-yet.
address@hidden
+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.
-It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
-Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
address@hidden:zip} parameters, respectively.
address@hidden backquote (quasiquote)
address@hidden `
address@hidden quasiquote
address@hidden comma (unquote)
address@hidden ,
address@hidden unquote
address@hidden ,@@
address@hidden unquote-splicing
+Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
+us to introduce a literal list in the @code{inputs} field, while
address@hidden,} (a comma, synonymous with @code{unquote}) allows us to insert a
+value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
+Reference Manual}).
-A list of source directories, test directories and jar names can be specified
-with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
-parameters, respectively. Compile directory and main class can be specified
-with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
-Other parameters are documented below.
+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}).
-This build system is an extension of @var{ant-build-system}, but with the
-following phases changed:
+However, any other dependencies need to be specified in the
address@hidden field. Any dependency not specified here will simply be
+unavailable to the build process, possibly leading to a build failure.
address@hidden itemize
address@hidden @code
address@hidden Reference}, for a full description of possible fields.
address@hidden build
-This phase calls @code{compile} in Clojure to compile source files and runs
address@hidden to create jars from both source files and compiled files
-according to the include list and exclude list specified in
address@hidden:aot-include} and @code{#:aot-exclude}, respectively. The
exclude list
-has priority over the include list. These lists consist of symbols
-representing Clojure libraries or the special keyword @code{#:all} representing
-all Clojure libraries found under the source directories. The parameter
address@hidden:omit-source?} decides if source should be included into the jars.
+Once a package definition is in place, the
+package may actually be built using the @code{guix build} command-line
+tool (@pxref{Invoking guix build}), troubleshooting any build failures
+you encounter (@pxref{Debugging Build Failures}). You can easily jump back to
the
+package definition using the @command{guix edit} command
+(@pxref{Invoking guix edit}).
address@hidden Guidelines}, for
+more information on how to test package definitions, and
address@hidden guix lint}, for information on how to check a definition
+for style conformance.
address@hidden GUIX_PACKAGE_PATH
+Lastly, @pxref{Channels}, for information
+on how to extend the distribution by adding your own package definitions
+in a ``channel''.
address@hidden check
-This phase runs tests according to the include list and exclude list specified
-in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
-meanings are analogous to that of @code{#:aot-include} and
address@hidden:aot-exclude}, except that the special keyword @code{#:all} now
-stands for all Clojure libraries found under the test directories. The
-parameter @code{#:tests?} decides if tests should be run.
+Finally, updating the package definition to a new upstream version
+can be partly automated by the @command{guix refresh} command
+(@pxref{Invoking guix refresh}).
address@hidden install
-This phase installs all jars built previously.
+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
address@hidden procedure (@pxref{The Store}).
+
address@hidden {Scheme Procedure} package-derivation @var{store} @var{package}
address@hidden
+Return the @code{<derivation>} object of @var{package} for @var{system}
+(@pxref{Derivations}).
+
address@hidden must be a valid @code{<package>} object, and @var{system}
+must be a string denoting the target system type---e.g.,
address@hidden"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}).
address@hidden deffn
+
address@hidden
address@hidden cross-compilation
+Similarly, it is possible to compute a derivation that cross-builds a
+package for some other system:
+
address@hidden {Scheme Procedure} package-cross-derivation @var{store} @
+ @var{package} @var{target} address@hidden
+Return the @code{<derivation>} object of @var{package} cross-built from
address@hidden to @var{target}.
+
address@hidden 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}).
address@hidden deffn
+
address@hidden package transformations
address@hidden input rewriting
address@hidden 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:
+
address@hidden {Scheme Procedure} package-input-rewriting @var{replacements} @
+ address@hidden
+Return a procedure that, when passed a package, replaces its direct and
+indirect dependencies (but not its implicit inputs) according to
address@hidden @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.
address@hidden deffn
+
address@hidden
+Consider this example:
+
address@hidden
+(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))
address@hidden example
+
address@hidden
+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
address@hidden package that uses @var{libressl} instead of @var{openssl}.
+This is exactly what the @option{--with-input} command-line option does
+(@pxref{Package Transformation Options, @option{--with-input}}).
+
+A more generic procedure to rewrite a package dependency graph is
address@hidden: it supports arbitrary changes to nodes in the
+graph.
+
address@hidden {Scheme Procedure} package-mapping @var{proc} address@hidden
+Return a procedure that, given a package, applies @var{proc} to all the
packages
+depended on and returns the resulting package. The procedure stops recursion
+when @var{cut?} returns true for a given package.
address@hidden deffn
+
address@hidden
+* package Reference:: The package data type.
+* origin Reference:: The origin data type.
address@hidden menu
+
+
address@hidden package Reference
address@hidden @code{package} Reference
+
+This section summarizes all the options available in @code{package}
+declarations (@pxref{Defining Packages}).
+
address@hidden {Data Type} package
+This is the data type representing a package recipe.
+
address@hidden @asis
address@hidden @code{name}
+The name of the package, as a string.
+
address@hidden @code{version}
+The version of the package, as a string.
+
address@hidden @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,
address@hidden).
+
address@hidden @code{build-system}
+The build system that should be used to build the package (@pxref{Build
+Systems}).
+
address@hidden @code{arguments} (default: @code{'()})
+The arguments that should be passed to the build system. This is a
+list, typically containing sequential keyword-value pairs.
+
address@hidden @code{inputs} (default: @code{'()})
address@hidden @code{native-inputs} (default: @code{'()})
address@hidden @code{propagated-inputs} (default: @code{'()})
address@hidden 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:
+
address@hidden
+`(("libffi" ,libffi)
+ ("libunistring" ,libunistring)
+ ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
address@hidden example
+
address@hidden 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.
+
address@hidden 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}).
+
address@hidden
+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
address@hidden 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}.
+
address@hidden @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.
+
address@hidden @code{outputs} (default: @code{'("out")})
+The list of output names of the package. @xref{Packages with Multiple
+Outputs}, for typical uses of additional outputs.
+
address@hidden @code{native-search-paths} (default: @code{'()})
address@hidden @code{search-paths} (default: @code{'()})
+A list of @code{search-path-specification} objects describing
+search-path environment variables honored by the package.
+
address@hidden @code{replacement} (default: @code{#f})
+This must be either @code{#f} or a package object that will be used as a
address@hidden for this package. @xref{Security Updates, grafts},
+for details.
+
address@hidden @code{synopsis}
+A one-line description of the package.
+
address@hidden @code{description}
+A more elaborate description of the package.
+
address@hidden @code{license}
address@hidden license, of packages
+The license of the package; a value from @code{(guix licenses)},
+or a list of such values.
+
address@hidden @code{home-page}
+The URL to the home-page of the package, as a string.
+
address@hidden @code{supported-systems} (default: @var{%supported-systems})
+The list of systems supported by the package, as strings of the form
address@hidden, for example @code{"x86_64-linux"}.
+
address@hidden @code{maintainers} (default: @code{'()})
+The list of maintainers of the package, as @code{maintainer} objects.
+
address@hidden @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
address@hidden deftp
-Apart from the above, this build system also contains an additional phase:
address@hidden @code
address@hidden origin Reference
address@hidden @code{origin} Reference
address@hidden install-doc
-This phase installs all top-level files with base name matching
address@hidden A different regex can be specified with the
address@hidden:doc-regex} parameter. All files (recursively) inside the
documentation
-directories specified in @code{#:doc-dirs} are installed as well.
address@hidden table
address@hidden defvr
+This section summarizes all the options available in @code{origin}
+declarations (@pxref{Defining Packages}).
address@hidden {Scheme Variable} cmake-build-system
-This variable is exported by @code{(guix build-system cmake)}. It
-implements the build procedure for packages using the
address@hidden://www.cmake.org, CMake build tool}.
address@hidden {Data Type} origin
+This is the data type representing a source code origin.
-It automatically adds the @code{cmake} package to the set of inputs.
-Which package is used can be specified with the @code{#:cmake}
-parameter.
address@hidden @asis
address@hidden @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
address@hidden method of @code{(guix download)}, the valid @code{uri}
+values are: a URL represented as a string, or a list thereof.
-The @code{#:configure-flags} parameter is taken as a list of flags
-passed to the @command{cmake} command. The @code{#:build-type}
-parameter specifies in abstract terms the flags passed to the compiler;
-it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
-debugging information''), which roughly means that code is compiled with
address@hidden -g}, as is the case for Autoconf-based packages by default.
address@hidden defvr
address@hidden @code{method}
+A procedure that handles the URI.
address@hidden {Scheme Variable} dune-build-system
-This variable is exported by @code{(guix build-system dune)}. It
-supports builds of packages using @uref{https://dune.build/, Dune}, a build
-tool for the OCaml programming language. It is implemented as an extension
-of the @code{ocaml-build-system} which is described below. As such, the
address@hidden:ocaml} and @code{#:findlib} parameters can be passed to this
build
-system.
+Examples include:
-It automatically adds the @code{dune} package to the set of inputs.
-Which package is used can be specified with the @code{#:dune}
-parameter.
address@hidden @asis
address@hidden @var{url-fetch} from @code{(guix download)}
+download a file from the HTTP, HTTPS, or FTP URL specified in the
address@hidden field;
-There is no @code{configure} phase because dune packages typically don't
-need to be configured. The @code{#:build-flags} parameter is taken as a
-list of flags passed to the @code{dune} command during the build.
address@hidden git-fetch
address@hidden @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
address@hidden looks like this:
-The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
-command instead of the more recent @code{dune} command while building
-a package. Its default value is @code{#f}.
address@hidden defvr
address@hidden
+(git-reference
+ (url "git://git.debian.org/git/pkg-shadow/shadow")
+ (commit "v4.1.5.1"))
address@hidden example
address@hidden table
address@hidden {Scheme Variable} go-build-system
-This variable is exported by @code{(guix build-system go)}. It
-implements a build procedure for Go packages using the standard
address@hidden://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
-Go build mechanisms}.
address@hidden @code{sha256}
+A bytevector containing the SHA-256 hash of the source. Typically the
address@hidden form is used here to generate the bytevector from a
+base-32 string.
-The user is expected to provide a value for the key @code{#:import-path}
-and, in some cases, @code{#:unpack-path}. The
address@hidden://golang.org/doc/code.html#ImportPaths, import path}
-corresponds to the file system path expected by the package's build
-scripts and any referring packages, and provides a unique way to
-refer to a Go package. It is typically based on a combination of the
-package source code's remote URI and file system hierarchy structure. In
-some cases, you will need to unpack the package's source code to a
-different directory structure than the one indicated by the import path,
-and @code{#:unpack-path} should be used in such cases.
+You can obtain this information using @code{guix download}
+(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
+guix hash}).
-Packages that provide Go libraries should be installed along with their
-source code. The key @code{#:install-source?}, which defaults to
address@hidden, controls whether or not the source code is installed. It can
-be set to @code{#f} for packages that only provide executable files.
address@hidden defvr
address@hidden @code{file-name} (default: @code{#f})
+The file name under which the source code should be saved. When this is
address@hidden, 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.
address@hidden {Scheme Variable} glib-or-gtk-build-system
-This variable is exported by @code{(guix build-system glib-or-gtk)}. It
-is intended for use with packages making use of GLib or GTK+.
address@hidden @code{patches} (default: @code{'()})
+A list of file names, origins, or file-like objects (@pxref{G-Expressions,
+file-like objects}) pointing to patches to be applied to the source.
-This build system adds the following two phases to the ones defined by
address@hidden:
+This list of patches must be unconditional. In particular, it cannot
+depend on the value of @code{%current-system} or
address@hidden
address@hidden @code
address@hidden glib-or-gtk-wrap
-The phase @code{glib-or-gtk-wrap} ensures that programs in
address@hidden/} are able to find GLib ``schemas'' and
address@hidden://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
-modules}. This is achieved by wrapping the programs in launch scripts
-that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
-environment variables.
address@hidden @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.
-It is possible to exclude specific package outputs from that wrapping
-process by listing their names in the
address@hidden:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
-when an output is known not to contain any GLib or GTK+ binaries, and
-where wrapping would gratuitously add a dependency of that output on
-GLib and GTK+.
address@hidden @code{patch-flags} (default: @code{'("-p1")})
+A list of command-line flags that should be passed to the @code{patch}
+command.
address@hidden glib-or-gtk-compile-schemas
-The phase @code{glib-or-gtk-compile-schemas} makes sure that all
address@hidden://developer.gnome.org/gio/stable/glib-compile-schemas.html,
-GSettings schemas} of GLib are compiled. Compilation is performed by the
address@hidden program. It is provided by the package
address@hidden:bin} which is automatically imported by the build system.
-The @code{glib} package providing @command{glib-compile-schemas} can be
-specified with the @code{#:glib} parameter.
address@hidden @code{patch-inputs} (default: @code{#f})
+Input packages or derivations to the patching process. When this is
address@hidden, the usual set of inputs necessary for patching are provided,
+such as address@hidden
+
address@hidden @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.
+
address@hidden @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
address@hidden deftp
-Both phases are executed after the @code{install} phase.
address@hidden defvr
address@hidden {Scheme Variable} guile-build-system
-This build system is for Guile packages that consist exclusively of Scheme
-code and that are so lean that they don't even have a makefile, let alone a
address@hidden script. It compiles Scheme code using @command{guild
-compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
-installs the @file{.scm} and @file{.go} files in the right place. It also
-installs documentation.
address@hidden Build Systems
address@hidden Build Systems
-This build system supports cross-compilation by using the @code{--target}
-option of @command{guild compile}.
address@hidden 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.
-Packages built with @code{guile-build-system} must provide a Guile package in
-their @code{native-inputs} field.
address@hidden defvr
+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.
address@hidden {Scheme Variable} minify-build-system
-This variable is exported by @code{(guix build-system minify)}. It
-implements a minification procedure for simple JavaScript packages.
address@hidden bag (low-level package representation)
+Under the hood, build systems first compile package objects to
address@hidden 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}).
-It adds @code{uglify-js} to the set of inputs and uses it to compress
-all JavaScript files in the @file{src} directory. A different minifier
-package can be specified with the @code{#:uglify-js} parameter, but it
-is expected that the package writes the minified code to the standard
-output.
+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}).
-When the input JavaScript files are not all located in the @file{src}
-directory, the parameter @code{#:javascript-files} can be used to
-specify a list of file names to feed to the minifier.
address@hidden defvr
+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.
address@hidden {Scheme Variable} ocaml-build-system
-This variable is exported by @code{(guix build-system ocaml)}. It implements
-a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
-of choosing the correct set of commands to run for each package. OCaml
-packages can expect many different commands to be run. This build system will
-try some of them.
address@hidden {Scheme Variable} gnu-build-system
address@hidden represents the GNU Build System, and variants
+thereof (@pxref{Configuration, configuration and makefile conventions,,
+standards, GNU Coding Standards}).
-When the package has a @file{setup.ml} file present at the top-level, it will
-run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
address@hidden setup.ml -install}. The build system will assume that this file
-was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
-care of setting the prefix and enabling tests if they are not disabled. You
-can pass configure and build flags with the @code{#:configure-flags} and
address@hidden:build-flags}. The @code{#:test-flags} key can be passed to
change the
-set of flags used to enable tests. The @code{#:use-make?} key can be used to
-bypass this system in the build and install phases.
address@hidden 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},
address@hidden see the @code{(guix build gnu-build-system)}
+modules for more details about the build phases.}:
+
address@hidden @code
address@hidden 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.
+
address@hidden 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
address@hidden/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
address@hidden 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.
+
address@hidden build
+Run @code{make} with the list of flags specified with
address@hidden:make-flags}. If the @code{#:parallel-build?} argument is true
+(the default), build with @code{make -j}.
-When the package has a @file{configure} file, it is assumed that it is a
-hand-made configure script that requires a different argument format than
-in the @code{gnu-build-system}. You can add more flags with the
address@hidden:configure-flags} key.
address@hidden check
+Run @code{make check}, or some other target specified with
address@hidden:test-target}, unless @code{#:tests? #f} is passed. If the
address@hidden:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
-When the package has a @file{Makefile} file (or @code{#:use-make?} is
address@hidden), it will be used and more flags can be passed to the build and
-install phases with the @code{#:make-flags} key.
address@hidden install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
-Finally, some packages do not have these files and use a somewhat standard
-location for its build system. In that case, the build system will run
address@hidden pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
-providing the path to the required findlib module. Additional flags can
-be passed via the @code{#:build-flags} key. Install is taken care of by
address@hidden In this case, the @code{opam} package must
-be added to the @code{native-inputs} field of the package definition.
address@hidden patch-shebangs
+Patch shebangs on the installed executable files.
-Note that most OCaml packages assume they will be installed in the same
-directory as OCaml, which is not what we want in guix. In particular, they
-will install @file{.so} files in their module's directory, which is usually
-fine because it is in the OCaml compiler directory. In guix though, these
-libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
-variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
address@hidden libraries should be installed.
address@hidden defvr
address@hidden 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}).
address@hidden table
address@hidden {Scheme Variable} python-build-system
-This variable is exported by @code{(guix build-system python)}. It
-implements the more or less standard build procedure used by Python
-packages, which consists in running @code{python setup.py build} and
-then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
address@hidden %standard-phases
+The build-side module @code{(guix build gnu-build-system)} defines
address@hidden as the default list of build phases.
address@hidden is a list of symbol/procedure pairs, where the
+procedure implements the actual phase.
-For packages that install stand-alone Python programs under @code{bin/},
-it takes care of wrapping these programs so that their @code{PYTHONPATH}
-environment variable points to all the Python libraries they depend on.
+The list of phases used for a particular package can be changed with the
address@hidden:phases} parameter. For instance, passing:
-Which Python package is used to perform the build can be specified with
-the @code{#:python} parameter. This is a useful way to force a package
-to be built for a specific version of the Python interpreter, which
-might be necessary if the package is only compatible with a single
-interpreter version.
address@hidden
+#:phases (modify-phases %standard-phases (delete 'configure))
address@hidden example
-By default guix calls @code{setup.py} under control of
address@hidden, much like @command{pip} does. Some packages are not
-compatible with setuptools (and pip), thus you can disable this by
-setting the @code{#:use-setuptools} parameter to @code{#f}.
+means that all the phases described above will be used, except the
address@hidden 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
address@hidden inputs} of a package, because package definitions do not
+have to mention them.
@end defvr
address@hidden {Scheme Variable} perl-build-system
-This variable is exported by @code{(guix build-system perl)}. It
-implements the standard build procedure for Perl packages, which either
-consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
-followed by @code{Build} and @code{Build install}; or in running
address@hidden Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
address@hidden and @code{make install}, depending on which of
address@hidden or @code{Makefile.PL} is present in the package
-distribution. Preference is given to the former if both @code{Build.PL}
-and @code{Makefile.PL} exist in the package distribution. This
-preference can be reversed by specifying @code{#t} for the
address@hidden:make-maker?} parameter.
+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.
-The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
-passes flags specified by the @code{#:make-maker-flags} or
address@hidden:module-build-flags} parameter, respectively.
address@hidden {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
address@hidden://ant.apache.org/, Ant build tool}.
-Which Perl package is used can be specified with @code{#:perl}.
address@hidden defvr
+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.
address@hidden {Scheme Variable} r-build-system
-This variable is exported by @code{(guix build-system r)}. It
-implements the build procedure used by @uref{http://r-project.org, R}
-packages, which essentially is little more than running @code{R CMD
-INSTALL --library=/gnu/store/@dots{}} in an environment where
address@hidden contains the paths to all R package inputs. Tests
-are run after installation using the R function
address@hidden::testInstalledPackage}.
address@hidden defvr
+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. In this case the parameter @code{#:source-dir} can be used to
+specify the source sub-directory, defaulting to ``src''.
address@hidden {Scheme Variable} texlive-build-system
-This variable is exported by @code{(guix build-system texlive)}. It is
-used to build TeX packages in batch mode with a specified engine. The
-build system sets the @code{TEXINPUTS} variable to find all TeX source
-files in the inputs.
+The @code{#:main-class} parameter can be used with the minimal ant
+buildfile to specify the main class of the resulting jar. This makes the
+jar file executable. The @code{#:test-include} parameter can be used to
+specify the list of junit tests to run. It defaults to
address@hidden(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
+disable some tests. It defaults to @code{(list "**/Abstract*.java")},
+because abstract classes cannot be run as tests.
-By default it runs @code{luatex} on all files ending on @code{ins}. A
-different engine and format can be specified with the
address@hidden:tex-format} argument. Different build targets can be specified
-with the @code{#:build-targets} argument, which expects a list of file
-names. The build system adds only @code{texlive-bin} and
address@hidden (both from @code{(gnu packages tex}) to the
-inputs. Both can be overridden with the arguments @code{#:texlive-bin}
-and @code{#:texlive-latex-base}, respectively.
+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.
-The @code{#:tex-directory} parameter tells the build system where to
-install the built files under the texmf tree.
@end defvr
address@hidden {Scheme Variable} ruby-build-system
-This variable is exported by @code{(guix build-system ruby)}. It
-implements the RubyGems build procedure used by Ruby packages, which
-involves running @code{gem build} followed by @code{gem install}.
address@hidden {Scheme Variable} android-ndk-build-system
address@hidden Android distribution
address@hidden Android NDK build system
+This variable is exported by @code{(guix build-system android-ndk)}. It
+implements a build procedure for Android NDK (native development kit)
+packages using a Guix-specific build process.
-The @code{source} field of a package that uses this build system
-typically references a gem archive, since this is the format that Ruby
-developers use when releasing their software. The build system unpacks
-the gem archive, potentially patches the source, runs the test suite,
-repackages the gem, and installs it. Additionally, directories and
-tarballs may be referenced to allow building unreleased gems from Git or
-a traditional source release tarball.
+The build system assumes that packages install their public interface
+(header) files to the subdirectory "include" of the "out" output and
+their libraries to the subdirectory "lib" of the "out" output.
-Which Ruby package is used can be specified with the @code{#:ruby}
-parameter. A list of additional flags to be passed to the @command{gem}
-command can be specified with the @code{#:gem-flags} parameter.
address@hidden defvr
+It's also assumed that the union of all the dependencies of a package
+has no conflicting files.
address@hidden {Scheme Variable} waf-build-system
-This variable is exported by @code{(guix build-system waf)}. It
-implements a build procedure around the @code{waf} script. The common
address@hidden, @code{build}, and @code{install}---are
-implemented by passing their names as arguments to the @code{waf}
-script.
+For the time being, cross-compilation is not supported - so right now
+the libraries and header files are assumed to be host tools.
-The @code{waf} script is executed by the Python interpreter. Which
-Python package is used to run the script can be specified with the
address@hidden:python} parameter.
@end defvr
address@hidden {Scheme Variable} scons-build-system
-This variable is exported by @code{(guix build-system scons)}. It
-implements the build procedure used by the SCons software construction
-tool. This build system runs @code{scons} to build the package,
address@hidden test} to run tests, and then @code{scons install} to install
-the package.
address@hidden {Scheme Variable} asdf-build-system/source
address@hidden {Scheme Variable} asdf-build-system/sbcl
address@hidden {Scheme Variable} asdf-build-system/ecl
-Additional flags to be passed to @code{scons} can be specified with the
address@hidden:scons-flags} parameter. The version of Python used to run SCons
-can be specified by selecting the appropriate SCons package with the
address@hidden:scons} parameter.
address@hidden defvr
+These variables, exported by @code{(guix build-system asdf)}, implement
+build procedures for Common Lisp packages using
address@hidden://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
+definition facility for Common Lisp programs and libraries.
address@hidden {Scheme Variable} haskell-build-system
-This variable is exported by @code{(guix build-system haskell)}. It
-implements the Cabal build procedure used by Haskell packages, which
-involves running @code{runhaskell Setup.hs configure
---prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
-Instead of installing the package by running @code{runhaskell Setup.hs
-install}, to avoid trying to register libraries in the read-only
-compiler store directory, the build system uses @code{runhaskell
-Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
-addition, the build system generates the package documentation by
-running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
-is passed. Optional Haddock parameters can be passed with the help of
-the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
-not found, the build system looks for @code{Setup.lhs} instead.
+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.
-Which Haskell compiler is used can be specified with the @code{#:haskell}
-parameter which defaults to @code{ghc}.
address@hidden defvr
+The build system uses naming conventions. For binary packages, the
+package name should be prefixed with the lisp implementation, such as
address@hidden for @code{asdf-build-system/sbcl}.
address@hidden {Scheme Variable} dub-build-system
-This variable is exported by @code{(guix build-system dub)}. It
-implements the Dub build procedure used by D packages, which
-involves running @code{dub build} and @code{dub run}.
-Installation is done by copying the files manually.
+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. Furthermore, if the package
+defines a system for its tests in a separate file, it will be loaded
+before the tests are run if it is specified by the
address@hidden:test-asd-file} parameter. If it is not set, the files
address@hidden<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
+and @code{test.asd} will be tried if they exist.
+
+If for some reason the package must be named in a different way than the
+naming conventions suggest, the @code{#:asd-system-name} parameter can
+be used to specify the name of the system.
-Which D compiler is used can be specified with the @code{#:ldc}
-parameter which defaults to @code{ldc}.
@end defvr
address@hidden {Scheme Variable} emacs-build-system
-This variable is exported by @code{(guix build-system emacs)}. It
-implements an installation procedure similar to the packaging system
-of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
address@hidden {Scheme Variable} cargo-build-system
address@hidden Rust programming language
address@hidden 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
address@hidden://www.rust-lang.org, Rust programming language}.
-It first creates the @address@hidden file, then it
-byte compiles all Emacs Lisp files. Differently from the Emacs
-packaging system, the Info documentation files are moved to the standard
-documentation directory and the @file{dir} file is deleted. Each
-package is installed in its own directory under
address@hidden/emacs/site-lisp/guix.d}.
+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
address@hidden {Scheme Variable} font-build-system
-This variable is exported by @code{(guix build-system font)}. It
-implements an installation procedure for font packages where upstream
-provides pre-compiled TrueType, OpenType, etc.@: font files that merely
-need to be copied into place. It copies font files to standard
-locations in the output directory.
address@hidden defvr
address@hidden Clojure (programming language)
address@hidden simple Clojure build system
address@hidden {Scheme Variable} clojure-build-system
+This variable is exported by @code{(guix build-system clojure)}. It implements
+a simple build procedure for @uref{https://clojure.org/, Clojure} packages
+using plain old @code{compile} in Clojure. Cross-compilation is not supported
+yet.
address@hidden {Scheme Variable} meson-build-system
-This variable is exported by @code{(guix build-system meson)}. It
-implements the build procedure for packages that use
address@hidden://mesonbuild.com, Meson} as their build system.
+It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
+Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
address@hidden:zip} parameters, respectively.
-It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
-of inputs, and they can be changed with the parameters @code{#:meson}
-and @code{#:ninja} if needed. The default Meson is
address@hidden, which is special because it doesn't clear the
address@hidden of binaries and libraries when they are installed.
+A list of source directories, test directories and jar names can be specified
+with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
+parameters, respectively. Compile directory and main class can be specified
+with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
+Other parameters are documented below.
-This build system is an extension of @var{gnu-build-system}, but with the
-following phases changed to some specific for Meson:
+This build system is an extension of @var{ant-build-system}, but with the
+following phases changed:
@table @code
address@hidden configure
-The phase runs @code{meson} with the flags specified in
address@hidden:configure-flags}. The flag @code{--build-type} is always set to
address@hidden unless something else is specified in @code{#:build-type}.
-
@item build
-The phase runs @code{ninja} to build the package in parallel by default, but
-this can be changed with @code{#:parallel-build?}.
+This phase calls @code{compile} in Clojure to compile source files and runs
address@hidden to create jars from both source files and compiled files
+according to the include list and exclude list specified in
address@hidden:aot-include} and @code{#:aot-exclude}, respectively. The
exclude list
+has priority over the include list. These lists consist of symbols
+representing Clojure libraries or the special keyword @code{#:all} representing
+all Clojure libraries found under the source directories. The parameter
address@hidden:omit-source?} decides if source should be included into the jars.
@item check
-The phase runs @code{ninja} with the target specified in @code{#:test-target},
-which is @code{"test"} by default.
+This phase runs tests according to the include list and exclude list specified
+in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
+meanings are analogous to that of @code{#:aot-include} and
address@hidden:aot-exclude}, except that the special keyword @code{#:all} now
+stands for all Clojure libraries found under the test directories. The
+parameter @code{#:tests?} decides if tests should be run.
@item install
-The phase runs @code{ninja install} and can not be changed.
+This phase installs all jars built previously.
@end table
-Apart from that, the build system also adds the following phases:
+Apart from the above, this build system also contains an additional phase:
@table @code
address@hidden fix-runpath
-This phase ensures that all binaries can find the libraries they need.
-It searches for required libraries in subdirectories of the package being
-built, and adds those to @code{RUNPATH} where needed. It also removes
-references to libraries left over from the build phase by
address@hidden, such as test dependencies, that aren't actually
-required for the program to run.
-
address@hidden glib-or-gtk-wrap
-This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
-is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
-
address@hidden glib-or-gtk-compile-schemas
-This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
-is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
address@hidden install-doc
+This phase installs all top-level files with base name matching
address@hidden A different regex can be specified with the
address@hidden:doc-regex} parameter. All files (recursively) inside the
documentation
+directories specified in @code{#:doc-dirs} are installed as well.
@end table
@end defvr
-Lastly, for packages that do not need anything as sophisticated, a
-``trivial'' build system is provided. It is trivial in the sense that
-it provides basically no support: it does not pull any implicit inputs,
-and does not have a notion of build phases.
address@hidden {Scheme Variable} cmake-build-system
+This variable is exported by @code{(guix build-system cmake)}. It
+implements the build procedure for packages using the
address@hidden://www.cmake.org, CMake build tool}.
address@hidden {Scheme Variable} trivial-build-system
-This variable is exported by @code{(guix build-system trivial)}.
+It automatically adds the @code{cmake} package to the set of inputs.
+Which package is used can be specified with the @code{#:cmake}
+parameter.
-This build system requires a @code{#:builder} argument. This argument
-must be a Scheme expression that builds the package output(s)---as
-with @code{build-expression->derivation} (@pxref{Derivations,
address@hidden>derivation}}).
+The @code{#:configure-flags} parameter is taken as a list of flags
+passed to the @command{cmake} command. The @code{#:build-type}
+parameter specifies in abstract terms the flags passed to the compiler;
+it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
+debugging information''), which roughly means that code is compiled with
address@hidden -g}, as is the case for Autoconf-based packages by default.
@end defvr
address@hidden The Store
address@hidden The Store
-
address@hidden store
address@hidden store items
address@hidden store paths
-
-Conceptually, the @dfn{store} is the place where derivations that have
-been built successfully are stored---by default, @file{/gnu/store}.
-Sub-directories in the store are referred to as @dfn{store items} or
-sometimes @dfn{store paths}. The store has an associated database that
-contains information such as the store paths referred to by each store
-path, and the list of @emph{valid} store items---results of successful
-builds. This database resides in @address@hidden/guix/db},
-where @var{localstatedir} is the state directory specified @i{via}
address@hidden at configure time, usually @file{/var}.
address@hidden {Scheme Variable} dune-build-system
+This variable is exported by @code{(guix build-system dune)}. It
+supports builds of packages using @uref{https://dune.build/, Dune}, a build
+tool for the OCaml programming language. It is implemented as an extension
+of the @code{ocaml-build-system} which is described below. As such, the
address@hidden:ocaml} and @code{#:findlib} parameters can be passed to this
build
+system.
-The store is @emph{always} accessed by the daemon on behalf of its clients
-(@pxref{Invoking guix-daemon}). To manipulate the store, clients
-connect to the daemon over a Unix-domain socket, send requests to it,
-and read the result---these are remote procedure calls, or RPCs.
+It automatically adds the @code{dune} package to the set of inputs.
+Which package is used can be specified with the @code{#:dune}
+parameter.
address@hidden Note
-Users must @emph{never} modify files under @file{/gnu/store} directly.
-This would lead to inconsistencies and break the immutability
-assumptions of Guix's functional model (@pxref{Introduction}).
+There is no @code{configure} phase because dune packages typically don't
+need to be configured. The @code{#:build-flags} parameter is taken as a
+list of flags passed to the @code{dune} command during the build.
address@hidden guix gc, @command{guix gc --verify}}, for information on
-how to check the integrity of the store and attempt recovery from
-accidental modifications.
address@hidden quotation
+The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
+command instead of the more recent @code{dune} command while building
+a package. Its default value is @code{#f}.
address@hidden defvr
-The @code{(guix store)} module provides procedures to connect to the
-daemon, and to perform RPCs. These are described below. By default,
address@hidden, and thus all the @command{guix} commands,
-connect to the local daemon or to the URI specified by the
address@hidden environment variable.
address@hidden {Scheme Variable} go-build-system
+This variable is exported by @code{(guix build-system go)}. It
+implements a build procedure for Go packages using the standard
address@hidden://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
+Go build mechanisms}.
address@hidden {Environment Variable} GUIX_DAEMON_SOCKET
-When set, the value of this variable should be a file name or a URI
-designating the daemon endpoint. When it is a file name, it denotes a
-Unix-domain socket to connect to. In addition to file names, the
-supported URI schemes are:
+The user is expected to provide a value for the key @code{#:import-path}
+and, in some cases, @code{#:unpack-path}. The
address@hidden://golang.org/doc/code.html#ImportPaths, import path}
+corresponds to the file system path expected by the package's build
+scripts and any referring packages, and provides a unique way to
+refer to a Go package. It is typically based on a combination of the
+package source code's remote URI and file system hierarchy structure. In
+some cases, you will need to unpack the package's source code to a
+different directory structure than the one indicated by the import path,
+and @code{#:unpack-path} should be used in such cases.
address@hidden @code
address@hidden file
address@hidden unix
-These are for Unix-domain sockets.
address@hidden:///var/guix/daemon-socket/socket} is equivalent to
address@hidden/var/guix/daemon-socket/socket}.
+Packages that provide Go libraries should be installed along with their
+source code. The key @code{#:install-source?}, which defaults to
address@hidden, controls whether or not the source code is installed. It can
+be set to @code{#f} for packages that only provide executable files.
address@hidden defvr
address@hidden guix
address@hidden daemon, remote access
address@hidden remote access to the daemon
address@hidden daemon, cluster setup
address@hidden clusters, daemon setup
-These URIs denote connections over TCP/IP, without encryption nor
-authentication of the remote host. The URI must specify the host name
-and optionally a port number (by default port 44146 is used):
address@hidden {Scheme Variable} glib-or-gtk-build-system
+This variable is exported by @code{(guix build-system glib-or-gtk)}. It
+is intended for use with packages making use of GLib or GTK+.
address@hidden
-guix://master.guix.example.org:1234
address@hidden example
+This build system adds the following two phases to the ones defined by
address@hidden:
-This setup is suitable on local networks, such as clusters, where only
-trusted nodes may connect to the build daemon at
address@hidden
address@hidden @code
address@hidden glib-or-gtk-wrap
+The phase @code{glib-or-gtk-wrap} ensures that programs in
address@hidden/} are able to find GLib ``schemas'' and
address@hidden://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
+modules}. This is achieved by wrapping the programs in launch scripts
+that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
+environment variables.
-The @code{--listen} option of @command{guix-daemon} can be used to
-instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
address@hidden).
+It is possible to exclude specific package outputs from that wrapping
+process by listing their names in the
address@hidden:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
+when an output is known not to contain any GLib or GTK+ binaries, and
+where wrapping would gratuitously add a dependency of that output on
+GLib and GTK+.
address@hidden ssh
address@hidden SSH access to build daemons
-These URIs allow you to connect to a remote daemon over
address@hidden feature requires Guile-SSH (@pxref{Requirements}).}.
-A typical URL might look like this:
address@hidden glib-or-gtk-compile-schemas
+The phase @code{glib-or-gtk-compile-schemas} makes sure that all
address@hidden://developer.gnome.org/gio/stable/glib-compile-schemas.html,
+GSettings schemas} of GLib are compiled. Compilation is performed by the
address@hidden program. It is provided by the package
address@hidden:bin} which is automatically imported by the build system.
+The @code{glib} package providing @command{glib-compile-schemas} can be
+specified with the @code{#:glib} parameter.
address@hidden table
address@hidden
-ssh://charlie@@guix.example.org:22
address@hidden example
+Both phases are executed after the @code{install} phase.
address@hidden defvr
-As for @command{guix copy}, the usual OpenSSH client configuration files
-are honored (@pxref{Invoking guix copy}).
address@hidden table
address@hidden {Scheme Variable} guile-build-system
+This build system is for Guile packages that consist exclusively of Scheme
+code and that are so lean that they don't even have a makefile, let alone a
address@hidden script. It compiles Scheme code using @command{guild
+compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
+installs the @file{.scm} and @file{.go} files in the right place. It also
+installs documentation.
-Additional URI schemes may be supported in the future.
+This build system supports cross-compilation by using the @code{--target}
+option of @command{guild compile}.
address@hidden XXX: Remove this note when the protocol incurs fewer round trips
address@hidden and when (guix derivations) no longer relies on file system
access.
address@hidden Note
-The ability to connect to remote build daemons is considered
-experimental as of @value{VERSION}. Please get in touch with us to
-share any problems or suggestions you may have (@pxref{Contributing}).
address@hidden quotation
+Packages built with @code{guile-build-system} must provide a Guile package in
+their @code{native-inputs} field.
@end defvr
address@hidden {Scheme Procedure} open-connection address@hidden
[#:reserve-space? #t]
-Connect to the daemon over the Unix-domain socket at @var{uri} (a string).
When
address@hidden is true, instruct it to reserve a little bit of
-extra space on the file system so that the garbage collector can still
-operate should the disk become full. Return a server object.
-
address@hidden defaults to @var{%default-socket-path}, which is the normal
-location given the options that were passed to @command{configure}.
address@hidden deffn
address@hidden {Scheme Variable} minify-build-system
+This variable is exported by @code{(guix build-system minify)}. It
+implements a minification procedure for simple JavaScript packages.
address@hidden {Scheme Procedure} close-connection @var{server}
-Close the connection to @var{server}.
address@hidden deffn
+It adds @code{uglify-js} to the set of inputs and uses it to compress
+all JavaScript files in the @file{src} directory. A different minifier
+package can be specified with the @code{#:uglify-js} parameter, but it
+is expected that the package writes the minified code to the standard
+output.
address@hidden {Scheme Variable} current-build-output-port
-This variable is bound to a SRFI-39 parameter, which refers to the port
-where build and error logs sent by the daemon should be written.
+When the input JavaScript files are not all located in the @file{src}
+directory, the parameter @code{#:javascript-files} can be used to
+specify a list of file names to feed to the minifier.
@end defvr
-Procedures that make RPCs all take a server object as their first
-argument.
address@hidden {Scheme Variable} ocaml-build-system
+This variable is exported by @code{(guix build-system ocaml)}. It implements
+a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
+of choosing the correct set of commands to run for each package. OCaml
+packages can expect many different commands to be run. This build system will
+try some of them.
address@hidden {Scheme Procedure} valid-path? @var{server} @var{path}
address@hidden invalid store items
-Return @code{#t} when @var{path} designates a valid store item and
address@hidden otherwise (an invalid item may exist on disk but still be
-invalid, for instance because it is the result of an aborted or failed
-build.)
+When the package has a @file{setup.ml} file present at the top-level, it will
+run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
address@hidden setup.ml -install}. The build system will assume that this file
+was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
+care of setting the prefix and enabling tests if they are not disabled. You
+can pass configure and build flags with the @code{#:configure-flags} and
address@hidden:build-flags}. The @code{#:test-flags} key can be passed to
change the
+set of flags used to enable tests. The @code{#:use-make?} key can be used to
+bypass this system in the build and install phases.
-A @code{&store-protocol-error} condition is raised if @var{path} is not
-prefixed by the store directory (@file{/gnu/store}).
address@hidden deffn
+When the package has a @file{configure} file, it is assumed that it is a
+hand-made configure script that requires a different argument format than
+in the @code{gnu-build-system}. You can add more flags with the
address@hidden:configure-flags} key.
address@hidden {Scheme Procedure} add-text-to-store @var{server} @var{name}
@var{text} address@hidden
-Add @var{text} under file @var{name} in the store, and return its store
-path. @var{references} is the list of store paths referred to by the
-resulting store path.
address@hidden deffn
+When the package has a @file{Makefile} file (or @code{#:use-make?} is
address@hidden), it will be used and more flags can be passed to the build and
+install phases with the @code{#:make-flags} key.
address@hidden {Scheme Procedure} build-derivations @var{server}
@var{derivations}
-Build @var{derivations} (a list of @code{<derivation>} objects or
-derivation paths), and return when the worker is done building them.
-Return @code{#t} on success.
address@hidden deffn
+Finally, some packages do not have these files and use a somewhat standard
+location for its build system. In that case, the build system will run
address@hidden pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
+providing the path to the required findlib module. Additional flags can
+be passed via the @code{#:build-flags} key. Install is taken care of by
address@hidden In this case, the @code{opam} package must
+be added to the @code{native-inputs} field of the package definition.
-Note that the @code{(guix monads)} module provides a monad as well as
-monadic versions of the above procedures, with the goal of making it
-more convenient to work with code that accesses the store (@pxref{The
-Store Monad}).
+Note that most OCaml packages assume they will be installed in the same
+directory as OCaml, which is not what we want in guix. In particular, they
+will install @file{.so} files in their module's directory, which is usually
+fine because it is in the OCaml compiler directory. In guix though, these
+libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
+variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
address@hidden libraries should be installed.
address@hidden defvr
address@hidden FIXME
address@hidden section is currently incomplete.}
address@hidden {Scheme Variable} python-build-system
+This variable is exported by @code{(guix build-system python)}. It
+implements the more or less standard build procedure used by Python
+packages, which consists in running @code{python setup.py build} and
+then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
address@hidden Derivations
address@hidden Derivations
+For packages that install stand-alone Python programs under @code{bin/},
+it takes care of wrapping these programs so that their @code{PYTHONPATH}
+environment variable points to all the Python libraries they depend on.
address@hidden derivations
-Low-level build actions and the environment in which they are performed
-are represented by @dfn{derivations}. A derivation contains the
-following pieces of information:
+Which Python package is used to perform the build can be specified with
+the @code{#:python} parameter. This is a useful way to force a package
+to be built for a specific version of the Python interpreter, which
+might be necessary if the package is only compatible with a single
+interpreter version.
address@hidden
address@hidden
-The outputs of the derivation---derivations produce at least one file or
-directory in the store, but may produce more.
+By default guix calls @code{setup.py} under control of
address@hidden, much like @command{pip} does. Some packages are not
+compatible with setuptools (and pip), thus you can disable this by
+setting the @code{#:use-setuptools} parameter to @code{#f}.
address@hidden defvr
address@hidden
-The inputs of the derivations, which may be other derivations or plain
-files in the store (patches, build scripts, etc.)
address@hidden {Scheme Variable} perl-build-system
+This variable is exported by @code{(guix build-system perl)}. It
+implements the standard build procedure for Perl packages, which either
+consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
+followed by @code{Build} and @code{Build install}; or in running
address@hidden Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
address@hidden and @code{make install}, depending on which of
address@hidden or @code{Makefile.PL} is present in the package
+distribution. Preference is given to the former if both @code{Build.PL}
+and @code{Makefile.PL} exist in the package distribution. This
+preference can be reversed by specifying @code{#t} for the
address@hidden:make-maker?} parameter.
address@hidden
-The system type targeted by the derivation---e.g., @code{x86_64-linux}.
+The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
+passes flags specified by the @code{#:make-maker-flags} or
address@hidden:module-build-flags} parameter, respectively.
address@hidden
-The file name of a build script in the store, along with the arguments
-to be passed.
+Which Perl package is used can be specified with @code{#:perl}.
address@hidden defvr
address@hidden
-A list of environment variables to be defined.
address@hidden {Scheme Variable} r-build-system
+This variable is exported by @code{(guix build-system r)}. It
+implements the build procedure used by @uref{http://r-project.org, R}
+packages, which essentially is little more than running @code{R CMD
+INSTALL --library=/gnu/store/@dots{}} in an environment where
address@hidden contains the paths to all R package inputs. Tests
+are run after installation using the R function
address@hidden::testInstalledPackage}.
address@hidden defvr
address@hidden itemize
address@hidden {Scheme Variable} texlive-build-system
+This variable is exported by @code{(guix build-system texlive)}. It is
+used to build TeX packages in batch mode with a specified engine. The
+build system sets the @code{TEXINPUTS} variable to find all TeX source
+files in the inputs.
address@hidden derivation path
-Derivations allow clients of the daemon to communicate build actions to
-the store. They exist in two forms: as an in-memory representation,
-both on the client- and daemon-side, and as files in the store whose
-name end in @code{.drv}---these files are referred to as @dfn{derivation
-paths}. Derivations paths can be passed to the @code{build-derivations}
-procedure to perform the build actions they prescribe (@pxref{The
-Store}).
+By default it runs @code{luatex} on all files ending on @code{ins}. A
+different engine and format can be specified with the
address@hidden:tex-format} argument. Different build targets can be specified
+with the @code{#:build-targets} argument, which expects a list of file
+names. The build system adds only @code{texlive-bin} and
address@hidden (both from @code{(gnu packages tex}) to the
+inputs. Both can be overridden with the arguments @code{#:texlive-bin}
+and @code{#:texlive-latex-base}, respectively.
address@hidden fixed-output derivations
-Operations such as file downloads and version-control checkouts for
-which the expected content hash is known in advance are modeled as
address@hidden derivations}. Unlike regular derivations, the outputs
-of a fixed-output derivation are independent of its inputs---e.g., a
-source code download produces the same result regardless of the download
-method and tools being used.
+The @code{#:tex-directory} parameter tells the build system where to
+install the built files under the texmf tree.
address@hidden defvr
-The @code{(guix derivations)} module provides a representation of
-derivations as Scheme objects, along with procedures to create and
-otherwise manipulate derivations. The lowest-level primitive to create
-a derivation is the @code{derivation} procedure:
address@hidden {Scheme Variable} ruby-build-system
+This variable is exported by @code{(guix build-system ruby)}. It
+implements the RubyGems build procedure used by Ruby packages, which
+involves running @code{gem build} followed by @code{gem install}.
address@hidden {Scheme Procedure} derivation @var{store} @var{name}
@var{builder} @
- @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
- [#:system (%current-system)] [#:references-graphs #f] @
- [#:allowed-references #f] [#:disallowed-references #f] @
- [#:leaked-env-vars #f] [#:local-build? #f] @
- [#:substitutable? #t] [#:properties '()]
-Build a derivation with the given arguments, and return the resulting
address@hidden<derivation>} object.
+The @code{source} field of a package that uses this build system
+typically references a gem archive, since this is the format that Ruby
+developers use when releasing their software. The build system unpacks
+the gem archive, potentially patches the source, runs the test suite,
+repackages the gem, and installs it. Additionally, directories and
+tarballs may be referenced to allow building unreleased gems from Git or
+a traditional source release tarball.
+
+Which Ruby package is used can be specified with the @code{#:ruby}
+parameter. A list of additional flags to be passed to the @command{gem}
+command can be specified with the @code{#:gem-flags} parameter.
address@hidden defvr
+
address@hidden {Scheme Variable} waf-build-system
+This variable is exported by @code{(guix build-system waf)}. It
+implements a build procedure around the @code{waf} script. The common
address@hidden, @code{build}, and @code{install}---are
+implemented by passing their names as arguments to the @code{waf}
+script.
+
+The @code{waf} script is executed by the Python interpreter. Which
+Python package is used to run the script can be specified with the
address@hidden:python} parameter.
address@hidden defvr
-When @var{hash} and @var{hash-algo} are given, a
address@hidden derivation} is created---i.e., one whose result is
-known in advance, such as a file download. If, in addition,
address@hidden is true, then that fixed output may be an executable
-file or a directory and @var{hash} must be the hash of an archive
-containing this output.
address@hidden {Scheme Variable} scons-build-system
+This variable is exported by @code{(guix build-system scons)}. It
+implements the build procedure used by the SCons software construction
+tool. This build system runs @code{scons} to build the package,
address@hidden test} to run tests, and then @code{scons install} to install
+the package.
-When @var{references-graphs} is true, it must be a list of file
-name/store path pairs. In that case, the reference graph of each store
-path is exported in the build environment in the corresponding file, in
-a simple text format.
+Additional flags to be passed to @code{scons} can be specified with the
address@hidden:scons-flags} parameter. The version of Python used to run SCons
+can be specified by selecting the appropriate SCons package with the
address@hidden:scons} parameter.
address@hidden defvr
-When @var{allowed-references} is true, it must be a list of store items
-or outputs that the derivation's output may refer to. Likewise,
address@hidden, if true, must be a list of things the
-outputs may @emph{not} refer to.
address@hidden {Scheme Variable} haskell-build-system
+This variable is exported by @code{(guix build-system haskell)}. It
+implements the Cabal build procedure used by Haskell packages, which
+involves running @code{runhaskell Setup.hs configure
+--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
+Instead of installing the package by running @code{runhaskell Setup.hs
+install}, to avoid trying to register libraries in the read-only
+compiler store directory, the build system uses @code{runhaskell
+Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
+addition, the build system generates the package documentation by
+running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
+is passed. Optional Haddock parameters can be passed with the help of
+the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
+not found, the build system looks for @code{Setup.lhs} instead.
-When @var{leaked-env-vars} is true, it must be a list of strings
-denoting environment variables that are allowed to ``leak'' from the
-daemon's environment to the build environment. This is only applicable
-to fixed-output derivations---i.e., when @var{hash} is true. The main
-use is to allow variables such as @code{http_proxy} to be passed to
-derivations that download files.
+Which Haskell compiler is used can be specified with the @code{#:haskell}
+parameter which defaults to @code{ghc}.
address@hidden defvr
-When @var{local-build?} is true, declare that the derivation is not a
-good candidate for offloading and should rather be built locally
-(@pxref{Daemon Offload Setup}). This is the case for small derivations
-where the costs of data transfers would outweigh the benefits.
address@hidden {Scheme Variable} dub-build-system
+This variable is exported by @code{(guix build-system dub)}. It
+implements the Dub build procedure used by D packages, which
+involves running @code{dub build} and @code{dub run}.
+Installation is done by copying the files manually.
-When @var{substitutable?} is false, declare that substitutes of the
-derivation's output should not be used (@pxref{Substitutes}). This is
-useful, for instance, when building packages that capture details of the
-host CPU instruction set.
+Which D compiler is used can be specified with the @code{#:ldc}
+parameter which defaults to @code{ldc}.
address@hidden defvr
address@hidden must be an association list describing ``properties'' of the
-derivation. It is kept as-is, uninterpreted, in the derivation.
address@hidden deffn
address@hidden {Scheme Variable} emacs-build-system
+This variable is exported by @code{(guix build-system emacs)}. It
+implements an installation procedure similar to the packaging system
+of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
address@hidden
-Here's an example with a shell script as its builder, assuming
address@hidden is an open connection to the daemon, and @var{bash} points
-to a Bash executable in the store:
+It first creates the @address@hidden file, then it
+byte compiles all Emacs Lisp files. Differently from the Emacs
+packaging system, the Info documentation files are moved to the standard
+documentation directory and the @file{dir} file is deleted. Each
+package is installed in its own directory under
address@hidden/emacs/site-lisp/guix.d}.
address@hidden defvr
address@hidden
-(use-modules (guix utils)
- (guix store)
- (guix derivations))
address@hidden {Scheme Variable} font-build-system
+This variable is exported by @code{(guix build-system font)}. It
+implements an installation procedure for font packages where upstream
+provides pre-compiled TrueType, OpenType, etc.@: font files that merely
+need to be copied into place. It copies font files to standard
+locations in the output directory.
address@hidden defvr
-(let ((builder ; add the Bash script to the store
- (add-text-to-store store "my-builder.sh"
- "echo hello world > $out\n" '())))
- (derivation store "foo"
- bash `("-e" ,builder)
- #:inputs `((,bash) (,builder))
- #:env-vars '(("HOME" . "/homeless"))))
address@hidden #<derivation /gnu/store/@dots{}-foo.drv =>
/gnu/store/@dots{}-foo>
address@hidden lisp
address@hidden {Scheme Variable} meson-build-system
+This variable is exported by @code{(guix build-system meson)}. It
+implements the build procedure for packages that use
address@hidden://mesonbuild.com, Meson} as their build system.
-As can be guessed, this primitive is cumbersome to use directly. A
-better approach is to write build scripts in Scheme, of course! The
-best course of action for that is to write the build code as a
-``G-expression'', and to pass it to @code{gexp->derivation}. For more
-information, @pxref{G-Expressions}.
+It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
+of inputs, and they can be changed with the parameters @code{#:meson}
+and @code{#:ninja} if needed. The default Meson is
address@hidden, which is special because it doesn't clear the
address@hidden of binaries and libraries when they are installed.
-Once upon a time, @code{gexp->derivation} did not exist and constructing
-derivations with build code written in Scheme was achieved with
address@hidden>derivation}, documented below. This procedure
-is now deprecated in favor of the much nicer @code{gexp->derivation}.
+This build system is an extension of @var{gnu-build-system}, but with the
+following phases changed to some specific for Meson:
address@hidden {Scheme Procedure} build-expression->derivation @var{store} @
- @var{name} @var{exp} @
- [#:system (%current-system)] [#:inputs '()] @
- [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
-Return a derivation that executes Scheme expression @var{exp} as a
-builder for derivation @var{name}. @var{inputs} must be a list of
address@hidden(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
address@hidden"out"} is assumed. @var{modules} is a list of names of Guile
-modules from the current search path to be copied in the store,
-compiled, and made available in the load path during the execution of
address@hidden, @code{((guix build utils) (guix build
-gnu-build-system))}.
address@hidden @code
address@hidden is evaluated in an environment where @code{%outputs} is bound
-to a list of output/path pairs, and where @code{%build-inputs} is bound
-to a list of string/output-path pairs made from @var{inputs}.
-Optionally, @var{env-vars} is a list of string pairs specifying the name
-and value of environment variables visible to the builder. The builder
-terminates by passing the result of @var{exp} to @code{exit}; thus, when
address@hidden returns @code{#f}, the build is considered to have failed.
address@hidden configure
+The phase runs @code{meson} with the flags specified in
address@hidden:configure-flags}. The flag @code{--build-type} is always set to
address@hidden unless something else is specified in @code{#:build-type}.
address@hidden is built using @var{guile-for-build} (a derivation). When
address@hidden is omitted or is @code{#f}, the value of the
address@hidden fluid is used instead.
address@hidden build
+The phase runs @code{ninja} to build the package in parallel by default, but
+this can be changed with @code{#:parallel-build?}.
-See the @code{derivation} procedure for the meaning of
address@hidden, @var{allowed-references},
address@hidden, @var{local-build?}, and
address@hidden
address@hidden deffn
address@hidden check
+The phase runs @code{ninja} with the target specified in @code{#:test-target},
+which is @code{"test"} by default.
address@hidden
-Here's an example of a single-output derivation that creates a directory
-containing one file:
address@hidden install
+The phase runs @code{ninja install} and can not be changed.
address@hidden table
address@hidden
-(let ((builder '(let ((out (assoc-ref %outputs "out")))
- (mkdir out) ; create /gnu/store/@dots{}-goo
- (call-with-output-file (string-append out "/test")
- (lambda (p)
- (display '(hello guix) p))))))
- (build-expression->derivation store "goo" builder))
+Apart from that, the build system also adds the following phases:
address@hidden #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
address@hidden lisp
address@hidden @code
address@hidden fix-runpath
+This phase ensures that all binaries can find the libraries they need.
+It searches for required libraries in subdirectories of the package being
+built, and adds those to @code{RUNPATH} where needed. It also removes
+references to libraries left over from the build phase by
address@hidden, such as test dependencies, that aren't actually
+required for the program to run.
address@hidden The Store Monad
address@hidden The Store Monad
address@hidden glib-or-gtk-wrap
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
address@hidden monad
address@hidden glib-or-gtk-compile-schemas
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
address@hidden table
address@hidden defvr
-The procedures that operate on the store described in the previous
-sections all take an open connection to the build daemon as their first
-argument. Although the underlying model is functional, they either have
-side effects or depend on the current state of the store.
+Lastly, for packages that do not need anything as sophisticated, a
+``trivial'' build system is provided. It is trivial in the sense that
+it provides basically no support: it does not pull any implicit inputs,
+and does not have a notion of build phases.
-The former is inconvenient: the connection to the build daemon has to be
-carried around in all those functions, making it impossible to compose
-functions that do not take that parameter with functions that do. The
-latter can be problematic: since store operations have side effects
-and/or depend on external state, they have to be properly sequenced.
address@hidden {Scheme Variable} trivial-build-system
+This variable is exported by @code{(guix build-system trivial)}.
address@hidden monadic values
address@hidden monadic functions
-This is where the @code{(guix monads)} module comes in. This module
-provides a framework for working with @dfn{monads}, and a particularly
-useful monad for our uses, the @dfn{store monad}. Monads are a
-construct that allows two things: associating ``context'' with values
-(in our case, the context is the store), and building sequences of
-computations (here computations include accesses to the store). Values
-in a monad---values that carry this additional context---are called
address@hidden values}; procedures that return such values are called
address@hidden procedures}.
+This build system requires a @code{#:builder} argument. This argument
+must be a Scheme expression that builds the package output(s)---as
+with @code{build-expression->derivation} (@pxref{Derivations,
address@hidden>derivation}}).
address@hidden defvr
-Consider this ``normal'' procedure:
address@hidden The Store
address@hidden The Store
address@hidden
-(define (sh-symlink store)
- ;; Return a derivation that symlinks the 'bash' executable.
- (let* ((drv (package-derivation store bash))
- (out (derivation->output-path drv))
- (sh (string-append out "/bin/bash")))
- (build-expression->derivation store "sh"
- `(symlink ,sh %output))))
address@hidden example
address@hidden store
address@hidden store items
address@hidden store paths
+
+Conceptually, the @dfn{store} is the place where derivations that have
+been built successfully are stored---by default, @file{/gnu/store}.
+Sub-directories in the store are referred to as @dfn{store items} or
+sometimes @dfn{store paths}. The store has an associated database that
+contains information such as the store paths referred to by each store
+path, and the list of @emph{valid} store items---results of successful
+builds. This database resides in @address@hidden/guix/db},
+where @var{localstatedir} is the state directory specified @i{via}
address@hidden at configure time, usually @file{/var}.
-Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
-as a monadic function:
+The store is @emph{always} accessed by the daemon on behalf of its clients
+(@pxref{Invoking guix-daemon}). To manipulate the store, clients
+connect to the daemon over a Unix-domain socket, send requests to it,
+and read the result---these are remote procedure calls, or RPCs.
address@hidden
-(define (sh-symlink)
- ;; Same, but return a monadic value.
- (mlet %store-monad ((drv (package->derivation bash)))
- (gexp->derivation "sh"
- #~(symlink (string-append #$drv "/bin/bash")
- #$output))))
address@hidden example
address@hidden Note
+Users must @emph{never} modify files under @file{/gnu/store} directly.
+This would lead to inconsistencies and break the immutability
+assumptions of Guix's functional model (@pxref{Introduction}).
-There are several things to note in the second version: the @code{store}
-parameter is now implicit and is ``threaded'' in the calls to the
address@hidden>derivation} and @code{gexp->derivation} monadic
-procedures, and the monadic value returned by @code{package->derivation}
-is @dfn{bound} using @code{mlet} instead of plain @code{let}.
address@hidden guix gc, @command{guix gc --verify}}, for information on
+how to check the integrity of the store and attempt recovery from
+accidental modifications.
address@hidden quotation
-As it turns out, the call to @code{package->derivation} can even be
-omitted since it will take place implicitly, as we will see later
-(@pxref{G-Expressions}):
+The @code{(guix store)} module provides procedures to connect to the
+daemon, and to perform RPCs. These are described below. By default,
address@hidden, and thus all the @command{guix} commands,
+connect to the local daemon or to the URI specified by the
address@hidden environment variable.
address@hidden
-(define (sh-symlink)
- (gexp->derivation "sh"
- #~(symlink (string-append #$bash "/bin/bash")
- #$output)))
address@hidden example
address@hidden {Environment Variable} GUIX_DAEMON_SOCKET
+When set, the value of this variable should be a file name or a URI
+designating the daemon endpoint. When it is a file name, it denotes a
+Unix-domain socket to connect to. In addition to file names, the
+supported URI schemes are:
address@hidden See
address@hidden
<https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
address@hidden for the funny quote.
-Calling the monadic @code{sh-symlink} has no effect. As someone once
-said, ``you exit a monad like you exit a building on fire: by running''.
-So, to exit the monad and get the desired effect, one must use
address@hidden:
address@hidden @code
address@hidden file
address@hidden unix
+These are for Unix-domain sockets.
address@hidden:///var/guix/daemon-socket/socket} is equivalent to
address@hidden/var/guix/daemon-socket/socket}.
+
address@hidden guix
address@hidden daemon, remote access
address@hidden remote access to the daemon
address@hidden daemon, cluster setup
address@hidden clusters, daemon setup
+These URIs denote connections over TCP/IP, without encryption nor
+authentication of the remote host. The URI must specify the host name
+and optionally a port number (by default port 44146 is used):
@example
-(run-with-store (open-connection) (sh-symlink))
address@hidden /gnu/store/...-sh-symlink
+guix://master.guix.example.org:1234
@end example
-Note that the @code{(guix monad-repl)} module extends the Guile REPL with
-new ``meta-commands'' to make it easier to deal with monadic procedures:
address@hidden, and @code{enter-store-monad}. The former is used
-to ``run'' a single monadic value through the store:
+This setup is suitable on local networks, such as clusters, where only
+trusted nodes may connect to the build daemon at
address@hidden
address@hidden
-scheme@@(guile-user)> ,run-in-store (package->derivation hello)
-$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
address@hidden example
+The @code{--listen} option of @command{guix-daemon} can be used to
+instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
address@hidden).
-The latter enters a recursive REPL, where all the return values are
-automatically run through the store:
address@hidden ssh
address@hidden SSH access to build daemons
+These URIs allow you to connect to a remote daemon over
address@hidden feature requires Guile-SSH (@pxref{Requirements}).}.
+A typical URL might look like this:
@example
-scheme@@(guile-user)> ,enter-store-monad
-store-monad@@(guile-user) [1]> (package->derivation hello)
-$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
-store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
-$3 = "/gnu/store/@dots{}-foo"
-store-monad@@(guile-user) [1]> ,q
-scheme@@(guile-user)>
+ssh://charlie@@guix.example.org:22
@end example
address@hidden
-Note that non-monadic values cannot be returned in the
address@hidden REPL.
-
-The main syntactic forms to deal with monads in general are provided by
-the @code{(guix monads)} module and are described below.
+As for @command{guix copy}, the usual OpenSSH client configuration files
+are honored (@pxref{Invoking guix copy}).
address@hidden table
address@hidden {Scheme Syntax} with-monad @var{monad} @var{body} ...
-Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
-in @var{monad}.
address@hidden deffn
+Additional URI schemes may be supported in the future.
address@hidden {Scheme Syntax} return @var{val}
-Return a monadic value that encapsulates @var{val}.
address@hidden deffn
address@hidden XXX: Remove this note when the protocol incurs fewer round trips
address@hidden and when (guix derivations) no longer relies on file system
access.
address@hidden Note
+The ability to connect to remote build daemons is considered
+experimental as of @value{VERSION}. Please get in touch with us to
+share any problems or suggestions you may have (@pxref{Contributing}).
address@hidden quotation
address@hidden defvr
address@hidden {Scheme Syntax} >>= @var{mval} @var{mproc} ...
address@hidden monadic value @var{mval}, passing its ``contents'' to monadic
-procedures @address@hidden@footnote{This operation is commonly
-referred to as ``bind'', but that name denotes an unrelated procedure in
-Guile. Thus we use this somewhat cryptic symbol inherited from the
-Haskell language.}. There can be one @var{mproc} or several of them, as
-in this example:
address@hidden {Scheme Procedure} open-connection address@hidden
[#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{uri} (a string).
When
address@hidden is true, instruct it to reserve a little bit of
+extra space on the file system so that the garbage collector can still
+operate should the disk become full. Return a server object.
address@hidden
-(run-with-state
- (with-monad %state-monad
- (>>= (return 1)
- (lambda (x) (return (+ 1 x)))
- (lambda (x) (return (* 2 x)))))
- 'some-state)
address@hidden defaults to @var{%default-socket-path}, which is the normal
+location given the options that were passed to @command{configure}.
address@hidden deffn
address@hidden 4
address@hidden some-state
address@hidden example
address@hidden {Scheme Procedure} close-connection @var{server}
+Close the connection to @var{server}.
@end deffn
address@hidden {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
address@hidden {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
-Bind the variables @var{var} to the monadic values @var{mval} in
address@hidden, which is a sequence of expressions. As with the bind
-operator, this can be thought of as ``unpacking'' the raw, non-monadic
-value ``contained'' in @var{mval} and making @var{var} refer to that
-raw, non-monadic value within the scope of the @var{body}. The form
-(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
address@hidden, as per @code{let}. The binding operations occur in sequence
-from left to right. The last expression of @var{body} must be a monadic
-expression, and its result will become the result of the @code{mlet} or
address@hidden when run in the @var{monad}.
address@hidden {Scheme Variable} current-build-output-port
+This variable is bound to a SRFI-39 parameter, which refers to the port
+where build and error logs sent by the daemon should be written.
address@hidden defvr
address@hidden is to @code{mlet} what @code{let*} is to @code{let}
-(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
address@hidden deffn
+Procedures that make RPCs all take a server object as their first
+argument.
address@hidden {Scheme System} mbegin @var{monad} @var{mexp} ...
-Bind @var{mexp} and the following monadic expressions in sequence,
-returning the result of the last expression. Every expression in the
-sequence must be a monadic expression.
address@hidden {Scheme Procedure} valid-path? @var{server} @var{path}
address@hidden invalid store items
+Return @code{#t} when @var{path} designates a valid store item and
address@hidden otherwise (an invalid item may exist on disk but still be
+invalid, for instance because it is the result of an aborted or failed
+build.)
-This is akin to @code{mlet}, except that the return values of the
-monadic expressions are ignored. In that sense, it is analogous to
address@hidden, but applied to monadic expressions.
+A @code{&store-protocol-error} condition is raised if @var{path} is not
+prefixed by the store directory (@file{/gnu/store}).
@end deffn
address@hidden {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
-When @var{condition} is true, evaluate the sequence of monadic
-expressions @address@hidden as in an @code{mbegin}. When
address@hidden is false, return @code{*unspecified*} in the current
-monad. Every expression in the sequence must be a monadic expression.
address@hidden {Scheme Procedure} add-text-to-store @var{server} @var{name}
@var{text} address@hidden
+Add @var{text} under file @var{name} in the store, and return its store
+path. @var{references} is the list of store paths referred to by the
+resulting store path.
@end deffn
address@hidden {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*}
...
-When @var{condition} is false, evaluate the sequence of monadic
-expressions @address@hidden as in an @code{mbegin}. When
address@hidden is true, return @code{*unspecified*} in the current
-monad. Every expression in the sequence must be a monadic expression.
address@hidden {Scheme Procedure} build-derivations @var{server}
@var{derivations}
+Build @var{derivations} (a list of @code{<derivation>} objects or
+derivation paths), and return when the worker is done building them.
+Return @code{#t} on success.
@end deffn
address@hidden state monad
-The @code{(guix monads)} module provides the @dfn{state monad}, which
-allows an additional value---the state---to be @emph{threaded} through
-monadic procedure calls.
-
address@hidden {Scheme Variable} %state-monad
-The state monad. Procedures in the state monad can access and change
-the state that is threaded.
-
-Consider the example below. The @code{square} procedure returns a value
-in the state monad. It returns the square of its argument, but also
-increments the current state value:
-
address@hidden
-(define (square x)
- (mlet %state-monad ((count (current-state)))
- (mbegin %state-monad
- (set-current-state (+ 1 count))
- (return (* x x)))))
+Note that the @code{(guix monads)} module provides a monad as well as
+monadic versions of the above procedures, with the goal of making it
+more convenient to work with code that accesses the store (@pxref{The
+Store Monad}).
-(run-with-state (sequence %state-monad (map square (iota 3))) 0)
address@hidden (0 1 4)
address@hidden 3
address@hidden example
address@hidden FIXME
address@hidden section is currently incomplete.}
-When ``run'' through @var{%state-monad}, we obtain that additional state
-value, which is the number of @code{square} calls.
address@hidden defvr
address@hidden Derivations
address@hidden Derivations
address@hidden {Monadic Procedure} current-state
-Return the current state as a monadic value.
address@hidden deffn
address@hidden derivations
+Low-level build actions and the environment in which they are performed
+are represented by @dfn{derivations}. A derivation contains the
+following pieces of information:
address@hidden {Monadic Procedure} set-current-state @var{value}
-Set the current state to @var{value} and return the previous state as a
-monadic value.
address@hidden deffn
address@hidden
address@hidden
+The outputs of the derivation---derivations produce at least one file or
+directory in the store, but may produce more.
address@hidden {Monadic Procedure} state-push @var{value}
-Push @var{value} to the current state, which is assumed to be a list,
-and return the previous state as a monadic value.
address@hidden deffn
address@hidden
+The inputs of the derivations, which may be other derivations or plain
+files in the store (patches, build scripts, etc.)
address@hidden {Monadic Procedure} state-pop
-Pop a value from the current state and return it as a monadic value.
-The state is assumed to be a list.
address@hidden deffn
address@hidden
+The system type targeted by the derivation---e.g., @code{x86_64-linux}.
address@hidden {Scheme Procedure} run-with-state @var{mval} address@hidden
-Run monadic value @var{mval} starting with @var{state} as the initial
-state. Return two values: the resulting value, and the resulting state.
address@hidden deffn
address@hidden
+The file name of a build script in the store, along with the arguments
+to be passed.
-The main interface to the store monad, provided by the @code{(guix
-store)} module, is as follows.
address@hidden
+A list of environment variables to be defined.
address@hidden {Scheme Variable} %store-monad
-The store monad---an alias for @var{%state-monad}.
address@hidden itemize
-Values in the store monad encapsulate accesses to the store. When its
-effect is needed, a value of the store monad must be ``evaluated'' by
-passing it to the @code{run-with-store} procedure (see below.)
address@hidden defvr
address@hidden derivation path
+Derivations allow clients of the daemon to communicate build actions to
+the store. They exist in two forms: as an in-memory representation,
+both on the client- and daemon-side, and as files in the store whose
+name end in @code{.drv}---these files are referred to as @dfn{derivation
+paths}. Derivations paths can be passed to the @code{build-derivations}
+procedure to perform the build actions they prescribe (@pxref{The
+Store}).
address@hidden {Scheme Procedure} run-with-store @var{store} @var{mval}
[#:guile-for-build] [#:system (%current-system)]
-Run @var{mval}, a monadic value in the store monad, in @var{store}, an
-open store connection.
address@hidden deffn
address@hidden fixed-output derivations
+Operations such as file downloads and version-control checkouts for
+which the expected content hash is known in advance are modeled as
address@hidden derivations}. Unlike regular derivations, the outputs
+of a fixed-output derivation are independent of its inputs---e.g., a
+source code download produces the same result regardless of the download
+method and tools being used.
address@hidden {Monadic Procedure} text-file @var{name} @var{text}
address@hidden
-Return as a monadic value the absolute file name in the store of the file
-containing @var{text}, a string. @var{references} is a list of store items
that the
-resulting text file refers to; it defaults to the empty list.
address@hidden deffn
+The @code{(guix derivations)} module provides a representation of
+derivations as Scheme objects, along with procedures to create and
+otherwise manipulate derivations. The lowest-level primitive to create
+a derivation is the @code{derivation} procedure:
address@hidden {Monadic Procedure} binary-file @var{name} @var{data}
address@hidden
-Return as a monadic value the absolute file name in the store of the file
-containing @var{data}, a bytevector. @var{references} is a list of store
-items that the resulting binary file refers to; it defaults to the empty list.
address@hidden deffn
address@hidden {Scheme Procedure} derivation @var{store} @var{name}
@var{builder} @
+ @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
+ [#:system (%current-system)] [#:references-graphs #f] @
+ [#:allowed-references #f] [#:disallowed-references #f] @
+ [#:leaked-env-vars #f] [#:local-build? #f] @
+ [#:substitutable? #t] [#:properties '()]
+Build a derivation with the given arguments, and return the resulting
address@hidden<derivation>} object.
address@hidden {Monadic Procedure} interned-file @var{file} address@hidden @
- [#:recursive? #t] [#:select? (const #t)]
-Return the name of @var{file} once interned in the store. Use
address@hidden as its store name, or the basename of @var{file} if
address@hidden is omitted.
+When @var{hash} and @var{hash-algo} are given, a
address@hidden derivation} is created---i.e., one whose result is
+known in advance, such as a file download. If, in addition,
address@hidden is true, then that fixed output may be an executable
+file or a directory and @var{hash} must be the hash of an archive
+containing this output.
-When @var{recursive?} is true, the contents of @var{file} are added
-recursively; if @var{file} designates a flat file and @var{recursive?}
-is true, its contents are added, and its permission bits are kept.
+When @var{references-graphs} is true, it must be a list of file
+name/store path pairs. In that case, the reference graph of each store
+path is exported in the build environment in the corresponding file, in
+a simple text format.
-When @var{recursive?} is true, call @code{(@var{select?} @var{file}
address@hidden)} for each directory entry, where @var{file} is the entry's
-absolute file name and @var{stat} is the result of @code{lstat}; exclude
-entries for which @var{select?} does not return true.
+When @var{allowed-references} is true, it must be a list of store items
+or outputs that the derivation's output may refer to. Likewise,
address@hidden, if true, must be a list of things the
+outputs may @emph{not} refer to.
-The example below adds a file to the store, under two different names:
+When @var{leaked-env-vars} is true, it must be a list of strings
+denoting environment variables that are allowed to ``leak'' from the
+daemon's environment to the build environment. This is only applicable
+to fixed-output derivations---i.e., when @var{hash} is true. The main
+use is to allow variables such as @code{http_proxy} to be passed to
+derivations that download files.
address@hidden
-(run-with-store (open-connection)
- (mlet %store-monad ((a (interned-file "README"))
- (b (interned-file "README" "LEGU-MIN")))
- (return (list a b))))
+When @var{local-build?} is true, declare that the derivation is not a
+good candidate for offloading and should rather be built locally
+(@pxref{Daemon Offload Setup}). This is the case for small derivations
+where the costs of data transfers would outweigh the benefits.
address@hidden ("/gnu/store/address@hidden" "/gnu/store/address@hidden")
address@hidden example
+When @var{substitutable?} is false, declare that substitutes of the
+derivation's output should not be used (@pxref{Substitutes}). This is
+useful, for instance, when building packages that capture details of the
+host CPU instruction set.
address@hidden must be an association list describing ``properties'' of the
+derivation. It is kept as-is, uninterpreted, in the derivation.
@end deffn
-The @code{(guix packages)} module exports the following package-related
-monadic procedures:
address@hidden
+Here's an example with a shell script as its builder, assuming
address@hidden is an open connection to the daemon, and @var{bash} points
+to a Bash executable in the store:
address@hidden {Monadic Procedure} package-file @var{package} address@hidden @
- [#:system (%current-system)] [#:target #f] @
- [#:output "out"]
-Return as a monadic
-value in the absolute file name of @var{file} within the @var{output}
-directory of @var{package}. When @var{file} is omitted, return the name
-of the @var{output} directory of @var{package}. When @var{target} is
-true, use it as a cross-compilation target triplet.
address@hidden deffn
address@hidden
+(use-modules (guix utils)
+ (guix store)
+ (guix derivations))
address@hidden {Monadic Procedure} package->derivation @var{package}
address@hidden
address@hidden {Monadic Procedure} package->cross-derivation @var{package} @
- @var{target} address@hidden
-Monadic version of @code{package-derivation} and
address@hidden (@pxref{Defining Packages}).
address@hidden deffn
+(let ((builder ; add the Bash script to the store
+ (add-text-to-store store "my-builder.sh"
+ "echo hello world > $out\n" '())))
+ (derivation store "foo"
+ bash `("-e" ,builder)
+ #:inputs `((,bash) (,builder))
+ #:env-vars '(("HOME" . "/homeless"))))
address@hidden #<derivation /gnu/store/@dots{}-foo.drv =>
/gnu/store/@dots{}-foo>
address@hidden lisp
+As can be guessed, this primitive is cumbersome to use directly. A
+better approach is to write build scripts in Scheme, of course! The
+best course of action for that is to write the build code as a
+``G-expression'', and to pass it to @code{gexp->derivation}. For more
+information, @pxref{G-Expressions}.
address@hidden G-Expressions
address@hidden G-Expressions
+Once upon a time, @code{gexp->derivation} did not exist and constructing
+derivations with build code written in Scheme was achieved with
address@hidden>derivation}, documented below. This procedure
+is now deprecated in favor of the much nicer @code{gexp->derivation}.
address@hidden G-expression
address@hidden build code quoting
-So we have ``derivations'', which represent a sequence of build actions
-to be performed to produce an item in the store (@pxref{Derivations}).
-These build actions are performed when asking the daemon to actually
-build the derivations; they are run by the daemon in a container
-(@pxref{Invoking guix-daemon}).
address@hidden {Scheme Procedure} build-expression->derivation @var{store} @
+ @var{name} @var{exp} @
+ [#:system (%current-system)] [#:inputs '()] @
+ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:disallowed-references #f] @
+ [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
+Return a derivation that executes Scheme expression @var{exp} as a
+builder for derivation @var{name}. @var{inputs} must be a list of
address@hidden(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
address@hidden"out"} is assumed. @var{modules} is a list of names of Guile
+modules from the current search path to be copied in the store,
+compiled, and made available in the load path during the execution of
address@hidden, @code{((guix build utils) (guix build
+gnu-build-system))}.
address@hidden strata of code
-It should come as no surprise that we like to write these build actions
-in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
address@hidden term @dfn{stratum} in this context was coined by
-Manuel Serrano et al.@: in the context of their work on Hop. Oleg
-Kiselyov, who has written insightful
address@hidden://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
-on this topic}, refers to this kind of code generation as
address@hidden: the ``host code''---code that defines packages, talks
-to the daemon, etc.---and the ``build code''---code that actually
-performs build actions, such as making directories, invoking
address@hidden, etc.
address@hidden is evaluated in an environment where @code{%outputs} is bound
+to a list of output/path pairs, and where @code{%build-inputs} is bound
+to a list of string/output-path pairs made from @var{inputs}.
+Optionally, @var{env-vars} is a list of string pairs specifying the name
+and value of environment variables visible to the builder. The builder
+terminates by passing the result of @var{exp} to @code{exit}; thus, when
address@hidden returns @code{#f}, the build is considered to have failed.
-To describe a derivation and its build actions, one typically needs to
-embed build code inside host code. It boils down to manipulating build
-code as data, and the homoiconicity of Scheme---code has a direct
-representation as data---comes in handy for that. But we need more than
-the normal @code{quasiquote} mechanism in Scheme to construct build
-expressions.
address@hidden is built using @var{guile-for-build} (a derivation). When
address@hidden is omitted or is @code{#f}, the value of the
address@hidden fluid is used instead.
-The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
-S-expressions adapted to build expressions. G-expressions, or
address@hidden, consist essentially of three syntactic forms: @code{gexp},
address@hidden, and @code{ungexp-splicing} (or simply: @code{#~},
address@hidden, and @code{#$@@}), which are comparable to
address@hidden, @code{unquote}, and @code{unquote-splicing},
-respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
-GNU Guile Reference Manual}). However, there are major differences:
+See the @code{derivation} procedure for the meaning of
address@hidden, @var{allowed-references},
address@hidden, @var{local-build?}, and
address@hidden
address@hidden deffn
address@hidden
address@hidden
-Gexps are meant to be written to a file and run or manipulated by other
-processes.
address@hidden
+Here's an example of a single-output derivation that creates a directory
+containing one file:
address@hidden
-When a high-level object such as a package or derivation is unquoted
-inside a gexp, the result is as if its output file name had been
-introduced.
address@hidden
+(let ((builder '(let ((out (assoc-ref %outputs "out")))
+ (mkdir out) ; create /gnu/store/@dots{}-goo
+ (call-with-output-file (string-append out "/test")
+ (lambda (p)
+ (display '(hello guix) p))))))
+ (build-expression->derivation store "goo" builder))
address@hidden
-Gexps carry information about the packages or derivations they refer to,
-and these dependencies are automatically added as inputs to the build
-processes that use them.
address@hidden itemize
address@hidden #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
address@hidden lisp
address@hidden lowering, of high-level objects in gexps
-This mechanism is not limited to package and derivation
-objects: @dfn{compilers} able to ``lower'' other high-level objects to
-derivations or files in the store can be defined,
-such that these objects can also be inserted
-into gexps. For example, a useful type of high-level objects that can be
-inserted in a gexp is ``file-like objects'', which make it easy to
-add files to the store and to refer to them in
-derivations and such (see @code{local-file} and @code{plain-file}
-below.)
-To illustrate the idea, here is an example of a gexp:
address@hidden The Store Monad
address@hidden The Store Monad
address@hidden
-(define build-exp
- #~(begin
- (mkdir #$output)
- (chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
- "list-files")))
address@hidden example
address@hidden monad
-This gexp can be passed to @code{gexp->derivation}; we obtain a
-derivation that builds a directory containing exactly one symlink to
address@hidden/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
+The procedures that operate on the store described in the previous
+sections all take an open connection to the build daemon as their first
+argument. Although the underlying model is functional, they either have
+side effects or depend on the current state of the store.
address@hidden
-(gexp->derivation "the-thing" build-exp)
address@hidden example
+The former is inconvenient: the connection to the build daemon has to be
+carried around in all those functions, making it impossible to compose
+functions that do not take that parameter with functions that do. The
+latter can be problematic: since store operations have side effects
+and/or depend on external state, they have to be properly sequenced.
-As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
-substituted to the reference to the @var{coreutils} package in the
-actual build code, and @var{coreutils} is automatically made an input to
-the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
-output)}) is replaced by a string containing the directory name of the
-output of the derivation.
address@hidden monadic values
address@hidden monadic functions
+This is where the @code{(guix monads)} module comes in. This module
+provides a framework for working with @dfn{monads}, and a particularly
+useful monad for our uses, the @dfn{store monad}. Monads are a
+construct that allows two things: associating ``context'' with values
+(in our case, the context is the store), and building sequences of
+computations (here computations include accesses to the store). Values
+in a monad---values that carry this additional context---are called
address@hidden values}; procedures that return such values are called
address@hidden procedures}.
address@hidden cross compilation
-In a cross-compilation context, it is useful to distinguish between
-references to the @emph{native} build of a package---that can run on the
-host---versus references to cross builds of a package. To that end, the
address@hidden plays the same role as @code{#$}, but is a reference to a
-native package build:
+Consider this ``normal'' procedure:
@example
-(gexp->derivation "vi"
- #~(begin
- (mkdir #$output)
- (system* (string-append #+coreutils "/bin/ln")
- "-s"
- (string-append #$emacs "/bin/emacs")
- (string-append #$output "/bin/vi")))
- #:target "mips64el-linux-gnu")
+(define (sh-symlink store)
+ ;; Return a derivation that symlinks the 'bash' executable.
+ (let* ((drv (package-derivation store bash))
+ (out (derivation->output-path drv))
+ (sh (string-append out "/bin/bash")))
+ (build-expression->derivation store "sh"
+ `(symlink ,sh %output))))
@end example
address@hidden
-In the example above, the native build of @var{coreutils} is used, so
-that @command{ln} can actually run on the host; but then the
-cross-compiled build of @var{emacs} is referenced.
-
address@hidden imported modules, for gexps
address@hidden with-imported-modules
-Another gexp feature is @dfn{imported modules}: sometimes you want to be
-able to use certain Guile modules from the ``host environment'' in the
-gexp, so those modules should be imported in the ``build environment''.
-The @code{with-imported-modules} form allows you to express that:
+Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
+as a monadic function:
@example
-(let ((build (with-imported-modules '((guix build utils))
- #~(begin
- (use-modules (guix build utils))
- (mkdir-p (string-append #$output "/bin"))))))
- (gexp->derivation "empty-dir"
- #~(begin
- #$build
- (display "success!\n")
- #t)))
+(define (sh-symlink)
+ ;; Same, but return a monadic value.
+ (mlet %store-monad ((drv (package->derivation bash)))
+ (gexp->derivation "sh"
+ #~(symlink (string-append #$drv "/bin/bash")
+ #$output))))
@end example
address@hidden
-In this example, the @code{(guix build utils)} module is automatically
-pulled into the isolated build environment of our gexp, such that
address@hidden(use-modules (guix build utils))} works as expected.
+There are several things to note in the second version: the @code{store}
+parameter is now implicit and is ``threaded'' in the calls to the
address@hidden>derivation} and @code{gexp->derivation} monadic
+procedures, and the monadic value returned by @code{package->derivation}
+is @dfn{bound} using @code{mlet} instead of plain @code{let}.
address@hidden module closure
address@hidden source-module-closure
-Usually you want the @emph{closure} of the module to be imported---i.e.,
-the module itself and all the modules it depends on---rather than just
-the module; failing to do that, attempts to use the module will fail
-because of missing dependent modules. The @code{source-module-closure}
-procedure computes the closure of a module by looking at its source file
-headers, which comes in handy in this case:
+As it turns out, the call to @code{package->derivation} can even be
+omitted since it will take place implicitly, as we will see later
+(@pxref{G-Expressions}):
@example
-(use-modules (guix modules)) ;for 'source-module-closure'
-
-(with-imported-modules (source-module-closure
- '((guix build utils)
- (gnu build vm)))
- (gexp->derivation "something-with-vms"
- #~(begin
- (use-modules (guix build utils)
- (gnu build vm))
- @dots{})))
+(define (sh-symlink)
+ (gexp->derivation "sh"
+ #~(symlink (string-append #$bash "/bin/bash")
+ #$output)))
@end example
address@hidden extensions, for gexps
address@hidden with-extensions
-In the same vein, sometimes you want to import not just pure-Scheme
-modules, but also ``extensions'' such as Guile bindings to C libraries
-or other ``full-blown'' packages. Say you need the @code{guile-json}
-package available on the build side, here's how you would do it:
address@hidden See
address@hidden
<https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
address@hidden for the funny quote.
+Calling the monadic @code{sh-symlink} has no effect. As someone once
+said, ``you exit a monad like you exit a building on fire: by running''.
+So, to exit the monad and get the desired effect, one must use
address@hidden:
@example
-(use-modules (gnu packages guile)) ;for 'guile-json'
-
-(with-extensions (list guile-json)
- (gexp->derivation "something-with-json"
- #~(begin
- (use-modules (json))
- @dots{})))
+(run-with-store (open-connection) (sh-symlink))
address@hidden /gnu/store/...-sh-symlink
@end example
-The syntactic form to construct gexps is summarized below.
-
address@hidden {Scheme Syntax} address@hidden
address@hidden {Scheme Syntax} (gexp @var{exp})
-Return a G-expression containing @var{exp}. @var{exp} may contain one
-or more of the following forms:
-
address@hidden @code
address@hidden address@hidden
address@hidden (ungexp @var{obj})
-Introduce a reference to @var{obj}. @var{obj} may have one of the
-supported types, for example a package or a
-derivation, in which case the @code{ungexp} form is replaced by its
-output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
-
-If @var{obj} is a list, it is traversed and references to supported
-objects are substituted similarly.
-
-If @var{obj} is another gexp, its contents are inserted and its
-dependencies are added to those of the containing gexp.
-
-If @var{obj} is another kind of object, it is inserted as is.
-
address@hidden address@hidden:@var{output}
address@hidden (ungexp @var{obj} @var{output})
-This is like the form above, but referring explicitly to the
address@hidden of @var{obj}---this is useful when @var{obj} produces
-multiple outputs (@pxref{Packages with Multiple Outputs}).
-
address@hidden address@hidden
address@hidden address@hidden:output
address@hidden (ungexp-native @var{obj})
address@hidden (ungexp-native @var{obj} @var{output})
-Same as @code{ungexp}, but produces a reference to the @emph{native}
-build of @var{obj} when used in a cross compilation context.
+Note that the @code{(guix monad-repl)} module extends the Guile REPL with
+new ``meta-commands'' to make it easier to deal with monadic procedures:
address@hidden, and @code{enter-store-monad}. The former is used
+to ``run'' a single monadic value through the store:
address@hidden #$output[:@var{output}]
address@hidden (ungexp output address@hidden)
-Insert a reference to derivation output @var{output}, or to the main
-output when @var{output} is omitted.
address@hidden
+scheme@@(guile-user)> ,run-in-store (package->derivation hello)
+$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
address@hidden example
-This only makes sense for gexps passed to @code{gexp->derivation}.
+The latter enters a recursive REPL, where all the return values are
+automatically run through the store:
address@hidden #$@@@var{lst}
address@hidden (ungexp-splicing @var{lst})
-Like the above, but splices the contents of @var{lst} inside the
-containing list.
address@hidden
+scheme@@(guile-user)> ,enter-store-monad
+store-monad@@(guile-user) [1]> (package->derivation hello)
+$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
+store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
+$3 = "/gnu/store/@dots{}-foo"
+store-monad@@(guile-user) [1]> ,q
+scheme@@(guile-user)>
address@hidden example
address@hidden #+@@@var{lst}
address@hidden (ungexp-native-splicing @var{lst})
-Like the above, but refers to native builds of the objects listed in
address@hidden
address@hidden
+Note that non-monadic values cannot be returned in the
address@hidden REPL.
address@hidden table
+The main syntactic forms to deal with monads in general are provided by
+the @code{(guix monads)} module and are described below.
-G-expressions created by @code{gexp} or @code{#~} are run-time objects
-of the @code{gexp?} type (see below.)
address@hidden {Scheme Syntax} with-monad @var{monad} @var{body} ...
+Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
+in @var{monad}.
@end deffn
address@hidden {Scheme Syntax} with-imported-modules @var{modules}
@address@hidden
-Mark the gexps defined in @address@hidden as requiring @var{modules}
-in their execution environment.
address@hidden {Scheme Syntax} return @var{val}
+Return a monadic value that encapsulates @var{val}.
address@hidden deffn
-Each item in @var{modules} can be the name of a module, such as
address@hidden(guix build utils)}, or it can be a module name, followed by an
-arrow, followed by a file-like object:
address@hidden {Scheme Syntax} >>= @var{mval} @var{mproc} ...
address@hidden monadic value @var{mval}, passing its ``contents'' to monadic
+procedures @address@hidden@footnote{This operation is commonly
+referred to as ``bind'', but that name denotes an unrelated procedure in
+Guile. Thus we use this somewhat cryptic symbol inherited from the
+Haskell language.}. There can be one @var{mproc} or several of them, as
+in this example:
@example
-`((guix build utils)
- (guix gcrypt)
- ((guix config) => ,(scheme-file "config.scm"
- #~(define-module @dots{}))))
+(run-with-state
+ (with-monad %state-monad
+ (>>= (return 1)
+ (lambda (x) (return (+ 1 x)))
+ (lambda (x) (return (* 2 x)))))
+ 'some-state)
+
address@hidden 4
address@hidden some-state
@end example
address@hidden deffn
address@hidden
-In the example above, the first two modules are taken from the search
-path, and the last one is created from the given file-like object.
address@hidden {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
address@hidden {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
+Bind the variables @var{var} to the monadic values @var{mval} in
address@hidden, which is a sequence of expressions. As with the bind
+operator, this can be thought of as ``unpacking'' the raw, non-monadic
+value ``contained'' in @var{mval} and making @var{var} refer to that
+raw, non-monadic value within the scope of the @var{body}. The form
+(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
address@hidden, as per @code{let}. The binding operations occur in sequence
+from left to right. The last expression of @var{body} must be a monadic
+expression, and its result will become the result of the @code{mlet} or
address@hidden when run in the @var{monad}.
-This form has @emph{lexical} scope: it has an effect on the gexps
-directly defined in @address@hidden, but not on those defined, say, in
-procedures called from @address@hidden
address@hidden is to @code{mlet} what @code{let*} is to @code{let}
+(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@end deffn
address@hidden {Scheme Syntax} with-extensions @var{extensions} @address@hidden
-Mark the gexps defined in @address@hidden as requiring
address@hidden in their build and execution environment.
address@hidden is typically a list of package objects such as those
-defined in the @code{(gnu packages guile)} module.
address@hidden {Scheme System} mbegin @var{monad} @var{mexp} ...
+Bind @var{mexp} and the following monadic expressions in sequence,
+returning the result of the last expression. Every expression in the
+sequence must be a monadic expression.
-Concretely, the packages listed in @var{extensions} are added to the
-load path while compiling imported modules in @address@hidden; they
-are also added to the load path of the gexp returned by
address@hidden@dots{}.
+This is akin to @code{mlet}, except that the return values of the
+monadic expressions are ignored. In that sense, it is analogous to
address@hidden, but applied to monadic expressions.
@end deffn
address@hidden {Scheme Procedure} gexp? @var{obj}
-Return @code{#t} if @var{obj} is a G-expression.
address@hidden {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is true, evaluate the sequence of monadic
+expressions @address@hidden as in an @code{mbegin}. When
address@hidden is false, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
@end deffn
-G-expressions are meant to be written to disk, either as code building
-some derivation, or as plain files in the store. The monadic procedures
-below allow you to do that (@pxref{The Store Monad}, for more
-information about monads.)
-
address@hidden {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
- [#:system (%current-system)] [#:target #f] [#:graft? #t] @
- [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:module-path @var{%load-path}] @
- [#:effective-version "2.2"] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:leaked-env-vars #f] @
- [#:script-name (string-append @var{name} "-builder")] @
- [#:deprecation-warnings #f] @
- [#:local-build? #f] [#:substitutable? #t] @
- [#:properties '()] [#:guile-for-build #f]
-Return a derivation @var{name} that runs @var{exp} (a gexp) with
address@hidden (a derivation) on @var{system}; @var{exp} is
-stored in a file called @var{script-name}. When @var{target} is true,
-it is used as the cross-compilation target triplet for packages referred
-to by @var{exp}.
-
address@hidden is deprecated in favor of @code{with-imported-modules}.
-Its meaning is to
-make @var{modules} available in the evaluation context of @var{exp};
address@hidden is a list of names of Guile modules searched in
address@hidden to be copied in the store, compiled, and made available in
-the load path during the execution of @var{exp}---e.g., @code{((guix
-build utils) (guix build gnu-build-system))}.
address@hidden {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*}
...
+When @var{condition} is false, evaluate the sequence of monadic
+expressions @address@hidden as in an @code{mbegin}. When
address@hidden is true, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
address@hidden deffn
address@hidden determines the string to use when adding extensions of
address@hidden (see @code{with-extensions}) to the search path---e.g.,
@code{"2.2"}.
address@hidden state monad
+The @code{(guix monads)} module provides the @dfn{state monad}, which
+allows an additional value---the state---to be @emph{threaded} through
+monadic procedure calls.
address@hidden determines whether packages referred to by @var{exp} should be
grafted when
-applicable.
address@hidden {Scheme Variable} %state-monad
+The state monad. Procedures in the state monad can access and change
+the state that is threaded.
-When @var{references-graphs} is true, it must be a list of tuples of one of the
-following forms:
+Consider the example below. The @code{square} procedure returns a value
+in the state monad. It returns the square of its argument, but also
+increments the current state value:
@example
-(@var{file-name} @var{package})
-(@var{file-name} @var{package} @var{output})
-(@var{file-name} @var{derivation})
-(@var{file-name} @var{derivation} @var{output})
-(@var{file-name} @var{store-item})
address@hidden example
+(define (square x)
+ (mlet %state-monad ((count (current-state)))
+ (mbegin %state-monad
+ (set-current-state (+ 1 count))
+ (return (* x x)))))
-The right-hand-side of each element of @var{references-graphs} is
automatically made
-an input of the build process of @var{exp}. In the build environment, each
address@hidden contains the reference graph of the corresponding item, in a
simple
-text format.
+(run-with-state (sequence %state-monad (map square (iota 3))) 0)
address@hidden (0 1 4)
address@hidden 3
address@hidden example
address@hidden must be either @code{#f} or a list of output names and packages.
-In the latter case, the list denotes store items that the result is allowed to
-refer to. Any reference to another store item will lead to a build error.
-Similarly for @var{disallowed-references}, which can list items that must not
be
-referenced by the outputs.
+When ``run'' through @var{%state-monad}, we obtain that additional state
+value, which is the number of @code{square} calls.
address@hidden defvr
address@hidden determines whether to show deprecation warnings while
-compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
address@hidden {Monadic Procedure} current-state
+Return the current state as a monadic value.
address@hidden deffn
-The other arguments are as for @code{derivation} (@pxref{Derivations}).
address@hidden {Monadic Procedure} set-current-state @var{value}
+Set the current state to @var{value} and return the previous state as a
+monadic value.
@end deffn
address@hidden file-like objects
-The @code{local-file}, @code{plain-file}, @code{computed-file},
address@hidden, and @code{scheme-file} procedures below return
address@hidden objects}. That is, when unquoted in a G-expression,
-these objects lead to a file in the store. Consider this G-expression:
address@hidden {Monadic Procedure} state-push @var{value}
+Push @var{value} to the current state, which is assumed to be a list,
+and return the previous state as a monadic value.
address@hidden deffn
address@hidden
-#~(system* #$(file-append glibc "/sbin/nscd") "-f"
- #$(local-file "/tmp/my-nscd.conf"))
address@hidden example
address@hidden {Monadic Procedure} state-pop
+Pop a value from the current state and return it as a monadic value.
+The state is assumed to be a list.
address@hidden deffn
-The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
-to the store. Once expanded, for instance @i{via}
address@hidden>derivation}, the G-expression refers to that copy under
address@hidden/gnu/store}; thus, modifying or removing the file in @file{/tmp}
-does not have any effect on what the G-expression does.
address@hidden can be used similarly; it differs in that the file
-content is directly passed as a string.
address@hidden {Scheme Procedure} run-with-state @var{mval} address@hidden
+Run monadic value @var{mval} starting with @var{state} as the initial
+state. Return two values: the resulting value, and the resulting state.
address@hidden deffn
address@hidden {Scheme Procedure} local-file @var{file} address@hidden @
- [#:recursive? #f] [#:select? (const #t)]
-Return an object representing local file @var{file} to add to the store; this
-object can be used in a gexp. If @var{file} is a relative file name, it is
looked
-up relative to the source file where this form appears. @var{file} will be
added to
-the store under @var{name}--by default the base name of @var{file}.
+The main interface to the store monad, provided by the @code{(guix
+store)} module, is as follows.
-When @var{recursive?} is true, the contents of @var{file} are added
recursively; if @var{file}
-designates a flat file and @var{recursive?} is true, its contents are added,
and its
-permission bits are kept.
address@hidden {Scheme Variable} %store-monad
+The store monad---an alias for @var{%state-monad}.
-When @var{recursive?} is true, call @code{(@var{select?} @var{file}
address@hidden)} for each directory entry, where @var{file} is the entry's
-absolute file name and @var{stat} is the result of @code{lstat}; exclude
-entries for which @var{select?} does not return true.
+Values in the store monad encapsulate accesses to the store. When its
+effect is needed, a value of the store monad must be ``evaluated'' by
+passing it to the @code{run-with-store} procedure (see below.)
address@hidden defvr
-This is the declarative counterpart of the @code{interned-file} monadic
-procedure (@pxref{The Store Monad, @code{interned-file}}).
address@hidden {Scheme Procedure} run-with-store @var{store} @var{mval}
[#:guile-for-build] [#:system (%current-system)]
+Run @var{mval}, a monadic value in the store monad, in @var{store}, an
+open store connection.
@end deffn
address@hidden {Scheme Procedure} plain-file @var{name} @var{content}
-Return an object representing a text file called @var{name} with the given
address@hidden (a string or a bytevector) to be added to the store.
-
-This is the declarative counterpart of @code{text-file}.
address@hidden {Monadic Procedure} text-file @var{name} @var{text}
address@hidden
+Return as a monadic value the absolute file name in the store of the file
+containing @var{text}, a string. @var{references} is a list of store items
that the
+resulting text file refers to; it defaults to the empty list.
@end deffn
address@hidden {Scheme Procedure} computed-file @var{name} @var{gexp} @
- [#:options '(#:local-build? #t)]
-Return an object representing the store item @var{name}, a file or
-directory computed by @var{gexp}. @var{options}
-is a list of additional arguments to pass to @code{gexp->derivation}.
-
-This is the declarative counterpart of @code{gexp->derivation}.
address@hidden {Monadic Procedure} binary-file @var{name} @var{data}
address@hidden
+Return as a monadic value the absolute file name in the store of the file
+containing @var{data}, a bytevector. @var{references} is a list of store
+items that the resulting binary file refers to; it defaults to the empty list.
@end deffn
address@hidden {Monadic Procedure} gexp->script @var{name} @var{exp} @
- [#:guile (default-guile)] [#:module-path %load-path]
-Return an executable script @var{name} that runs @var{exp} using
address@hidden, with @var{exp}'s imported modules in its search path.
-Look up @var{exp}'s modules in @var{module-path}.
address@hidden {Monadic Procedure} interned-file @var{file} address@hidden @
+ [#:recursive? #t] [#:select? (const #t)]
+Return the name of @var{file} once interned in the store. Use
address@hidden as its store name, or the basename of @var{file} if
address@hidden is omitted.
-The example below builds a script that simply invokes the @command{ls}
-command:
+When @var{recursive?} is true, the contents of @var{file} are added
+recursively; if @var{file} designates a flat file and @var{recursive?}
+is true, its contents are added, and its permission bits are kept.
address@hidden
-(use-modules (guix gexp) (gnu packages base))
+When @var{recursive?} is true, call @code{(@var{select?} @var{file}
address@hidden)} for each directory entry, where @var{file} is the entry's
+absolute file name and @var{stat} is the result of @code{lstat}; exclude
+entries for which @var{select?} does not return true.
-(gexp->script "list-files"
- #~(execl #$(file-append coreutils "/bin/ls")
- "ls"))
address@hidden example
+The example below adds a file to the store, under two different names:
-When ``running'' it through the store (@pxref{The Store Monad,
address@hidden), we obtain a derivation that produces an
-executable file @file{/gnu/store/@dots{}-list-files} along these lines:
address@hidden
+(run-with-store (open-connection)
+ (mlet %store-monad ((a (interned-file "README"))
+ (b (interned-file "README" "LEGU-MIN")))
+ (return (list a b))))
address@hidden
-#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
-!#
-(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
address@hidden ("/gnu/store/address@hidden" "/gnu/store/address@hidden")
@end example
address@hidden deffn
-
address@hidden {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f] [#:module-path %load-path]
-Return an object representing the executable store item @var{name} that
-runs @var{gexp}. @var{guile} is the Guile package used to execute that
-script. Imported modules of @var{gexp} are looked up in @var{module-path}.
-This is the declarative counterpart of @code{gexp->script}.
@end deffn
address@hidden {Monadic Procedure} gexp->file @var{name} @var{exp} @
- [#:set-load-path? #t] [#:module-path %load-path] @
- [#:splice? #f] @
- [#:guile (default-guile)]
-Return a derivation that builds a file @var{name} containing @var{exp}.
-When @var{splice?} is true, @var{exp} is considered to be a list of
-expressions that will be spliced in the resulting file.
+The @code{(guix packages)} module exports the following package-related
+monadic procedures:
-When @var{set-load-path?} is true, emit code in the resulting file to
-set @code{%load-path} and @code{%load-compiled-path} to honor
address@hidden's imported modules. Look up @var{exp}'s modules in
address@hidden
address@hidden {Monadic Procedure} package-file @var{package} address@hidden @
+ [#:system (%current-system)] [#:target #f] @
+ [#:output "out"]
+Return as a monadic
+value in the absolute file name of @var{file} within the @var{output}
+directory of @var{package}. When @var{file} is omitted, return the name
+of the @var{output} directory of @var{package}. When @var{target} is
+true, use it as a cross-compilation target triplet.
address@hidden deffn
-The resulting file holds references to all the dependencies of @var{exp}
-or a subset thereof.
address@hidden {Monadic Procedure} package->derivation @var{package}
address@hidden
address@hidden {Monadic Procedure} package->cross-derivation @var{package} @
+ @var{target} address@hidden
+Monadic version of @code{package-derivation} and
address@hidden (@pxref{Defining Packages}).
@end deffn
address@hidden {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice?
#f]
-Return an object representing the Scheme file @var{name} that contains
address@hidden
-This is the declarative counterpart of @code{gexp->file}.
address@hidden deffn
address@hidden G-Expressions
address@hidden G-Expressions
address@hidden {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
-Return as a monadic value a derivation that builds a text file
-containing all of @var{text}. @var{text} may list, in addition to
-strings, objects of any type that can be used in a gexp: packages,
-derivations, local file objects, etc. The resulting store file holds
-references to all these.
address@hidden G-expression
address@hidden build code quoting
+So we have ``derivations'', which represent a sequence of build actions
+to be performed to produce an item in the store (@pxref{Derivations}).
+These build actions are performed when asking the daemon to actually
+build the derivations; they are run by the daemon in a container
+(@pxref{Invoking guix-daemon}).
-This variant should be preferred over @code{text-file} anytime the file
-to create will reference items from the store. This is typically the
-case when building a configuration file that embeds store file names,
-like this:
address@hidden strata of code
+It should come as no surprise that we like to write these build actions
+in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
address@hidden term @dfn{stratum} in this context was coined by
+Manuel Serrano et al.@: in the context of their work on Hop. Oleg
+Kiselyov, who has written insightful
address@hidden://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
+on this topic}, refers to this kind of code generation as
address@hidden: the ``host code''---code that defines packages, talks
+to the daemon, etc.---and the ``build code''---code that actually
+performs build actions, such as making directories, invoking
address@hidden, etc.
address@hidden
-(define (profile.sh)
- ;; Return the name of a shell script in the store that
- ;; initializes the 'PATH' environment variable.
- (text-file* "profile.sh"
- "export PATH=" coreutils "/bin:"
- grep "/bin:" sed "/bin\n"))
address@hidden example
+To describe a derivation and its build actions, one typically needs to
+embed build code inside host code. It boils down to manipulating build
+code as data, and the homoiconicity of Scheme---code has a direct
+representation as data---comes in handy for that. But we need more than
+the normal @code{quasiquote} mechanism in Scheme to construct build
+expressions.
-In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
-will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
-preventing them from being garbage-collected during its lifetime.
address@hidden deffn
+The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
+S-expressions adapted to build expressions. G-expressions, or
address@hidden, consist essentially of three syntactic forms: @code{gexp},
address@hidden, and @code{ungexp-splicing} (or simply: @code{#~},
address@hidden, and @code{#$@@}), which are comparable to
address@hidden, @code{unquote}, and @code{unquote-splicing},
+respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
+GNU Guile Reference Manual}). However, there are major differences:
address@hidden {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
-Return an object representing store file @var{name} containing
address@hidden @var{text} is a sequence of strings and file-like objects,
-as in:
address@hidden
address@hidden
+Gexps are meant to be written to a file and run or manipulated by other
+processes.
address@hidden
-(mixed-text-file "profile"
- "export PATH=" coreutils "/bin:" grep "/bin")
address@hidden example
address@hidden
+When a high-level object such as a package or derivation is unquoted
+inside a gexp, the result is as if its output file name had been
+introduced.
-This is the declarative counterpart of @code{text-file*}.
address@hidden deffn
address@hidden
+Gexps carry information about the packages or derivations they refer to,
+and these dependencies are automatically added as inputs to the build
+processes that use them.
address@hidden itemize
address@hidden {Scheme Procedure} file-union @var{name} @var{files}
-Return a @code{<computed-file>} that builds a directory containing all of
@var{files}.
-Each item in @var{files} must be a two-element list where the first element is
the
-file name to use in the new directory, and the second element is a gexp
-denoting the target file. Here's an example:
address@hidden lowering, of high-level objects in gexps
+This mechanism is not limited to package and derivation
+objects: @dfn{compilers} able to ``lower'' other high-level objects to
+derivations or files in the store can be defined,
+such that these objects can also be inserted
+into gexps. For example, a useful type of high-level objects that can be
+inserted in a gexp is ``file-like objects'', which make it easy to
+add files to the store and to refer to them in
+derivations and such (see @code{local-file} and @code{plain-file}
+below.)
+
+To illustrate the idea, here is an example of a gexp:
@example
-(file-union "etc"
- `(("hosts" ,(plain-file "hosts"
- "127.0.0.1 localhost"))
- ("bashrc" ,(plain-file "bashrc"
- "alias ls='ls --color=auto'"))))
+(define build-exp
+ #~(begin
+ (mkdir #$output)
+ (chdir #$output)
+ (symlink (string-append #$coreutils "/bin/ls")
+ "list-files")))
@end example
-This yields an @code{etc} directory containing these two files.
address@hidden deffn
-
address@hidden {Scheme Procedure} directory-union @var{name} @var{things}
-Return a directory that is the union of @var{things}, where @var{things} is a
list of
-file-like objects denoting directories. For example:
+This gexp can be passed to @code{gexp->derivation}; we obtain a
+derivation that builds a directory containing exactly one symlink to
address@hidden/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
@example
-(directory-union "guile+emacs" (list guile emacs))
+(gexp->derivation "the-thing" build-exp)
@end example
-yields a directory that is the union of the @code{guile} and @code{emacs}
packages.
address@hidden deffn
-
address@hidden {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
-Return a file-like object that expands to the concatenation of @var{obj}
-and @var{suffix}, where @var{obj} is a lowerable object and each
address@hidden is a string.
+As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
+substituted to the reference to the @var{coreutils} package in the
+actual build code, and @var{coreutils} is automatically made an input to
+the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
+output)}) is replaced by a string containing the directory name of the
+output of the derivation.
-As an example, consider this gexp:
address@hidden cross compilation
+In a cross-compilation context, it is useful to distinguish between
+references to the @emph{native} build of a package---that can run on the
+host---versus references to cross builds of a package. To that end, the
address@hidden plays the same role as @code{#$}, but is a reference to a
+native package build:
@example
-(gexp->script "run-uname"
- #~(system* #$(file-append coreutils
- "/bin/uname")))
+(gexp->derivation "vi"
+ #~(begin
+ (mkdir #$output)
+ (system* (string-append #+coreutils "/bin/ln")
+ "-s"
+ (string-append #$emacs "/bin/emacs")
+ (string-append #$output "/bin/vi")))
+ #:target "mips64el-linux-gnu")
@end example
-The same effect could be achieved with:
address@hidden
+In the example above, the native build of @var{coreutils} is used, so
+that @command{ln} can actually run on the host; but then the
+cross-compiled build of @var{emacs} is referenced.
+
address@hidden imported modules, for gexps
address@hidden with-imported-modules
+Another gexp feature is @dfn{imported modules}: sometimes you want to be
+able to use certain Guile modules from the ``host environment'' in the
+gexp, so those modules should be imported in the ``build environment''.
+The @code{with-imported-modules} form allows you to express that:
@example
-(gexp->script "run-uname"
- #~(system* (string-append #$coreutils
- "/bin/uname")))
+(let ((build (with-imported-modules '((guix build utils))
+ #~(begin
+ (use-modules (guix build utils))
+ (mkdir-p (string-append #$output "/bin"))))))
+ (gexp->derivation "empty-dir"
+ #~(begin
+ #$build
+ (display "success!\n")
+ #t)))
@end example
-There is one difference though: in the @code{file-append} case, the
-resulting script contains the absolute file name as a string, whereas in
-the second case, the resulting script contains a @code{(string-append
address@hidden)} expression to construct the file name @emph{at run time}.
address@hidden deffn
-
-
-Of course, in addition to gexps embedded in ``host'' code, there are
-also modules containing build tools. To make it clear that they are
-meant to be used in the build stratum, these modules are kept in the
address@hidden(guix build @dots{})} name space.
address@hidden
+In this example, the @code{(guix build utils)} module is automatically
+pulled into the isolated build environment of our gexp, such that
address@hidden(use-modules (guix build utils))} works as expected.
address@hidden lowering, of high-level objects in gexps
-Internally, high-level objects are @dfn{lowered}, using their compiler,
-to either derivations or store items. For instance, lowering a package
-yields a derivation, and lowering a @code{plain-file} yields a store
-item. This is achieved using the @code{lower-object} monadic procedure.
address@hidden module closure
address@hidden source-module-closure
+Usually you want the @emph{closure} of the module to be imported---i.e.,
+the module itself and all the modules it depends on---rather than just
+the module; failing to do that, attempts to use the module will fail
+because of missing dependent modules. The @code{source-module-closure}
+procedure computes the closure of a module by looking at its source file
+headers, which comes in handy in this case:
address@hidden {Monadic Procedure} lower-object @var{obj} address@hidden @
- [#:target #f]
-Return as a value in @var{%store-monad} the derivation or store item
-corresponding to @var{obj} for @var{system}, cross-compiling for
address@hidden if @var{target} is true. @var{obj} must be an object that
-has an associated gexp compiler, such as a @code{<package>}.
address@hidden deffn
address@hidden
+(use-modules (guix modules)) ;for 'source-module-closure'
address@hidden Invoking guix repl
address@hidden Invoking @command{guix repl}
+(with-imported-modules (source-module-closure
+ '((guix build utils)
+ (gnu build vm)))
+ (gexp->derivation "something-with-vms"
+ #~(begin
+ (use-modules (guix build utils)
+ (gnu build vm))
+ @dots{})))
address@hidden example
address@hidden REPL, read-eval-print loop
-The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop}
-(REPL) for interactive programming (@pxref{Using Guile Interactively,,, guile,
-GNU Guile Reference Manual}). Compared to just launching the @command{guile}
-command, @command{guix repl} guarantees that all the Guix modules and all its
-dependencies are available in the search path. You can use it this way:
address@hidden extensions, for gexps
address@hidden with-extensions
+In the same vein, sometimes you want to import not just pure-Scheme
+modules, but also ``extensions'' such as Guile bindings to C libraries
+or other ``full-blown'' packages. Say you need the @code{guile-json}
+package available on the build side, here's how you would do it:
@example
-$ guix repl
-scheme@@(guile-user)> ,use (gnu packages base)
-scheme@@(guile-user)> coreutils
-$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
address@hidden example
+(use-modules (gnu packages guile)) ;for 'guile-json'
address@hidden inferiors
-In addition, @command{guix repl} implements a simple machine-readable REPL
-protocol for use by @code{(guix inferior)}, a facility to interact with
address@hidden, separate processes running a potentially different revision
-of Guix.
+(with-extensions (list guile-json)
+ (gexp->derivation "something-with-json"
+ #~(begin
+ (use-modules (json))
+ @dots{})))
address@hidden example
-The available options are as follows:
+The syntactic form to construct gexps is summarized below.
address@hidden @code
address@hidden address@hidden
address@hidden -t @var{type}
-Start a REPL of the given @var{TYPE}, which can be one of the following:
address@hidden {Scheme Syntax} address@hidden
address@hidden {Scheme Syntax} (gexp @var{exp})
+Return a G-expression containing @var{exp}. @var{exp} may contain one
+or more of the following forms:
@table @code
address@hidden guile
-This is default, and it spawns a standard full-featured Guile REPL.
address@hidden machine
-Spawn a REPL that uses the machine-readable protocol. This is the protocol
-that the @code{(guix inferior)} module speaks.
address@hidden table
address@hidden address@hidden
address@hidden (ungexp @var{obj})
+Introduce a reference to @var{obj}. @var{obj} may have one of the
+supported types, for example a package or a
+derivation, in which case the @code{ungexp} form is replaced by its
+output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
address@hidden address@hidden
-By default, @command{guix repl} reads from standard input and writes to
-standard output. When this option is passed, it will instead listen for
-connections on @var{endpoint}. Here are examples of valid options:
+If @var{obj} is a list, it is traversed and references to supported
+objects are substituted similarly.
address@hidden @code
address@hidden --listen=tcp:37146
-Accept connections on localhost on port 37146.
+If @var{obj} is another gexp, its contents are inserted and its
+dependencies are added to those of the containing gexp.
address@hidden --listen=unix:/tmp/socket
-Accept connections on the Unix-domain socket @file{/tmp/socket}.
address@hidden table
address@hidden table
+If @var{obj} is another kind of object, it is inserted as is.
address@hidden
*********************************************************************
address@hidden Utilities
address@hidden Utilities
address@hidden address@hidden:@var{output}
address@hidden (ungexp @var{obj} @var{output})
+This is like the form above, but referring explicitly to the
address@hidden of @var{obj}---this is useful when @var{obj} produces
+multiple outputs (@pxref{Packages with Multiple Outputs}).
-This section describes Guix command-line utilities. Some of them are
-primarily targeted at developers and users who write new package
-definitions, while others are more generally useful. They complement
-the Scheme programming interface of Guix in a convenient way.
address@hidden address@hidden
address@hidden address@hidden:output
address@hidden (ungexp-native @var{obj})
address@hidden (ungexp-native @var{obj} @var{output})
+Same as @code{ungexp}, but produces a reference to the @emph{native}
+build of @var{obj} when used in a cross compilation context.
address@hidden
-* Invoking guix build:: Building packages from the command line.
-* Invoking guix edit:: Editing package definitions.
-* Invoking guix download:: Downloading a file and printing its hash.
-* Invoking guix hash:: Computing the cryptographic hash of a file.
-* Invoking guix import:: Importing package definitions.
-* Invoking guix refresh:: Updating package definitions.
-* Invoking guix lint:: Finding errors in package definitions.
-* Invoking guix size:: Profiling disk usage.
-* Invoking guix graph:: Visualizing the graph of packages.
-* Invoking guix environment:: Setting up development environments.
-* Invoking guix publish:: Sharing substitutes.
-* Invoking guix challenge:: Challenging substitute servers.
-* Invoking guix copy:: Copying to and from a remote store.
-* Invoking guix container:: Process isolation.
-* Invoking guix weather:: Assessing substitute availability.
-* Invoking guix processes:: Listing client processes.
address@hidden menu
address@hidden #$output[:@var{output}]
address@hidden (ungexp output address@hidden)
+Insert a reference to derivation output @var{output}, or to the main
+output when @var{output} is omitted.
address@hidden Invoking guix build
address@hidden Invoking @command{guix build}
+This only makes sense for gexps passed to @code{gexp->derivation}.
address@hidden package building
address@hidden @command{guix build}
-The @command{guix build} command builds packages or derivations and
-their dependencies, and prints the resulting store paths. Note that it
-does not modify the user's profile---this is the job of the
address@hidden package} command (@pxref{Invoking guix package}). Thus,
-it is mainly useful for distribution developers.
address@hidden #$@@@var{lst}
address@hidden (ungexp-splicing @var{lst})
+Like the above, but splices the contents of @var{lst} inside the
+containing list.
-The general syntax is:
address@hidden #+@@@var{lst}
address@hidden (ungexp-native-splicing @var{lst})
+Like the above, but refers to native builds of the objects listed in
address@hidden
address@hidden
-guix build @var{options} @address@hidden
address@hidden example
address@hidden table
-As an example, the following command builds the latest versions of Emacs
-and of Guile, displays their build logs, and finally displays the
-resulting directories:
+G-expressions created by @code{gexp} or @code{#~} are run-time objects
+of the @code{gexp?} type (see below.)
address@hidden deffn
address@hidden
-guix build emacs guile
address@hidden example
address@hidden {Scheme Syntax} with-imported-modules @var{modules}
@address@hidden
+Mark the gexps defined in @address@hidden as requiring @var{modules}
+in their execution environment.
-Similarly, the following command builds all the available packages:
+Each item in @var{modules} can be the name of a module, such as
address@hidden(guix build utils)}, or it can be a module name, followed by an
+arrow, followed by a file-like object:
@example
-guix build --quiet --keep-going \
- `guix package -A | cut -f1,2 --output-delimiter=@@`
+`((guix build utils)
+ (guix gcrypt)
+ ((guix config) => ,(scheme-file "config.scm"
+ #~(define-module @dots{}))))
@end example
address@hidden may be either the name of a package found in
-the software distribution such as @code{coreutils} or
address@hidden@@8.20}, or a derivation such as
address@hidden/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
-package with the corresponding name (and optionally version) is searched
-for among the GNU distribution modules (@pxref{Package Modules}).
-
-Alternatively, the @code{--expression} option may be used to specify a
-Scheme expression that evaluates to a package; this is useful when
-disambiguating among several same-named packages or package variants is
-needed.
-
-There may be zero or more @var{options}. The available options are
-described in the subsections below.
-
address@hidden
-* Common Build Options:: Build options for most commands.
-* Package Transformation Options:: Creating variants of packages.
-* Additional Build Options:: Options specific to 'guix build'.
-* Debugging Build Failures:: Real life packaging experience.
address@hidden menu
-
address@hidden Common Build Options
address@hidden Common Build Options
-
-A number of options that control the build process are common to
address@hidden build} and other commands that can spawn builds, such as
address@hidden package} or @command{guix archive}. These are the
-following:
address@hidden
+In the example above, the first two modules are taken from the search
+path, and the last one is created from the given file-like object.
address@hidden @code
+This form has @emph{lexical} scope: it has an effect on the gexps
+directly defined in @address@hidden, but not on those defined, say, in
+procedures called from @address@hidden
address@hidden deffn
address@hidden address@hidden
address@hidden -L @var{directory}
-Add @var{directory} to the front of the package module search path
-(@pxref{Package Modules}).
address@hidden {Scheme Syntax} with-extensions @var{extensions} @address@hidden
+Mark the gexps defined in @address@hidden as requiring
address@hidden in their build and execution environment.
address@hidden is typically a list of package objects such as those
+defined in the @code{(gnu packages guile)} module.
-This allows users to define their own packages and make them visible to
-the command-line tools.
+Concretely, the packages listed in @var{extensions} are added to the
+load path while compiling imported modules in @address@hidden; they
+are also added to the load path of the gexp returned by
address@hidden@dots{}.
address@hidden deffn
address@hidden --keep-failed
address@hidden -K
-Keep the build tree of failed builds. Thus, if a build fails, its build
-tree is kept under @file{/tmp}, in a directory whose name is shown at
-the end of the build log. This is useful when debugging build issues.
address@hidden Build Failures}, for tips and tricks on how to debug
-build issues.
address@hidden {Scheme Procedure} gexp? @var{obj}
+Return @code{#t} if @var{obj} is a G-expression.
address@hidden deffn
-This option has no effect when connecting to a remote daemon with a
address@hidden://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
-variable}).
+G-expressions are meant to be written to disk, either as code building
+some derivation, or as plain files in the store. The monadic procedures
+below allow you to do that (@pxref{The Store Monad}, for more
+information about monads.)
address@hidden --keep-going
address@hidden -k
-Keep going when some of the derivations fail to build; return only once
-all the builds have either completed or failed.
address@hidden {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
+ [#:system (%current-system)] [#:target #f] [#:graft? #t] @
+ [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:module-path @var{%load-path}] @
+ [#:effective-version "2.2"] @
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:disallowed-references #f] @
+ [#:leaked-env-vars #f] @
+ [#:script-name (string-append @var{name} "-builder")] @
+ [#:deprecation-warnings #f] @
+ [#:local-build? #f] [#:substitutable? #t] @
+ [#:properties '()] [#:guile-for-build #f]
+Return a derivation @var{name} that runs @var{exp} (a gexp) with
address@hidden (a derivation) on @var{system}; @var{exp} is
+stored in a file called @var{script-name}. When @var{target} is true,
+it is used as the cross-compilation target triplet for packages referred
+to by @var{exp}.
-The default behavior is to stop as soon as one of the specified
-derivations has failed.
address@hidden is deprecated in favor of @code{with-imported-modules}.
+Its meaning is to
+make @var{modules} available in the evaluation context of @var{exp};
address@hidden is a list of names of Guile modules searched in
address@hidden to be copied in the store, compiled, and made available in
+the load path during the execution of @var{exp}---e.g., @code{((guix
+build utils) (guix build gnu-build-system))}.
address@hidden --dry-run
address@hidden -n
-Do not build the derivations.
address@hidden determines the string to use when adding extensions of
address@hidden (see @code{with-extensions}) to the search path---e.g.,
@code{"2.2"}.
address@hidden
address@hidden --fallback
-When substituting a pre-built binary fails, fall back to building
-packages locally (@pxref{Substitution Failure}).
address@hidden determines whether packages referred to by @var{exp} should be
grafted when
+applicable.
address@hidden address@hidden
address@hidden
-Consider @var{urls} the whitespace-separated list of substitute source
-URLs, overriding the default list of URLs of @command{guix-daemon}
-(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
+When @var{references-graphs} is true, it must be a list of tuples of one of the
+following forms:
-This means that substitutes may be downloaded from @var{urls}, provided
-they are signed by a key authorized by the system administrator
-(@pxref{Substitutes}).
address@hidden
+(@var{file-name} @var{package})
+(@var{file-name} @var{package} @var{output})
+(@var{file-name} @var{derivation})
+(@var{file-name} @var{derivation} @var{output})
+(@var{file-name} @var{store-item})
address@hidden example
-When @var{urls} is the empty string, substitutes are effectively
-disabled.
+The right-hand-side of each element of @var{references-graphs} is
automatically made
+an input of the build process of @var{exp}. In the build environment, each
address@hidden contains the reference graph of the corresponding item, in a
simple
+text format.
address@hidden --no-substitutes
-Do not use substitutes for build products. That is, always build things
-locally instead of allowing downloads of pre-built binaries
-(@pxref{Substitutes}).
address@hidden must be either @code{#f} or a list of output names and packages.
+In the latter case, the list denotes store items that the result is allowed to
+refer to. Any reference to another store item will lead to a build error.
+Similarly for @var{disallowed-references}, which can list items that must not
be
+referenced by the outputs.
address@hidden --no-grafts
-Do not ``graft'' packages. In practice, this means that package updates
-available as grafts are not applied. @xref{Security Updates}, for more
-information on grafts.
address@hidden determines whether to show deprecation warnings while
+compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
address@hidden address@hidden
-Build each derivation @var{n} times in a row, and raise an error if
-consecutive build results are not bit-for-bit identical.
+The other arguments are as for @code{derivation} (@pxref{Derivations}).
address@hidden deffn
-This is a useful way to detect non-deterministic builds processes.
-Non-deterministic build processes are a problem because they make it
-practically impossible for users to @emph{verify} whether third-party
-binaries are genuine. @xref{Invoking guix challenge}, for more.
address@hidden file-like objects
+The @code{local-file}, @code{plain-file}, @code{computed-file},
address@hidden, and @code{scheme-file} procedures below return
address@hidden objects}. That is, when unquoted in a G-expression,
+these objects lead to a file in the store. Consider this G-expression:
-Note that, currently, the differing build results are not kept around,
-so you will have to manually investigate in case of an error---e.g., by
-stashing one of the build results with @code{guix archive --export}
-(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
-the two results.
address@hidden
+#~(system* #$(file-append glibc "/sbin/nscd") "-f"
+ #$(local-file "/tmp/my-nscd.conf"))
address@hidden example
address@hidden --no-build-hook
-Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
-(@pxref{Daemon Offload Setup}). That is, always build things locally
-instead of offloading builds to remote machines.
+The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
+to the store. Once expanded, for instance @i{via}
address@hidden>derivation}, the G-expression refers to that copy under
address@hidden/gnu/store}; thus, modifying or removing the file in @file{/tmp}
+does not have any effect on what the G-expression does.
address@hidden can be used similarly; it differs in that the file
+content is directly passed as a string.
address@hidden address@hidden
-When the build or substitution process remains silent for more than
address@hidden, terminate it and report a build failure.
address@hidden {Scheme Procedure} local-file @var{file} address@hidden @
+ [#:recursive? #f] [#:select? (const #t)]
+Return an object representing local file @var{file} to add to the store; this
+object can be used in a gexp. If @var{file} is a relative file name, it is
looked
+up relative to the source file where this form appears. @var{file} will be
added to
+the store under @var{name}--by default the base name of @var{file}.
-By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--max-silent-time}}).
+When @var{recursive?} is true, the contents of @var{file} are added
recursively; if @var{file}
+designates a flat file and @var{recursive?} is true, its contents are added,
and its
+permission bits are kept.
address@hidden address@hidden
-Likewise, when the build or substitution process lasts for more than
address@hidden, terminate it and report a build failure.
+When @var{recursive?} is true, call @code{(@var{select?} @var{file}
address@hidden)} for each directory entry, where @var{file} is the entry's
+absolute file name and @var{stat} is the result of @code{lstat}; exclude
+entries for which @var{select?} does not return true.
-By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--timeout}}).
+This is the declarative counterpart of the @code{interned-file} monadic
+procedure (@pxref{The Store Monad, @code{interned-file}}).
address@hidden deffn
address@hidden Note: This option is actually not part of
%standard-build-options but
address@hidden most programs honor it.
address@hidden verbosity, of the command-line tools
address@hidden build logs, verbosity
address@hidden -v @var{level}
address@hidden address@hidden
-Use the given verbosity @var{level}, an integer. Choosing 0 means that no
-output is produced, 1 is for quiet output, and 2 shows all the build log
-output on standard error.
address@hidden {Scheme Procedure} plain-file @var{name} @var{content}
+Return an object representing a text file called @var{name} with the given
address@hidden (a string or a bytevector) to be added to the store.
address@hidden address@hidden
address@hidden -c @var{n}
-Allow the use of up to @var{n} CPU cores for the build. The special
-value @code{0} means to use as many CPU cores as available.
+This is the declarative counterpart of @code{text-file}.
address@hidden deffn
address@hidden address@hidden
address@hidden -M @var{n}
-Allow at most @var{n} build jobs in parallel. @xref{Invoking
-guix-daemon, @code{--max-jobs}}, for details about this option and the
-equivalent @command{guix-daemon} option.
address@hidden {Scheme Procedure} computed-file @var{name} @var{gexp} @
+ [#:options '(#:local-build? #t)]
+Return an object representing the store item @var{name}, a file or
+directory computed by @var{gexp}. @var{options}
+is a list of additional arguments to pass to @code{gexp->derivation}.
address@hidden address@hidden
-Produce debugging output coming from the build daemon. @var{level} must be an
-integer between 0 and 5; higher means more verbose output. Setting a level of
-4 or more may be helpful when debugging setup issues with the build daemon.
+This is the declarative counterpart of @code{gexp->derivation}.
address@hidden deffn
address@hidden table
address@hidden {Monadic Procedure} gexp->script @var{name} @var{exp} @
+ [#:guile (default-guile)] [#:module-path %load-path]
+Return an executable script @var{name} that runs @var{exp} using
address@hidden, with @var{exp}'s imported modules in its search path.
+Look up @var{exp}'s modules in @var{module-path}.
-Behind the scenes, @command{guix build} is essentially an interface to
-the @code{package-derivation} procedure of the @code{(guix packages)}
-module, and to the @code{build-derivations} procedure of the @code{(guix
-derivations)} module.
+The example below builds a script that simply invokes the @command{ls}
+command:
-In addition to options explicitly passed on the command line,
address@hidden build} and other @command{guix} commands that support
-building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
address@hidden
+(use-modules (guix gexp) (gnu packages base))
address@hidden {Environment Variable} GUIX_BUILD_OPTIONS
-Users can define this variable to a list of command line options that
-will automatically be used by @command{guix build} and other
address@hidden commands that can perform builds, as in the example
-below:
+(gexp->script "list-files"
+ #~(execl #$(file-append coreutils "/bin/ls")
+ "ls"))
address@hidden example
+
+When ``running'' it through the store (@pxref{The Store Monad,
address@hidden), we obtain a derivation that produces an
+executable file @file{/gnu/store/@dots{}-list-files} along these lines:
@example
-$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
+#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
+!#
+(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
@end example
address@hidden deffn
-These options are parsed independently, and the result is appended to
-the parsed command-line options.
address@hidden defvr
address@hidden {Scheme Procedure} program-file @var{name} @var{exp} @
+ [#:guile #f] [#:module-path %load-path]
+Return an object representing the executable store item @var{name} that
+runs @var{gexp}. @var{guile} is the Guile package used to execute that
+script. Imported modules of @var{gexp} are looked up in @var{module-path}.
+This is the declarative counterpart of @code{gexp->script}.
address@hidden deffn
address@hidden Package Transformation Options
address@hidden Package Transformation Options
address@hidden {Monadic Procedure} gexp->file @var{name} @var{exp} @
+ [#:set-load-path? #t] [#:module-path %load-path] @
+ [#:splice? #f] @
+ [#:guile (default-guile)]
+Return a derivation that builds a file @var{name} containing @var{exp}.
+When @var{splice?} is true, @var{exp} is considered to be a list of
+expressions that will be spliced in the resulting file.
address@hidden package variants
-Another set of command-line options supported by @command{guix build}
-and also @command{guix package} are @dfn{package transformation
-options}. These are options that make it possible to define @dfn{package
-variants}---for instance, packages built from different source code.
-This is a convenient way to create customized packages on the fly
-without having to type in the definitions of package variants
-(@pxref{Defining Packages}).
+When @var{set-load-path?} is true, emit code in the resulting file to
+set @code{%load-path} and @code{%load-compiled-path} to honor
address@hidden's imported modules. Look up @var{exp}'s modules in
address@hidden
address@hidden @code
+The resulting file holds references to all the dependencies of @var{exp}
+or a subset thereof.
address@hidden deffn
address@hidden address@hidden
address@hidden address@hidden@var{source}
address@hidden address@hidden@@@address@hidden
-Use @var{source} as the source of @var{package}, and @var{version} as
-its version number.
address@hidden must be a file name or a URL, as for @command{guix
-download} (@pxref{Invoking guix download}).
address@hidden {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice?
#f]
+Return an object representing the Scheme file @var{name} that contains
address@hidden
-When @var{package} is omitted,
-it is taken to be the package name specified on the
-command line that matches the base of @var{source}---e.g.,
-if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
-package is @code{guile}.
+This is the declarative counterpart of @code{gexp->file}.
address@hidden deffn
-Likewise, when @var{version} is omitted, the version string is inferred from
address@hidden; in the previous example, it is @code{2.0.10}.
address@hidden {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
+Return as a monadic value a derivation that builds a text file
+containing all of @var{text}. @var{text} may list, in addition to
+strings, objects of any type that can be used in a gexp: packages,
+derivations, local file objects, etc. The resulting store file holds
+references to all these.
-This option allows users to try out versions of packages other than the
-one provided by the distribution. The example below downloads
address@hidden from a GNU mirror and uses that as the source for
-the @code{ed} package:
+This variant should be preferred over @code{text-file} anytime the file
+to create will reference items from the store. This is typically the
+case when building a configuration file that embeds store file names,
+like this:
@example
-guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
+(define (profile.sh)
+ ;; Return the name of a shell script in the store that
+ ;; initializes the 'PATH' environment variable.
+ (text-file* "profile.sh"
+ "export PATH=" coreutils "/bin:"
+ grep "/bin:" sed "/bin\n"))
@end example
-As a developer, @code{--with-source} makes it easy to test release
-candidates:
-
address@hidden
-guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
address@hidden example
+In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
+will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
address@hidden deffn
address@hidden or to build from a checkout in a pristine environment:
address@hidden {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
+Return an object representing store file @var{name} containing
address@hidden @var{text} is a sequence of strings and file-like objects,
+as in:
@example
-$ git clone git://git.sv.gnu.org/guix.git
-$ guix build guix --with-source=guix@@1.0=./guix
+(mixed-text-file "profile"
+ "export PATH=" coreutils "/bin:" grep "/bin")
@end example
address@hidden address@hidden@var{replacement}
-Replace dependency on @var{package} by a dependency on
address@hidden @var{package} must be a package name, and
address@hidden must be a package specification such as @code{guile}
-or @code{guile@@1.8}.
+This is the declarative counterpart of @code{text-file*}.
address@hidden deffn
-For instance, the following command builds Guix, but replaces its
-dependency on the current stable version of Guile with a dependency on
-the legacy version of Guile, @code{guile@@2.0}:
address@hidden {Scheme Procedure} file-union @var{name} @var{files}
+Return a @code{<computed-file>} that builds a directory containing all of
@var{files}.
+Each item in @var{files} must be a two-element list where the first element is
the
+file name to use in the new directory, and the second element is a gexp
+denoting the target file. Here's an example:
@example
-guix build --with-input=guile=guile@@2.0 guix
+(file-union "etc"
+ `(("hosts" ,(plain-file "hosts"
+ "127.0.0.1 localhost"))
+ ("bashrc" ,(plain-file "bashrc"
+ "alias ls='ls --color=auto'"))))
@end example
-This is a recursive, deep replacement. So in this example, both
address@hidden and its dependency @code{guile-json} (which also depends on
address@hidden) get rebuilt against @code{guile@@2.0}.
-
-This is implemented using the @code{package-input-rewriting} Scheme
-procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
-
address@hidden address@hidden@var{replacement}
-This is similar to @code{--with-input} but with an important difference:
-instead of rebuilding the whole dependency chain, @var{replacement} is
-built and then @dfn{grafted} onto the binaries that were initially
-referring to @var{package}. @xref{Security Updates}, for more
-information on grafts.
+This yields an @code{etc} directory containing these two files.
address@hidden deffn
-For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
-and all its dependencies, replacing references to the version of GnuTLS
-they currently refer to:
address@hidden {Scheme Procedure} directory-union @var{name} @var{things}
+Return a directory that is the union of @var{things}, where @var{things} is a
list of
+file-like objects denoting directories. For example:
@example
-guix build --with-graft=gnutls=gnutls@@3.5.4 wget
+(directory-union "guile+emacs" (list guile emacs))
@end example
-This has the advantage of being much faster than rebuilding everything.
-But there is a caveat: it works if and only if @var{package} and
address@hidden are strictly compatible---for example, if they provide
-a library, the application binary interface (ABI) of those libraries
-must be compatible. If @var{replacement} is somehow incompatible with
address@hidden, then the resulting package may be unusable. Use with
-care!
+yields a directory that is the union of the @code{guile} and @code{emacs}
packages.
address@hidden deffn
address@hidden address@hidden@var{branch}
address@hidden Git, using the latest commit
address@hidden latest commit, building
-Build @var{package} from the latest commit of @var{branch}. The @code{source}
-field of @var{package} must be an origin with the @code{git-fetch} method
-(@pxref{origin Reference}) or a @code{git-checkout} object; the repository URL
-is taken from that @code{source}. Git sub-modules of the repository are
-fetched, recursively.
address@hidden {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
+Return a file-like object that expands to the concatenation of @var{obj}
+and @var{suffix}, where @var{obj} is a lowerable object and each
address@hidden is a string.
-For instance, the following command builds @code{guile-sqlite3} from the
-latest commit of its @code{master} branch, and then builds @code{guix} (which
-depends on it) and @code{cuirass} (which depends on @code{guix}) against this
-specific @code{guile-sqlite3} build:
+As an example, consider this gexp:
@example
-guix build --with-branch=guile-sqlite3=master cuirass
+(gexp->script "run-uname"
+ #~(system* #$(file-append coreutils
+ "/bin/uname")))
@end example
address@hidden continuous integration
-Obviously, since it uses the latest commit of the given branch, the result of
-such a command varies over time. Nevertheless it is a convenient way to
-rebuild entire software stacks against the latest commit of one or more
-packages. This is particularly useful in the context of continuous
-integration (CI).
+The same effect could be achieved with:
-Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
-consecutive accesses to the same repository. You may want to clean it up once
-in a while to save disk space.
address@hidden
+(gexp->script "run-uname"
+ #~(system* (string-append #$coreutils
+ "/bin/uname")))
address@hidden example
address@hidden address@hidden@var{commit}
-This is similar to @code{--with-branch}, except that it builds from
address@hidden rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier.
address@hidden table
+There is one difference though: in the @code{file-append} case, the
+resulting script contains the absolute file name as a string, whereas in
+the second case, the resulting script contains a @code{(string-append
address@hidden)} expression to construct the file name @emph{at run time}.
address@hidden deffn
address@hidden Additional Build Options
address@hidden Additional Build Options
-The command-line options presented below are specific to @command{guix
-build}.
+Of course, in addition to gexps embedded in ``host'' code, there are
+also modules containing build tools. To make it clear that they are
+meant to be used in the build stratum, these modules are kept in the
address@hidden(guix build @dots{})} name space.
address@hidden @code
address@hidden lowering, of high-level objects in gexps
+Internally, high-level objects are @dfn{lowered}, using their compiler,
+to either derivations or store items. For instance, lowering a package
+yields a derivation, and lowering a @code{plain-file} yields a store
+item. This is achieved using the @code{lower-object} monadic procedure.
address@hidden --quiet
address@hidden -q
-Build quietly, without displaying the build log; this is equivalent to
address@hidden Upon completion, the build log is kept in @file{/var}
-(or similar) and can always be retrieved using the @option{--log-file} option.
address@hidden {Monadic Procedure} lower-object @var{obj} address@hidden @
+ [#:target #f]
+Return as a value in @var{%store-monad} the derivation or store item
+corresponding to @var{obj} for @var{system}, cross-compiling for
address@hidden if @var{target} is true. @var{obj} must be an object that
+has an associated gexp compiler, such as a @code{<package>}.
address@hidden deffn
address@hidden address@hidden
address@hidden -f @var{file}
-Build the package, derivation, or other file-like object that the code within
address@hidden evaluates to (@pxref{G-Expressions, file-like objects}).
address@hidden Invoking guix repl
address@hidden Invoking @command{guix repl}
-As an example, @var{file} might contain a package definition like this
-(@pxref{Defining Packages}):
address@hidden REPL, read-eval-print loop
+The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop}
+(REPL) for interactive programming (@pxref{Using Guile Interactively,,, guile,
+GNU Guile Reference Manual}). Compared to just launching the @command{guile}
+command, @command{guix repl} guarantees that all the Guix modules and all its
+dependencies are available in the search path. You can use it this way:
@example
address@hidden package-hello.scm
+$ guix repl
+scheme@@(guile-user)> ,use (gnu packages base)
+scheme@@(guile-user)> coreutils
+$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
@end example
address@hidden address@hidden
address@hidden -e @var{expr}
-Build the package or derivation @var{expr} evaluates to.
address@hidden inferiors
+In addition, @command{guix repl} implements a simple machine-readable REPL
+protocol for use by @code{(guix inferior)}, a facility to interact with
address@hidden, separate processes running a potentially different revision
+of Guix.
-For example, @var{expr} may be @code{(@@ (gnu packages guile)
-guile-1.8)}, which unambiguously designates this specific variant of
-version 1.8 of Guile.
+The available options are as follows:
-Alternatively, @var{expr} may be a G-expression, in which case it is used
-as a build program passed to @code{gexp->derivation}
-(@pxref{G-Expressions}).
address@hidden @code
address@hidden address@hidden
address@hidden -t @var{type}
+Start a REPL of the given @var{TYPE}, which can be one of the following:
-Lastly, @var{expr} may refer to a zero-argument monadic procedure
-(@pxref{The Store Monad}). The procedure must return a derivation as a
-monadic value, which is then passed through @code{run-with-store}.
address@hidden @code
address@hidden guile
+This is default, and it spawns a standard full-featured Guile REPL.
address@hidden machine
+Spawn a REPL that uses the machine-readable protocol. This is the protocol
+that the @code{(guix inferior)} module speaks.
address@hidden table
address@hidden --source
address@hidden -S
-Build the source derivations of the packages, rather than the packages
-themselves.
address@hidden address@hidden
+By default, @command{guix repl} reads from standard input and writes to
+standard output. When this option is passed, it will instead listen for
+connections on @var{endpoint}. Here are examples of valid options:
-For instance, @code{guix build -S gcc} returns something like
address@hidden/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
-source tarball.
address@hidden @code
address@hidden --listen=tcp:37146
+Accept connections on localhost on port 37146.
-The returned source tarball is the result of applying any patches and
-code snippets specified in the package @code{origin} (@pxref{Defining
-Packages}).
address@hidden --listen=unix:/tmp/socket
+Accept connections on the Unix-domain socket @file{/tmp/socket}.
address@hidden table
address@hidden table
address@hidden --sources
-Fetch and return the source of @var{package-or-derivation} and all their
-dependencies, recursively. This is a handy way to obtain a local copy
-of all the source code needed to build @var{packages}, allowing you to
-eventually build them even without network access. It is an extension
-of the @code{--source} option and can accept one of the following
-optional argument values:
address@hidden
*********************************************************************
address@hidden Utilities
address@hidden Utilities
+
+This section describes Guix command-line utilities. Some of them are
+primarily targeted at developers and users who write new package
+definitions, while others are more generally useful. They complement
+the Scheme programming interface of Guix in a convenient way.
+
address@hidden
+* 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 publish:: Sharing substitutes.
+* Invoking guix challenge:: Challenging substitute servers.
+* Invoking guix copy:: Copying to and from a remote store.
+* Invoking guix container:: Process isolation.
+* Invoking guix weather:: Assessing substitute availability.
+* Invoking guix processes:: Listing client processes.
address@hidden menu
+
address@hidden Invoking guix build
address@hidden Invoking @command{guix build}
address@hidden @code
address@hidden package
-This value causes the @code{--sources} option to behave in the same way
-as the @code{--source} option.
address@hidden package building
address@hidden @command{guix build}
+The @command{guix build} command builds packages or derivations and
+their dependencies, and prints the resulting store paths. Note that it
+does not modify the user's profile---this is the job of the
address@hidden package} command (@pxref{Invoking guix package}). Thus,
+it is mainly useful for distribution developers.
address@hidden all
-Build the source derivations of all packages, including any source that
-might be listed as @code{inputs}. This is the default value.
+The general syntax is:
@example
-$ guix build --sources tzdata
-The following derivations will be built:
- /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+guix build @var{options} @address@hidden
@end example
address@hidden transitive
-Build the source derivations of all packages, as well of all transitive
-inputs to the packages. This can be used e.g.@: to
-prefetch package source for later offline building.
+As an example, the following command builds the latest versions of Emacs
+and of Guile, displays their build logs, and finally displays the
+resulting directories:
@example
-$ guix build --sources=transitive tzdata
-The following derivations will be built:
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
- /gnu/store/@dots{}-grep-2.21.tar.xz.drv
- /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
- /gnu/store/@dots{}-make-4.1.tar.xz.drv
- /gnu/store/@dots{}-bash-4.3.tar.xz.drv
address@hidden
+guix build emacs guile
@end example
address@hidden table
-
address@hidden address@hidden
address@hidden -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
-
address@hidden Note
-The @code{--system} flag is for @emph{native} compilation and must not
-be confused with cross-compilation. See @code{--target} below for
-information on cross-compilation.
address@hidden quotation
-
-An example use of this is on Linux-based systems, which can emulate
-different personalities. For instance, passing
address@hidden on an @code{x86_64-linux} system or
address@hidden on an @code{aarch64-linux} system allows you
-to build packages in a complete 32-bit environment.
-
address@hidden Note
-Building for an @code{armhf-linux} system is unconditionally enabled on
address@hidden machines, although certain aarch64 chipsets do not
-allow for this functionality, notably the ThunderX.
address@hidden quotation
+Similarly, the following command builds all the available packages:
-Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
-is enabled (@pxref{Virtualization Services,
address@hidden), you can build for any system for
-which a QEMU @code{binfmt_misc} handler is installed.
address@hidden
+guix build --quiet --keep-going \
+ `guix package -A | cut -f1,2 --output-delimiter=@@`
address@hidden example
-Builds for a system other than that of the machine you are using can
-also be offloaded to a remote machine of the right architecture.
address@hidden Offload Setup}, for more information on offloading.
address@hidden may be either the name of a package found in
+the software distribution such as @code{coreutils} or
address@hidden@@8.20}, or a derivation such as
address@hidden/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
+package with the corresponding name (and optionally version) is searched
+for among the GNU distribution modules (@pxref{Package Modules}).
address@hidden address@hidden
address@hidden cross-compilation
-Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
-configuration triplets,, autoconf, Autoconf}).
+Alternatively, the @code{--expression} option may be used to specify a
+Scheme expression that evaluates to a package; this is useful when
+disambiguating among several same-named packages or package variants is
+needed.
address@hidden
address@hidden --check
address@hidden determinism, checking
address@hidden reproducibility, checking
-Rebuild @var{package-or-derivation}, which are already available in the
-store, and raise an error if the build results are not bit-for-bit
-identical.
+There may be zero or more @var{options}. The available options are
+described in the subsections below.
-This mechanism allows you to check whether previously installed
-substitutes are genuine (@pxref{Substitutes}), or whether the build result
-of a package is deterministic. @xref{Invoking guix challenge}, for more
-background information and tools.
address@hidden
+* Common Build Options:: Build options for most commands.
+* Package Transformation Options:: Creating variants of packages.
+* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience.
address@hidden menu
-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.
address@hidden Common Build Options
address@hidden Common Build Options
address@hidden --repair
address@hidden repairing store items
address@hidden corruption, recovering from
-Attempt to repair the specified store items, if they are corrupt, by
-re-downloading or rebuilding them.
+A number of options that control the build process are common to
address@hidden build} and other commands that can spawn builds, such as
address@hidden package} or @command{guix archive}. These are the
+following:
-This operation is not atomic and thus restricted to @code{root}.
address@hidden @code
address@hidden --derivations
address@hidden -d
-Return the derivation paths, not the output paths, of the given
-packages.
address@hidden address@hidden
address@hidden -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
address@hidden address@hidden
address@hidden -r @var{file}
address@hidden GC roots, adding
address@hidden garbage collector roots, adding
-Make @var{file} a symlink to the result, and register it as a garbage
-collector root.
+This allows users to define their own packages and make them visible to
+the command-line tools.
-Consequently, the results of this @command{guix build} invocation are
-protected from garbage collection until @var{file} is removed. When
-that option is omitted, build results are eligible for garbage
-collection as soon as the build completes. @xref{Invoking guix gc}, for
-more on GC roots.
address@hidden --keep-failed
address@hidden -K
+Keep the build tree of failed builds. Thus, if a build fails, its build
+tree is kept under @file{/tmp}, in a directory whose name is shown at
+the end of the build log. This is useful when debugging build issues.
address@hidden Build Failures}, for tips and tricks on how to debug
+build issues.
address@hidden --log-file
address@hidden build logs, access
-Return the build log file names or URLs for the given
address@hidden, or raise an error if build logs are
-missing.
+This option has no effect when connecting to a remote daemon with a
address@hidden://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
+variable}).
-This works regardless of how packages or derivations are specified. For
-instance, the following invocations are equivalent:
address@hidden --keep-going
address@hidden -k
+Keep going when some of the derivations fail to build; return only once
+all the builds have either completed or failed.
address@hidden
-guix build --log-file `guix build -d guile`
-guix build --log-file `guix build guile`
-guix build --log-file guile
-guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
address@hidden example
+The default behavior is to stop as soon as one of the specified
+derivations has failed.
-If a log is unavailable locally, and unless @code{--no-substitutes} is
-passed, the command looks for a corresponding log on one of the
-substitute servers (as specified with @code{--substitute-urls}.)
address@hidden --dry-run
address@hidden -n
+Do not build the derivations.
-So for instance, imagine you want to see the build log of GDB on MIPS,
-but you are actually on an @code{x86_64} machine:
address@hidden
address@hidden --fallback
+When substituting a pre-built binary fails, fall back to building
+packages locally (@pxref{Substitution Failure}).
address@hidden
-$ guix build --log-file gdb -s mips64el-linux
-https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
address@hidden example
address@hidden address@hidden
address@hidden
+Consider @var{urls} the whitespace-separated list of substitute source
+URLs, overriding the default list of URLs of @command{guix-daemon}
+(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
-You can freely access a huge library of build logs!
address@hidden table
+This means that substitutes may be downloaded from @var{urls}, provided
+they are signed by a key authorized by the system administrator
+(@pxref{Substitutes}).
address@hidden Debugging Build Failures
address@hidden Debugging Build Failures
+When @var{urls} is the empty string, substitutes are effectively
+disabled.
address@hidden build failures, debugging
-When defining a new package (@pxref{Defining Packages}), you will
-probably find yourself spending some time debugging and tweaking the
-build until it succeeds. To do that, you need to operate the build
-commands yourself in an environment as close as possible to the one the
-build daemon uses.
address@hidden --no-substitutes
+Do not use substitutes for build products. That is, always build things
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
-To that end, the first thing to do is to use the @option{--keep-failed}
-or @option{-K} option of @command{guix build}, which will keep the
-failed build tree in @file{/tmp} or whatever directory you specified as
address@hidden (@pxref{Invoking guix build, @code{--keep-failed}}).
address@hidden --no-grafts
+Do not ``graft'' packages. In practice, this means that package updates
+available as grafts are not applied. @xref{Security Updates}, for more
+information on grafts.
-From there on, you can @command{cd} to the failed build tree and source
-the @file{environment-variables} file, which contains all the
-environment variable definitions that were in place when the build
-failed. So let's say you're debugging a build failure in package
address@hidden; a typical session would look like this:
address@hidden address@hidden
+Build each derivation @var{n} times in a row, and raise an error if
+consecutive build results are not bit-for-bit identical.
address@hidden
-$ guix build foo -K
address@hidden @i{build fails}
-$ cd /tmp/guix-build-foo.drv-0
-$ source ./environment-variables
-$ cd foo-1.2
address@hidden example
+This is a useful way to detect non-deterministic builds processes.
+Non-deterministic build processes are a problem because they make it
+practically impossible for users to @emph{verify} whether third-party
+binaries are genuine. @xref{Invoking guix challenge}, for more.
-Now, you can invoke commands as if you were the daemon (almost) and
-troubleshoot your build process.
+Note that, currently, the differing build results are not kept around,
+so you will have to manually investigate in case of an error---e.g., by
+stashing one of the build results with @code{guix archive --export}
+(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
+the two results.
-Sometimes it happens that, for example, a package's tests pass when you
-run them manually but they fail when the daemon runs them. This can
-happen because the daemon runs builds in containers where, unlike in our
-environment above, network access is missing, @file{/bin/sh} does not
-exist, etc. (@pxref{Build Environment Setup}).
address@hidden --no-build-hook
+Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
+(@pxref{Daemon Offload Setup}). That is, always build things locally
+instead of offloading builds to remote machines.
-In such cases, you may need to run inspect the build process from within
-a container similar to the one the build daemon creates:
address@hidden address@hidden
+When the build or substitution process remains silent for more than
address@hidden, terminate it and report a build failure.
address@hidden
-$ guix build -K foo
address@hidden
-$ cd /tmp/guix-build-foo.drv-0
-$ guix environment --no-grafts -C foo --ad-hoc strace gdb
-[env]# source ./environment-variables
-[env]# cd foo-1.2
address@hidden example
+By default, the daemon's setting is honored (@pxref{Invoking
+guix-daemon, @code{--max-silent-time}}).
-Here, @command{guix environment -C} creates a container and spawns a new
-shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
-strace gdb} part adds the @command{strace} and @command{gdb} commands to
-the container, which would may find handy while debugging. The
address@hidden option makes sure we get the exact same
-environment, with ungrafted packages (@pxref{Security Updates}, for more
-info on grafts).
address@hidden address@hidden
+Likewise, when the build or substitution process lasts for more than
address@hidden, terminate it and report a build failure.
-To get closer to a container like that used by the build daemon, we can
-remove @file{/bin/sh}:
+By default, the daemon's setting is honored (@pxref{Invoking
+guix-daemon, @code{--timeout}}).
address@hidden
-[env]# rm /bin/sh
address@hidden example
address@hidden Note: This option is actually not part of
%standard-build-options but
address@hidden most programs honor it.
address@hidden verbosity, of the command-line tools
address@hidden build logs, verbosity
address@hidden -v @var{level}
address@hidden address@hidden
+Use the given verbosity @var{level}, an integer. Choosing 0 means that no
+output is produced, 1 is for quiet output, and 2 shows all the build log
+output on standard error.
-(Don't worry, this is harmless: this is all happening in the throw-away
-container created by @command{guix environment}.)
address@hidden address@hidden
address@hidden -c @var{n}
+Allow the use of up to @var{n} CPU cores for the build. The special
+value @code{0} means to use as many CPU cores as available.
-The @command{strace} command is probably not in the search path, but we
-can run:
address@hidden address@hidden
address@hidden -M @var{n}
+Allow at most @var{n} build jobs in parallel. @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
address@hidden
-[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
address@hidden example
address@hidden address@hidden
+Produce debugging output coming from the build daemon. @var{level} must be an
+integer between 0 and 5; higher means more verbose output. Setting a level of
+4 or more may be helpful when debugging setup issues with the build daemon.
-In this way, not only you will have reproduced the environment variables
-the daemon uses, you will also be running the build process in a container
-similar to the one the daemon uses.
address@hidden table
+Behind the scenes, @command{guix build} is essentially an interface to
+the @code{package-derivation} procedure of the @code{(guix packages)}
+module, and to the @code{build-derivations} procedure of the @code{(guix
+derivations)} module.
address@hidden Invoking guix edit
address@hidden Invoking @command{guix edit}
+In addition to options explicitly passed on the command line,
address@hidden build} and other @command{guix} commands that support
+building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
address@hidden @command{guix edit}
address@hidden package definition, editing
-So many packages, so many source files! The @command{guix edit} command
-facilitates the life of users and packagers by pointing their editor at
-the source file containing the definition of the specified packages.
-For instance:
address@hidden {Environment Variable} GUIX_BUILD_OPTIONS
+Users can define this variable to a list of command line options that
+will automatically be used by @command{guix build} and other
address@hidden commands that can perform builds, as in the example
+below:
@example
-guix edit gcc@@4.9 vim
+$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example
address@hidden
-launches the program specified in the @code{VISUAL} or in the
address@hidden environment variable to view the recipe of address@hidden
-and that of Vim.
+These options are parsed independently, and the result is appended to
+the parsed command-line options.
address@hidden defvr
-If you are using a Guix Git checkout (@pxref{Building from Git}), or
-have created your own packages on @code{GUIX_PACKAGE_PATH}
-(@pxref{Package Modules}), you will be able to edit the package
-recipes. In other cases, you will be able to examine the read-only recipes
-for packages currently in the store.
address@hidden Package Transformation Options
address@hidden Package Transformation Options
address@hidden Invoking guix download
address@hidden Invoking @command{guix download}
address@hidden package variants
+Another set of command-line options supported by @command{guix build}
+and also @command{guix package} are @dfn{package transformation
+options}. These are options that make it possible to define @dfn{package
+variants}---for instance, packages built from different source code.
+This is a convenient way to create customized packages on the fly
+without having to type in the definitions of package variants
+(@pxref{Defining Packages}).
address@hidden @command{guix download}
address@hidden downloading package sources
-When writing a package definition, developers typically need to download
-a source tarball, compute its SHA256 hash, and write that
-hash in the package definition (@pxref{Defining Packages}). The
address@hidden download} tool helps with this task: it downloads a file
-from the given URI, adds it to the store, and prints both its file name
-in the store and its SHA256 hash.
address@hidden @code
-The fact that the downloaded file is added to the store saves bandwidth:
-when the developer eventually tries to build the newly defined package
-with @command{guix build}, the source tarball will not have to be
-downloaded again because it is already in the store. It is also a
-convenient way to temporarily stash files, which may be deleted
-eventually (@pxref{Invoking guix gc}).
address@hidden address@hidden
address@hidden address@hidden@var{source}
address@hidden address@hidden@@@address@hidden
+Use @var{source} as the source of @var{package}, and @var{version} as
+its version number.
address@hidden must be a file name or a URL, as for @command{guix
+download} (@pxref{Invoking guix download}).
-The @command{guix download} command supports the same URIs as used in
-package definitions. In particular, it supports @code{mirror://} URIs.
address@hidden URIs (HTTP over TLS) are supported @emph{provided} the
-Guile bindings for GnuTLS are available in the user's environment; when
-they are not available, an error is raised. @xref{Guile Preparations,
-how to install the GnuTLS bindings for Guile,, gnutls-guile,
-GnuTLS-Guile}, for more information.
+When @var{package} is omitted,
+it is taken to be the package name specified on the
+command line that matches the base of @var{source}---e.g.,
+if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
+package is @code{guile}.
address@hidden download} verifies HTTPS server certificates by loading
-the certificates of X.509 authorities from the directory pointed to by
-the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
-Certificates}), unless @option{--no-check-certificate} is used.
+Likewise, when @var{version} is omitted, the version string is inferred from
address@hidden; in the previous example, it is @code{2.0.10}.
-The following options are available:
+This option allows users to try out versions of packages other than the
+one provided by the distribution. The example below downloads
address@hidden from a GNU mirror and uses that as the source for
+the @code{ed} package:
address@hidden @code
address@hidden address@hidden
address@hidden -f @var{fmt}
-Write the hash in the format specified by @var{fmt}. For more
-information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
address@hidden
+guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
address@hidden example
address@hidden --no-check-certificate
-Do not validate the X.509 certificates of HTTPS servers.
+As a developer, @code{--with-source} makes it easy to test release
+candidates:
-When using this option, you have @emph{absolutely no guarantee} that you
-are communicating with the authentic server responsible for the given
-URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
address@hidden
+guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
address@hidden example
address@hidden address@hidden
address@hidden -o @var{file}
-Save the downloaded file to @var{file} instead of adding it to the
-store.
address@hidden table
address@hidden or to build from a checkout in a pristine environment:
address@hidden Invoking guix hash
address@hidden Invoking @command{guix hash}
address@hidden
+$ git clone git://git.sv.gnu.org/guix.git
+$ guix build guix --with-source=guix@@1.0=./guix
address@hidden example
address@hidden @command{guix hash}
-The @command{guix hash} command computes the SHA256 hash of a file.
-It is primarily a convenience tool for anyone contributing to the
-distribution: it computes the cryptographic hash of a file, which can be
-used in the definition of a package (@pxref{Defining Packages}).
address@hidden address@hidden@var{replacement}
+Replace dependency on @var{package} by a dependency on
address@hidden @var{package} must be a package name, and
address@hidden must be a package specification such as @code{guile}
+or @code{guile@@1.8}.
-The general syntax is:
+For instance, the following command builds Guix, but replaces its
+dependency on the current stable version of Guile with a dependency on
+the legacy version of Guile, @code{guile@@2.0}:
@example
-guix hash @var{option} @var{file}
+guix build --with-input=guile=guile@@2.0 guix
@end example
-When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
-hash of data read from standard input. @command{guix hash} has the
-following options:
-
address@hidden @code
+This is a recursive, deep replacement. So in this example, both
address@hidden and its dependency @code{guile-json} (which also depends on
address@hidden) get rebuilt against @code{guile@@2.0}.
address@hidden address@hidden
address@hidden -f @var{fmt}
-Write the hash in the format specified by @var{fmt}.
+This is implemented using the @code{package-input-rewriting} Scheme
+procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
-Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
-(@code{hex} and @code{hexadecimal} can be used as well).
address@hidden address@hidden@var{replacement}
+This is similar to @code{--with-input} but with an important difference:
+instead of rebuilding the whole dependency chain, @var{replacement} is
+built and then @dfn{grafted} onto the binaries that were initially
+referring to @var{package}. @xref{Security Updates}, for more
+information on grafts.
-If the @option{--format} option is not specified, @command{guix hash}
-will output the hash in @code{nix-base32}. This representation is used
-in the definitions of packages.
+For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
+and all its dependencies, replacing references to the version of GnuTLS
+they currently refer to:
address@hidden --recursive
address@hidden -r
-Compute the hash on @var{file} recursively.
address@hidden
+guix build --with-graft=gnutls=gnutls@@3.5.4 wget
address@hidden example
-In this case, the hash is computed on an archive containing @var{file},
-including its children if it is a directory. Some of the metadata of
address@hidden is part of the archive; for instance, when @var{file} is a
-regular file, the hash is different depending on whether @var{file} is
-executable or not. Metadata such as time stamps has no impact on the
-hash (@pxref{Invoking guix archive}).
address@hidden FIXME: Replace xref above with xref to an ``Archive'' section
when
address@hidden it exists.
+This has the advantage of being much faster than rebuilding everything.
+But there is a caveat: it works if and only if @var{package} and
address@hidden are strictly compatible---for example, if they provide
+a library, the application binary interface (ABI) of those libraries
+must be compatible. If @var{replacement} is somehow incompatible with
address@hidden, then the resulting package may be unusable. Use with
+care!
address@hidden --exclude-vcs
address@hidden -x
-When combined with @option{--recursive}, exclude version control system
-directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
address@hidden address@hidden@var{branch}
address@hidden Git, using the latest commit
address@hidden latest commit, building
+Build @var{package} from the latest commit of @var{branch}. The @code{source}
+field of @var{package} must be an origin with the @code{git-fetch} method
+(@pxref{origin Reference}) or a @code{git-checkout} object; the repository URL
+is taken from that @code{source}. Git sub-modules of the repository are
+fetched, recursively.
address@hidden git-fetch
-As an example, here is how you would compute the hash of a Git checkout,
-which is useful when using the @code{git-fetch} method (@pxref{origin
-Reference}):
+For instance, the following command builds @code{guile-sqlite3} from the
+latest commit of its @code{master} branch, and then builds @code{guix} (which
+depends on it) and @code{cuirass} (which depends on @code{guix}) against this
+specific @code{guile-sqlite3} build:
@example
-$ git clone http://example.org/foo.git
-$ cd foo
-$ guix hash -rx .
+guix build --with-branch=guile-sqlite3=master cuirass
@end example
address@hidden table
address@hidden Invoking guix import
address@hidden Invoking @command{guix import}
address@hidden continuous integration
+Obviously, since it uses the latest commit of the given branch, the result of
+such a command varies over time. Nevertheless it is a convenient way to
+rebuild entire software stacks against the latest commit of one or more
+packages. This is particularly useful in the context of continuous
+integration (CI).
address@hidden importing packages
address@hidden package import
address@hidden package conversion
address@hidden Invoking @command{guix import}
-The @command{guix import} command is useful for people who would like to
-add a package to the distribution with as little work as
-possible---a legitimate demand. The command knows of a few
-repositories from which it can ``import'' package metadata. The result
-is a package definition, or a template thereof, in the format we know
-(@pxref{Defining Packages}).
+Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
+consecutive accesses to the same repository. You may want to clean it up once
+in a while to save disk space.
-The general syntax is:
address@hidden address@hidden@var{commit}
+This is similar to @code{--with-branch}, except that it builds from
address@hidden rather than the tip of a branch. @var{commit} must be a valid
+Git commit SHA1 identifier.
address@hidden table
address@hidden
-guix import @var{importer} @address@hidden
address@hidden example
address@hidden Additional Build Options
address@hidden Additional Build Options
address@hidden specifies the source from which to import package
-metadata, and @var{options} specifies a package identifier and other
-options specific to @var{importer}. Currently, the available
-``importers'' are:
+The command-line options presented below are specific to @command{guix
+build}.
@table @code
address@hidden gnu
-Import metadata for the given GNU package. This provides a template
-for the latest version of that GNU package, including the hash of its
-source tarball, and its canonical synopsis and description.
-Additional information such as the package dependencies and its
-license needs to be figured out manually.
address@hidden --quiet
address@hidden -q
+Build quietly, without displaying the build log; this is equivalent to
address@hidden Upon completion, the build log is kept in @file{/var}
+(or similar) and can always be retrieved using the @option{--log-file} option.
-For example, the following command returns a package definition for
address@hidden:
address@hidden address@hidden
address@hidden -f @var{file}
+Build the package, derivation, or other file-like object that the code within
address@hidden evaluates to (@pxref{G-Expressions, file-like objects}).
+
+As an example, @var{file} might contain a package definition like this
+(@pxref{Defining Packages}):
@example
-guix import gnu hello
address@hidden package-hello.scm
@end example
-Specific command-line options are:
-
address@hidden @code
address@hidden address@hidden
-As for @code{guix refresh}, specify the policy to handle missing OpenPGP
-keys when verifying the package signature. @xref{Invoking guix
-refresh, @code{--key-download}}.
address@hidden table
address@hidden address@hidden
address@hidden -e @var{expr}
+Build the package or derivation @var{expr} evaluates to.
address@hidden pypi
address@hidden pypi
-Import metadata from the @uref{https://pypi.python.org/, Python Package
-Index}. Information is taken from the JSON-formatted description
-available at @code{pypi.python.org} and usually includes all the relevant
-information, including package dependencies. For maximum efficiency, it
-is recommended to install the @command{unzip} utility, so that the
-importer can unzip Python wheels and gather data from them.
+For example, @var{expr} may be @code{(@@ (gnu packages guile)
+guile-1.8)}, which unambiguously designates this specific variant of
+version 1.8 of Guile.
-The command below imports metadata for the @code{itsdangerous} Python
-package:
+Alternatively, @var{expr} may be a G-expression, in which case it is used
+as a build program passed to @code{gexp->derivation}
+(@pxref{G-Expressions}).
address@hidden
-guix import pypi itsdangerous
address@hidden example
+Lastly, @var{expr} may refer to a zero-argument monadic procedure
+(@pxref{The Store Monad}). The procedure must return a derivation as a
+monadic value, which is then passed through @code{run-with-store}.
address@hidden @code
address@hidden --recursive
address@hidden -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
address@hidden table
address@hidden --source
address@hidden -S
+Build the source derivations of the packages, rather than the packages
+themselves.
address@hidden gem
address@hidden gem
-Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
-is taken from the JSON-formatted description available at
address@hidden and includes most relevant information, including
-runtime dependencies. There are some caveats, however. The metadata
-doesn't distinguish between synopses and descriptions, so the same string
-is used for both fields. Additionally, the details of non-Ruby
-dependencies required to build native extensions is unavailable and left
-as an exercise to the packager.
+For instance, @code{guix build -S gcc} returns something like
address@hidden/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
+source tarball.
-The command below imports metadata for the @code{rails} Ruby package:
+The returned source tarball is the result of applying any patches and
+code snippets specified in the package @code{origin} (@pxref{Defining
+Packages}).
address@hidden
-guix import gem rails
address@hidden example
address@hidden --sources
+Fetch and return the source of @var{package-or-derivation} and all their
+dependencies, recursively. This is a handy way to obtain a local copy
+of all the source code needed to build @var{packages}, allowing you to
+eventually build them even without network access. It is an extension
+of the @code{--source} option and can accept one of the following
+optional argument values:
@table @code
address@hidden --recursive
address@hidden -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
address@hidden table
address@hidden package
+This value causes the @code{--sources} option to behave in the same way
+as the @code{--source} option.
address@hidden cpan
address@hidden CPAN
-Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
-Information is taken from the JSON-formatted metadata provided through
address@hidden://fastapi.metacpan.org/, MetaCPAN's API} and includes most
-relevant information, such as module dependencies. License information
-should be checked closely. If Perl is available in the store, then the
address@hidden utility will be used to filter core modules out of the
-list of dependencies.
address@hidden all
+Build the source derivations of all packages, including any source that
+might be listed as @code{inputs}. This is the default value.
-The command command below imports metadata for the @code{Acme::Boolean}
-Perl module:
address@hidden
+$ guix build --sources tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
address@hidden example
+
address@hidden transitive
+Build the source derivations of all packages, as well of all transitive
+inputs to the packages. This can be used e.g.@: to
+prefetch package source for later offline building.
@example
-guix import cpan Acme::Boolean
+$ guix build --sources=transitive tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+ /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
+ /gnu/store/@dots{}-grep-2.21.tar.xz.drv
+ /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
+ /gnu/store/@dots{}-make-4.1.tar.xz.drv
+ /gnu/store/@dots{}-bash-4.3.tar.xz.drv
address@hidden
@end example
address@hidden cran
address@hidden CRAN
address@hidden Bioconductor
-Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
-central repository for the @uref{http://r-project.org, address@hidden
-statistical and graphical environment}.
address@hidden table
-Information is extracted from the @code{DESCRIPTION} file of the package.
address@hidden address@hidden
address@hidden -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
+the system type of the build host.
-The command command below imports metadata for the @code{Cairo}
-R package:
address@hidden Note
+The @code{--system} flag is for @emph{native} compilation and must not
+be confused with cross-compilation. See @code{--target} below for
+information on cross-compilation.
address@hidden quotation
address@hidden
-guix import cran Cairo
address@hidden example
+An example use of this is on Linux-based systems, which can emulate
+different personalities. For instance, passing
address@hidden on an @code{x86_64-linux} system or
address@hidden on an @code{aarch64-linux} system allows you
+to build packages in a complete 32-bit environment.
-When @code{--recursive} is added, the importer will traverse the
-dependency graph of the given upstream package recursively and generate
-package expressions for all those packages that are not yet in Guix.
address@hidden Note
+Building for an @code{armhf-linux} system is unconditionally enabled on
address@hidden machines, although certain aarch64 chipsets do not
+allow for this functionality, notably the ThunderX.
address@hidden quotation
-When @code{--archive=bioconductor} is added, metadata is imported from
address@hidden://www.bioconductor.org/, Bioconductor}, a repository of R
-packages for for the analysis and comprehension of high-throughput
-genomic data in bioinformatics.
+Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
+is enabled (@pxref{Virtualization Services,
address@hidden), you can build for any system for
+which a QEMU @code{binfmt_misc} handler is installed.
-Information is extracted from the @code{DESCRIPTION} file of a package
-published on the web interface of the Bioconductor SVN repository.
+Builds for a system other than that of the machine you are using can
+also be offloaded to a remote machine of the right architecture.
address@hidden Offload Setup}, for more information on offloading.
-The command below imports metadata for the @code{GenomicRanges}
-R package:
address@hidden address@hidden
address@hidden cross-compilation
+Cross-build for @var{triplet}, which must be a valid GNU triplet, such
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+configuration triplets,, autoconf, Autoconf}).
+
address@hidden
address@hidden --check
address@hidden determinism, checking
address@hidden reproducibility, checking
+Rebuild @var{package-or-derivation}, which are already available in the
+store, and raise an error if the build results are not bit-for-bit
+identical.
address@hidden
-guix import cran --archive=bioconductor GenomicRanges
address@hidden example
+This mechanism allows you to check whether previously installed
+substitutes are genuine (@pxref{Substitutes}), or whether the build result
+of a package is deterministic. @xref{Invoking guix challenge}, for more
+background information and tools.
address@hidden texlive
address@hidden TeX Live
address@hidden CTAN
-Import metadata from @uref{http://www.ctan.org/, CTAN}, the
-comprehensive TeX archive network for TeX packages that are part of the
address@hidden://www.tug.org/texlive/, TeX Live distribution}.
+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.
-Information about the package is obtained through the XML API provided
-by CTAN, while the source code is downloaded from the SVN repository of
-the Tex Live project. This is done because the CTAN does not keep
-versioned archives.
address@hidden --repair
address@hidden repairing store items
address@hidden corruption, recovering from
+Attempt to repair the specified store items, if they are corrupt, by
+re-downloading or rebuilding them.
-The command command below imports metadata for the @code{fontspec}
-TeX package:
+This operation is not atomic and thus restricted to @code{root}.
address@hidden
-guix import texlive fontspec
address@hidden example
address@hidden --derivations
address@hidden -d
+Return the derivation paths, not the output paths, of the given
+packages.
-When @code{--archive=DIRECTORY} is added, the source code is downloaded
-not from the @file{latex} sub-directory of the @file{texmf-dist/source}
-tree in the TeX Live SVN repository, but from the specified sibling
-directory under the same root.
address@hidden address@hidden
address@hidden -r @var{file}
address@hidden GC roots, adding
address@hidden garbage collector roots, adding
+Make @var{file} a symlink to the result, and register it as a garbage
+collector root.
-The command below imports metadata for the @code{ifxetex} package from
-CTAN while fetching the sources from the directory
address@hidden/source/generic}:
+Consequently, the results of this @command{guix build} invocation are
+protected from garbage collection until @var{file} is removed. When
+that option is omitted, build results are eligible for garbage
+collection as soon as the build completes. @xref{Invoking guix gc}, for
+more on GC roots.
address@hidden
-guix import texlive --archive=generic ifxetex
address@hidden example
address@hidden --log-file
address@hidden build logs, access
+Return the build log file names or URLs for the given
address@hidden, or raise an error if build logs are
+missing.
address@hidden json
address@hidden JSON, import
-Import package metadata from a local JSON file. Consider the following
-example package definition in JSON format:
+This works regardless of how packages or derivations are specified. For
+instance, the following invocations are equivalent:
@example
address@hidden
- "name": "hello",
- "version": "2.10",
- "source": "mirror://gnu/hello/hello-2.10.tar.gz",
- "build-system": "gnu",
- "home-page": "https://www.gnu.org/software/hello/";,
- "synopsis": "Hello, GNU world: An example GNU package",
- "description": "GNU Hello prints a greeting.",
- "license": "GPL-3.0+",
- "native-inputs": ["gcc@@6"]
address@hidden
+guix build --log-file `guix build -d guile`
+guix build --log-file `guix build guile`
+guix build --log-file guile
+guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
-The field names are the same as for the @code{<package>} record
-(@xref{Defining Packages}). References to other packages are provided
-as JSON lists of quoted package specification strings such as
address@hidden or @code{guile@@2.0}.
+If a log is unavailable locally, and unless @code{--no-substitutes} is
+passed, the command looks for a corresponding log on one of the
+substitute servers (as specified with @code{--substitute-urls}.)
-The importer also supports a more explicit source definition using the
-common fields for @code{<origin>} records:
+So for instance, imagine you want to see the build log of GDB on MIPS,
+but you are actually on an @code{x86_64} machine:
@example
address@hidden
- @dots{}
- "source": @{
- "method": "url-fetch",
- "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
- "sha256": @{
- "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
- @}
- @}
- @dots{}
address@hidden
+$ guix build --log-file gdb -s mips64el-linux
+https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
@end example
-The command below reads metadata from the JSON file @code{hello.json}
-and outputs a package expression:
+You can freely access a huge library of build logs!
address@hidden table
address@hidden
-guix import json hello.json
address@hidden example
address@hidden Debugging Build Failures
address@hidden Debugging Build Failures
address@hidden nix
-Import metadata from a local copy of the source of the
address@hidden://nixos.org/nixpkgs/, Nixpkgs address@hidden
-relies on the @command{nix-instantiate} command of
address@hidden://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
-typically written in a mixture of Nix-language and Bash code. This
-command only imports the high-level package structure that is written in
-the Nix language. It normally includes all the basic fields of a
-package definition.
address@hidden build failures, debugging
+When defining a new package (@pxref{Defining Packages}), you will
+probably find yourself spending some time debugging and tweaking the
+build until it succeeds. To do that, you need to operate the build
+commands yourself in an environment as close as possible to the one the
+build daemon uses.
-When importing a GNU package, the synopsis and descriptions are replaced
-by their canonical upstream variant.
+To that end, the first thing to do is to use the @option{--keep-failed}
+or @option{-K} option of @command{guix build}, which will keep the
+failed build tree in @file{/tmp} or whatever directory you specified as
address@hidden (@pxref{Invoking guix build, @code{--keep-failed}}).
-Usually, you will first need to do:
+From there on, you can @command{cd} to the failed build tree and source
+the @file{environment-variables} file, which contains all the
+environment variable definitions that were in place when the build
+failed. So let's say you're debugging a build failure in package
address@hidden; a typical session would look like this:
@example
-export NIX_REMOTE=daemon
+$ guix build foo -K
address@hidden @i{build fails}
+$ cd /tmp/guix-build-foo.drv-0
+$ source ./environment-variables
+$ cd foo-1.2
@end example
address@hidden
-so that @command{nix-instantiate} does not try to open the Nix database.
+Now, you can invoke commands as if you were the daemon (almost) and
+troubleshoot your build process.
-As an example, the command below imports the package definition of
-LibreOffice (more precisely, it imports the definition of the package
-bound to the @code{libreoffice} top-level attribute):
+Sometimes it happens that, for example, a package's tests pass when you
+run them manually but they fail when the daemon runs them. This can
+happen because the daemon runs builds in containers where, unlike in our
+environment above, network access is missing, @file{/bin/sh} does not
+exist, etc. (@pxref{Build Environment Setup}).
+
+In such cases, you may need to run inspect the build process from within
+a container similar to the one the build daemon creates:
@example
-guix import nix ~/path/to/nixpkgs libreoffice
+$ guix build -K foo
address@hidden
+$ cd /tmp/guix-build-foo.drv-0
+$ guix environment --no-grafts -C foo --ad-hoc strace gdb
+[env]# source ./environment-variables
+[env]# cd foo-1.2
@end example
address@hidden hackage
address@hidden hackage
-Import metadata from the Haskell community's central package archive
address@hidden://hackage.haskell.org/, Hackage}. Information is taken from
-Cabal files and includes all the relevant information, including package
-dependencies.
-
-Specific command-line options are:
-
address@hidden @code
address@hidden --stdin
address@hidden -s
-Read a Cabal file from standard input.
address@hidden --no-test-dependencies
address@hidden -t
-Do not include dependencies required only by the test suites.
address@hidden address@hidden
address@hidden -e @var{alist}
address@hidden is a Scheme alist defining the environment in which the
-Cabal conditionals are evaluated. The accepted keys are: @code{os},
address@hidden, @code{impl} and a string representing the name of a flag.
-The value associated with a flag has to be either the symbol
address@hidden or @code{false}. The value associated with other keys
-has to conform to the Cabal file format definition. The default value
-associated with the keys @code{os}, @code{arch} and @code{impl} is
address@hidden, @samp{x86_64} and @samp{ghc}, respectively.
address@hidden --recursive
address@hidden -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
address@hidden table
+Here, @command{guix environment -C} creates a container and spawns a new
+shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
+strace gdb} part adds the @command{strace} and @command{gdb} commands to
+the container, which would may find handy while debugging. The
address@hidden option makes sure we get the exact same
+environment, with ungrafted packages (@pxref{Security Updates}, for more
+info on grafts).
-The command below imports metadata for the latest version of the
address@hidden Haskell package without including test dependencies and
-specifying the value of the flag @samp{network-uri} as @code{false}:
+To get closer to a container like that used by the build daemon, we can
+remove @file{/bin/sh}:
@example
-guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
+[env]# rm /bin/sh
@end example
-A specific package version may optionally be specified by following the
-package name by an at-sign and a version number as in the following example:
+(Don't worry, this is harmless: this is all happening in the throw-away
+container created by @command{guix environment}.)
+
+The @command{strace} command is probably not in the search path, but we
+can run:
@example
-guix import hackage mtl@@2.1.3.1
+[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
@end example
address@hidden stackage
address@hidden stackage
-The @code{stackage} importer is a wrapper around the @code{hackage} one.
-It takes a package name, looks up the package version included in a
-long-term support (LTS) @uref{https://www.stackage.org, Stackage}
-release and uses the @code{hackage} importer to retrieve its metadata.
-Note that it is up to you to select an LTS release compatible with the
-GHC compiler used by Guix.
+In this way, not only you will have reproduced the environment variables
+the daemon uses, you will also be running the build process in a container
+similar to the one the daemon uses.
-Specific command-line options are:
address@hidden @code
address@hidden --no-test-dependencies
address@hidden -t
-Do not include dependencies required only by the test suites.
address@hidden address@hidden
address@hidden -l @var{version}
address@hidden is the desired LTS release version. If omitted the latest
-release is used.
address@hidden --recursive
address@hidden -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
address@hidden table
address@hidden Invoking guix edit
address@hidden Invoking @command{guix edit}
-The command below imports metadata for the @code{HTTP} Haskell package
-included in the LTS Stackage release version 7.18:
address@hidden @command{guix edit}
address@hidden package definition, editing
+So many packages, so many source files! The @command{guix edit} command
+facilitates the life of users and packagers by pointing their editor at
+the source file containing the definition of the specified packages.
+For instance:
@example
-guix import stackage --lts-version=7.18 HTTP
+guix edit gcc@@4.9 vim
@end example
address@hidden elpa
address@hidden elpa
-Import metadata from an Emacs Lisp Package Archive (ELPA) package
-repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
address@hidden
+launches the program specified in the @code{VISUAL} or in the
address@hidden environment variable to view the recipe of address@hidden
+and that of Vim.
-Specific command-line options are:
+If you are using a Guix Git checkout (@pxref{Building from Git}), or
+have created your own packages on @code{GUIX_PACKAGE_PATH}
+(@pxref{Package Modules}), you will be able to edit the package
+recipes. In other cases, you will be able to examine the read-only recipes
+for packages currently in the store.
address@hidden @code
address@hidden address@hidden
address@hidden -a @var{repo}
address@hidden identifies the archive repository from which to retrieve the
-information. Currently the supported repositories and their identifiers
-are:
address@hidden -
address@hidden
address@hidden://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
-identifier. This is the default.
-Packages from @code{elpa.gnu.org} are signed with one of the keys
-contained in the GnuPG keyring at
address@hidden/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
address@hidden package (@pxref{Package Installation, ELPA package
-signatures,, emacs, The GNU Emacs Manual}).
address@hidden Invoking guix download
address@hidden Invoking @command{guix download}
address@hidden
address@hidden://stable.melpa.org/packages, MELPA-Stable}, selected by the
address@hidden identifier.
address@hidden @command{guix download}
address@hidden downloading package sources
+When writing a package definition, developers typically need to download
+a source tarball, compute its SHA256 hash, and write that
+hash in the package definition (@pxref{Defining Packages}). The
address@hidden download} tool helps with this task: it downloads a file
+from the given URI, adds it to the store, and prints both its file name
+in the store and its SHA256 hash.
address@hidden
address@hidden://melpa.org/packages, MELPA}, selected by the @code{melpa}
-identifier.
address@hidden itemize
+The fact that the downloaded file is added to the store saves bandwidth:
+when the developer eventually tries to build the newly defined package
+with @command{guix build}, the source tarball will not have to be
+downloaded again because it is already in the store. It is also a
+convenient way to temporarily stash files, which may be deleted
+eventually (@pxref{Invoking guix gc}).
address@hidden --recursive
address@hidden -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
address@hidden table
+The @command{guix download} command supports the same URIs as used in
+package definitions. In particular, it supports @code{mirror://} URIs.
address@hidden URIs (HTTP over TLS) are supported @emph{provided} the
+Guile bindings for GnuTLS are available in the user's environment; when
+they are not available, an error is raised. @xref{Guile Preparations,
+how to install the GnuTLS bindings for Guile,, gnutls-guile,
+GnuTLS-Guile}, for more information.
address@hidden crate
address@hidden crate
-Import metadata from the crates.io Rust package repository
address@hidden://crates.io, crates.io}.
address@hidden download} verifies HTTPS server certificates by loading
+the certificates of X.509 authorities from the directory pointed to by
+the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
+Certificates}), unless @option{--no-check-certificate} is used.
address@hidden opam
address@hidden OPAM
address@hidden OCaml
-Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
-repository used by the OCaml community.
address@hidden table
+The following options are available:
-The structure of the @command{guix import} code is modular. It would be
-useful to have more importers for other package formats, and your help
-is welcome here (@pxref{Contributing}).
address@hidden @code
address@hidden address@hidden
address@hidden -f @var{fmt}
+Write the hash in the format specified by @var{fmt}. For more
+information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
address@hidden Invoking guix refresh
address@hidden Invoking @command{guix refresh}
address@hidden --no-check-certificate
+Do not validate the X.509 certificates of HTTPS servers.
address@hidden @command {guix refresh}
-The primary audience of the @command{guix refresh} command is developers
-of the GNU software distribution. By default, it reports any packages
-provided by the distribution that are outdated compared to the latest
-upstream version, like this:
+When using this option, you have @emph{absolutely no guarantee} that you
+are communicating with the authentic server responsible for the given
+URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
address@hidden
-$ guix refresh
-gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to
0.18.2.1
-gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
address@hidden example
address@hidden address@hidden
address@hidden -o @var{file}
+Save the downloaded file to @var{file} instead of adding it to the
+store.
address@hidden table
-Alternately, one can specify packages to consider, in which case a
-warning is emitted for packages that lack an updater:
address@hidden Invoking guix hash
address@hidden Invoking @command{guix hash}
+
address@hidden @command{guix hash}
+The @command{guix hash} command computes the SHA256 hash of a file.
+It is primarily a convenience tool for anyone contributing to the
+distribution: it computes the cryptographic hash of a file, which can be
+used in the definition of a package (@pxref{Defining Packages}).
+
+The general syntax is:
@example
-$ guix refresh coreutils guile guile-ssh
-gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
-gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
+guix hash @var{option} @var{file}
@end example
address@hidden refresh} browses the upstream repository of each package and
determines
-the highest version number of the releases therein. The command
-knows how to update specific types of packages: GNU packages, ELPA
-packages, etc.---see the documentation for @option{--type} below. There
-are many packages, though, for which it lacks a method to determine
-whether a new upstream release is available. However, the mechanism is
-extensible, so feel free to get in touch with us to add a new method!
+When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
+hash of data read from standard input. @command{guix hash} has the
+following options:
@table @code
address@hidden address@hidden
address@hidden -f @var{fmt}
+Write the hash in the format specified by @var{fmt}.
+
+Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+(@code{hex} and @code{hexadecimal} can be used as well).
+
+If the @option{--format} option is not specified, @command{guix hash}
+will output the hash in @code{nix-base32}. This representation is used
+in the definitions of packages.
+
@item --recursive
-Consider the packages specified, and all the packages upon which they depend.
address@hidden -r
+Compute the hash on @var{file} recursively.
+
+In this case, the hash is computed on an archive containing @var{file},
+including its children if it is a directory. Some of the metadata of
address@hidden is part of the archive; for instance, when @var{file} is a
+regular file, the hash is different depending on whether @var{file} is
+executable or not. Metadata such as time stamps has no impact on the
+hash (@pxref{Invoking guix archive}).
address@hidden FIXME: Replace xref above with xref to an ``Archive'' section
when
address@hidden it exists.
+
address@hidden --exclude-vcs
address@hidden -x
+When combined with @option{--recursive}, exclude version control system
+directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
+
address@hidden git-fetch
+As an example, here is how you would compute the hash of a Git checkout,
+which is useful when using the @code{git-fetch} method (@pxref{origin
+Reference}):
@example
-$ guix refresh --recursive coreutils
-gnu/packages/acl.scm:35:2: warning: no updater for acl
-gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
-gnu/packages/xml.scm:68:2: warning: no updater for expat
-gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest
version of gmp
address@hidden
+$ git clone http://example.org/foo.git
+$ cd foo
+$ guix hash -rx .
@end example
-
@end table
-Sometimes the upstream name differs from the package name used in Guix,
-and @command{guix refresh} needs a little help. Most updaters honor the
address@hidden property in package definitions, which can be used
-to that effect:
address@hidden Invoking guix import
address@hidden Invoking @command{guix import}
+
address@hidden importing packages
address@hidden package import
address@hidden package conversion
address@hidden Invoking @command{guix import}
+The @command{guix import} command is useful for people who would like to
+add a package to the distribution with as little work as
+possible---a legitimate demand. The command knows of a few
+repositories from which it can ``import'' package metadata. The result
+is a package definition, or a template thereof, in the format we know
+(@pxref{Defining Packages}).
+
+The general syntax is:
@example
-(define-public network-manager
- (package
- (name "network-manager")
- ;; @dots{}
- (properties '((upstream-name . "NetworkManager")))))
+guix import @var{importer} @address@hidden
@end example
-When passed @code{--update}, it modifies distribution source files to
-update the version numbers and source tarball hashes of those package
-recipes (@pxref{Defining Packages}). This is achieved by downloading
-each package's latest source tarball and its associated OpenPGP
-signature, authenticating the downloaded tarball against its signature
-using @command{gpg}, and finally computing its hash. When the public
-key used to sign the tarball is missing from the user's keyring, an
-attempt is made to automatically retrieve it from a public key server;
-when this is successful, the key is added to the user's keyring; otherwise,
address@hidden refresh} reports an error.
-
-The following options are supported:
address@hidden specifies the source from which to import package
+metadata, and @var{options} specifies a package identifier and other
+options specific to @var{importer}. Currently, the available
+``importers'' are:
@table @code
address@hidden gnu
+Import metadata for the given GNU package. This provides a template
+for the latest version of that GNU package, including the hash of its
+source tarball, and its canonical synopsis and description.
address@hidden address@hidden
address@hidden -e @var{expr}
-Consider the package @var{expr} evaluates to.
+Additional information such as the package dependencies and its
+license needs to be figured out manually.
-This is useful to precisely refer to a package, as in this example:
+For example, the following command returns a package definition for
address@hidden:
@example
-guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
+guix import gnu hello
@end example
-This command lists the dependents of the ``final'' libc (essentially all
-the packages.)
+Specific command-line options are:
+
address@hidden @code
address@hidden address@hidden
+As for @code{guix refresh}, specify the policy to handle missing OpenPGP
+keys when verifying the package signature. @xref{Invoking guix
+refresh, @code{--key-download}}.
address@hidden table
+
address@hidden pypi
address@hidden pypi
+Import metadata from the @uref{https://pypi.python.org/, Python Package
+Index}. Information is taken from the JSON-formatted description
+available at @code{pypi.python.org} and usually includes all the relevant
+information, including package dependencies. For maximum efficiency, it
+is recommended to install the @command{unzip} utility, so that the
+importer can unzip Python wheels and gather data from them.
address@hidden --update
address@hidden -u
-Update distribution source files (package recipes) in place. This is
-usually run from a checkout of the Guix source tree (@pxref{Running
-Guix Before It Is Installed}):
+The command below imports metadata for the @code{itsdangerous} Python
+package:
@example
-$ ./pre-inst-env guix refresh -s non-core -u
+guix import pypi itsdangerous
@end example
address@hidden Packages}, for more information on package definitions.
-
address@hidden address@hidden
address@hidden -s @var{subset}
-Select all the packages in @var{subset}, one of @code{core} or
address@hidden
-
-The @code{core} subset refers to all the packages at the core of the
-distribution---i.e., packages that are used to build ``everything
-else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
-changing one of these packages in the distribution entails a rebuild of
-all the others. Thus, such updates are an inconvenience to users in
-terms of build time or bandwidth used to achieve the upgrade.
address@hidden @code
address@hidden --recursive
address@hidden -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
address@hidden table
-The @code{non-core} subset refers to the remaining packages. It is
-typically useful in cases where an update of the core packages would be
-inconvenient.
address@hidden gem
address@hidden gem
+Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
+is taken from the JSON-formatted description available at
address@hidden and includes most relevant information, including
+runtime dependencies. There are some caveats, however. The metadata
+doesn't distinguish between synopses and descriptions, so the same string
+is used for both fields. Additionally, the details of non-Ruby
+dependencies required to build native extensions is unavailable and left
+as an exercise to the packager.
address@hidden address@hidden
address@hidden -m @var{file}
-Select all the packages from the manifest in @var{file}. This is useful to
-check if any packages of the user manifest can be updated.
+The command below imports metadata for the @code{rails} Ruby package:
address@hidden address@hidden
address@hidden -t @var{updater}
-Select only packages handled by @var{updater} (may be a comma-separated
-list of updaters). Currently, @var{updater} may be one of:
address@hidden
+guix import gem rails
address@hidden example
@table @code
address@hidden gnu
-the updater for GNU packages;
address@hidden gnome
-the updater for GNOME packages;
address@hidden kde
-the updater for KDE packages;
address@hidden xorg
-the updater for X.org packages;
address@hidden kernel.org
-the updater for packages hosted on kernel.org;
address@hidden elpa
-the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
address@hidden cran
-the updater for @uref{https://cran.r-project.org/, CRAN} packages;
address@hidden bioconductor
-the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
address@hidden cpan
-the updater for @uref{http://www.cpan.org/, CPAN} packages;
address@hidden pypi
-the updater for @uref{https://pypi.python.org, PyPI} packages.
address@hidden gem
-the updater for @uref{https://rubygems.org, RubyGems} packages.
address@hidden github
-the updater for @uref{https://github.com, GitHub} packages.
address@hidden hackage
-the updater for @uref{https://hackage.haskell.org, Hackage} packages.
address@hidden stackage
-the updater for @uref{https://www.stackage.org, Stackage} packages.
address@hidden crate
-the updater for @uref{https://crates.io, Crates} packages.
address@hidden --recursive
address@hidden -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
@end table
-For instance, the following command only checks for updates of Emacs
-packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
address@hidden cpan
address@hidden CPAN
+Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
+Information is taken from the JSON-formatted metadata provided through
address@hidden://fastapi.metacpan.org/, MetaCPAN's API} and includes most
+relevant information, such as module dependencies. License information
+should be checked closely. If Perl is available in the store, then the
address@hidden utility will be used to filter core modules out of the
+list of dependencies.
+
+The command command below imports metadata for the @code{Acme::Boolean}
+Perl module:
@example
-$ guix refresh --type=elpa,cran
-gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0
to 0.11.0
-gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to
11.88.9
+guix import cpan Acme::Boolean
@end example
address@hidden table
address@hidden cran
address@hidden CRAN
address@hidden Bioconductor
+Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
+central repository for the @uref{http://r-project.org, address@hidden
+statistical and graphical environment}.
-In addition, @command{guix refresh} can be passed one or more package
-names, as in this example:
+Information is extracted from the @code{DESCRIPTION} file of the package.
+
+The command command below imports metadata for the @code{Cairo}
+R package:
@example
-$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
+guix import cran Cairo
@end example
address@hidden
-The command above specifically updates the @code{emacs} and
address@hidden packages. The @code{--select} option would have no
-effect in this case.
-
-When considering whether to upgrade a package, it is sometimes
-convenient to know which packages would be affected by the upgrade and
-should be checked for compatibility. For this the following option may
-be used when passing @command{guix refresh} one or more package names:
+When @code{--recursive} is added, the importer will traverse the
+dependency graph of the given upstream package recursively and generate
+package expressions for all those packages that are not yet in Guix.
address@hidden @code
+When @code{--archive=bioconductor} is added, metadata is imported from
address@hidden://www.bioconductor.org/, Bioconductor}, a repository of R
+packages for for the analysis and comprehension of high-throughput
+genomic data in bioinformatics.
address@hidden --list-updaters
address@hidden -L
-List available updaters and exit (see @option{--type} above.)
+Information is extracted from the @code{DESCRIPTION} file of a package
+published on the web interface of the Bioconductor SVN repository.
-For each updater, display the fraction of packages it covers; at the
-end, display the fraction of packages covered by all these updaters.
+The command below imports metadata for the @code{GenomicRanges}
+R package:
address@hidden --list-dependent
address@hidden -l
-List top-level dependent packages that would need to be rebuilt as a
-result of upgrading one or more packages.
address@hidden
+guix import cran --archive=bioconductor GenomicRanges
address@hidden example
address@hidden guix graph, the @code{reverse-package} type of
address@hidden graph}}, for information on how to visualize the list of
-dependents of a package.
address@hidden texlive
address@hidden TeX Live
address@hidden CTAN
+Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+comprehensive TeX archive network for TeX packages that are part of the
address@hidden://www.tug.org/texlive/, TeX Live distribution}.
address@hidden table
+Information about the package is obtained through the XML API provided
+by CTAN, while the source code is downloaded from the SVN repository of
+the Tex Live project. This is done because the CTAN does not keep
+versioned archives.
-Be aware that the @code{--list-dependent} option only
address@hidden the rebuilds that would be required as a result of
-an upgrade. More rebuilds might be required under some circumstances.
+The command command below imports metadata for the @code{fontspec}
+TeX package:
@example
-$ guix refresh --list-dependent flex
-Building the following 120 packages would ensure 213 dependent packages are
rebuilt:
-hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6
@dots{}
+guix import texlive fontspec
@end example
-The command above lists a set of packages that could be built to check
-for compatibility with an upgraded @code{flex} package.
-
address@hidden @code
+When @code{--archive=DIRECTORY} is added, the source code is downloaded
+not from the @file{latex} sub-directory of the @file{texmf-dist/source}
+tree in the TeX Live SVN repository, but from the specified sibling
+directory under the same root.
address@hidden --list-transitive
-List all the packages which one or more packages depend upon.
+The command below imports metadata for the @code{ifxetex} package from
+CTAN while fetching the sources from the directory
address@hidden/source/generic}:
@example
-$ guix refresh --list-transitive flex
-flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
-bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4
file@@5.33 @dots{}
+guix import texlive --archive=generic ifxetex
@end example
address@hidden table
address@hidden json
address@hidden JSON, import
+Import package metadata from a local JSON file. Consider the following
+example package definition in JSON format:
-The command above lists a set of packages which, when changed, would cause
address@hidden to be rebuilt.
address@hidden
address@hidden
+ "name": "hello",
+ "version": "2.10",
+ "source": "mirror://gnu/hello/hello-2.10.tar.gz",
+ "build-system": "gnu",
+ "home-page": "https://www.gnu.org/software/hello/";,
+ "synopsis": "Hello, GNU world: An example GNU package",
+ "description": "GNU Hello prints a greeting.",
+ "license": "GPL-3.0+",
+ "native-inputs": ["gcc@@6"]
address@hidden
address@hidden example
-The following options can be used to customize GnuPG operation:
+The field names are the same as for the @code{<package>} record
+(@xref{Defining Packages}). References to other packages are provided
+as JSON lists of quoted package specification strings such as
address@hidden or @code{guile@@2.0}.
address@hidden @code
+The importer also supports a more explicit source definition using the
+common fields for @code{<origin>} records:
address@hidden address@hidden
-Use @var{command} as the GnuPG 2.x command. @var{command} is searched
-for in @code{$PATH}.
address@hidden
address@hidden
+ @dots{}
+ "source": @{
+ "method": "url-fetch",
+ "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
+ "sha256": @{
+ "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
+ @}
+ @}
+ @dots{}
address@hidden
address@hidden example
address@hidden address@hidden
-Use @var{file} as the keyring for upstream keys. @var{file} must be in the
address@hidden format}. Keybox files usually have a name ending in @file{.kbx}
-and the address@hidden Guard (GPG) can manipulate these files
-(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
-information on a tool to manipulate keybox files).
+The command below reads metadata from the JSON file @code{hello.json}
+and outputs a package expression:
+
address@hidden
+guix import json hello.json
address@hidden example
-When this option is omitted, @command{guix refresh} uses
address@hidden/.config/guix/upstream/trustedkeys.kbx} as the keyring for
upstream
-signing keys. OpenPGP signatures are checked against keys from this keyring;
-missing keys are downloaded to this keyring as well (see
address@hidden below.)
address@hidden nix
+Import metadata from a local copy of the source of the
address@hidden://nixos.org/nixpkgs/, Nixpkgs address@hidden
+relies on the @command{nix-instantiate} command of
address@hidden://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+typically written in a mixture of Nix-language and Bash code. This
+command only imports the high-level package structure that is written in
+the Nix language. It normally includes all the basic fields of a
+package definition.
-You can export keys from your default GPG keyring into a keybox file using
-commands like this one:
+When importing a GNU package, the synopsis and descriptions are replaced
+by their canonical upstream variant.
+
+Usually, you will first need to do:
@example
-gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
+export NIX_REMOTE=daemon
@end example
-Likewise, you can fetch keys to a specific keybox file like this:
address@hidden
+so that @command{nix-instantiate} does not try to open the Nix database.
+
+As an example, the command below imports the package definition of
+LibreOffice (more precisely, it imports the definition of the package
+bound to the @code{libreoffice} top-level attribute):
@example
-gpg --no-default-keyring --keyring mykeyring.kbx \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+guix import nix ~/path/to/nixpkgs libreoffice
@end example
address@hidden Configuration Options, @option{--keyring},, gnupg, Using the GNU
-Privacy Guard}, for more information on GPG's @option{--keyring} option.
address@hidden hackage
address@hidden hackage
+Import metadata from the Haskell community's central package archive
address@hidden://hackage.haskell.org/, Hackage}. Information is taken from
+Cabal files and includes all the relevant information, including package
+dependencies.
address@hidden address@hidden
-Handle missing OpenPGP keys according to @var{policy}, which may be one
-of:
+Specific command-line options are:
@table @code
address@hidden always
-Always download missing OpenPGP keys from the key server, and add them
-to the user's GnuPG keyring.
-
address@hidden never
-Never try to download missing OpenPGP keys. Instead just bail out.
-
address@hidden interactive
-When a package signed with an unknown OpenPGP key is encountered, ask
-the user whether to download it or not. This is the default behavior.
address@hidden --stdin
address@hidden -s
+Read a Cabal file from standard input.
address@hidden --no-test-dependencies
address@hidden -t
+Do not include dependencies required only by the test suites.
address@hidden address@hidden
address@hidden -e @var{alist}
address@hidden is a Scheme alist defining the environment in which the
+Cabal conditionals are evaluated. The accepted keys are: @code{os},
address@hidden, @code{impl} and a string representing the name of a flag.
+The value associated with a flag has to be either the symbol
address@hidden or @code{false}. The value associated with other keys
+has to conform to the Cabal file format definition. The default value
+associated with the keys @code{os}, @code{arch} and @code{impl} is
address@hidden, @samp{x86_64} and @samp{ghc}, respectively.
address@hidden --recursive
address@hidden -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
@end table
address@hidden address@hidden
-Use @var{host} as the OpenPGP key server when importing a public key.
+The command below imports metadata for the latest version of the
address@hidden Haskell package without including test dependencies and
+specifying the value of the flag @samp{network-uri} as @code{false}:
address@hidden table
address@hidden
+guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
address@hidden example
-The @code{github} updater uses the
address@hidden://developer.github.com/v3/, GitHub API} to query for new
-releases. When used repeatedly e.g.@: when refreshing all packages,
-GitHub will eventually refuse to answer any further API requests. By
-default 60 API requests per hour are allowed, and a full refresh on all
-GitHub packages in Guix requires more than this. Authentication with
-GitHub through the use of an API token alleviates these limits. To use
-an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
-token procured from @uref{https://github.com/settings/tokens} or
-otherwise.
+A specific package version may optionally be specified by following the
+package name by an at-sign and a version number as in the following example:
address@hidden
+guix import hackage mtl@@2.1.3.1
address@hidden example
address@hidden Invoking guix lint
address@hidden Invoking @command{guix lint}
address@hidden stackage
address@hidden stackage
+The @code{stackage} importer is a wrapper around the @code{hackage} one.
+It takes a package name, looks up the package version included in a
+long-term support (LTS) @uref{https://www.stackage.org, Stackage}
+release and uses the @code{hackage} importer to retrieve its metadata.
+Note that it is up to you to select an LTS release compatible with the
+GHC compiler used by Guix.
address@hidden @command{guix lint}
address@hidden package, checking for errors
-The @command{guix lint} command is meant to help package developers avoid
-common errors and use a consistent style. It runs a number of checks on
-a given set of packages in order to find common mistakes in their
-definitions. Available @dfn{checkers} include (see
address@hidden for a complete list):
+Specific command-line options are:
@table @code
address@hidden synopsis
address@hidden description
-Validate certain typographical and stylistic rules about package
-descriptions and synopses.
address@hidden --no-test-dependencies
address@hidden -t
+Do not include dependencies required only by the test suites.
address@hidden address@hidden
address@hidden -l @var{version}
address@hidden is the desired LTS release version. If omitted the latest
+release is used.
address@hidden --recursive
address@hidden -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
address@hidden table
address@hidden inputs-should-be-native
-Identify inputs that should most likely be native inputs.
+The command below imports metadata for the @code{HTTP} Haskell package
+included in the LTS Stackage release version 7.18:
address@hidden source
address@hidden home-page
address@hidden mirror-url
address@hidden github-url
address@hidden source-file-name
-Probe @code{home-page} and @code{source} URLs and report those that are
-invalid. Suggest a @code{mirror://} URL when applicable. If the
address@hidden URL redirects to a GitHub URL, recommend usage of the GitHub
-URL. Check that the source file name is meaningful, e.g.@: is not just a
-version number or ``git-checkout'', without a declared @code{file-name}
-(@pxref{origin Reference}).
address@hidden
+guix import stackage --lts-version=7.18 HTTP
address@hidden example
address@hidden source-unstable-tarball
-Parse the @code{source} URL to determine if a tarball from GitHub is
-autogenerated or if it is a release tarball. Unfortunately GitHub's
-autogenerated tarballs are sometimes regenerated.
address@hidden elpa
address@hidden elpa
+Import metadata from an Emacs Lisp Package Archive (ELPA) package
+repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
address@hidden cve
address@hidden security vulnerabilities
address@hidden CVE, Common Vulnerabilities and Exposures
-Report known vulnerabilities found in the Common Vulnerabilities and
-Exposures (CVE) databases of the current and past year
address@hidden://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
-NIST}.
+Specific command-line options are:
-To view information about a particular vulnerability, visit pages such as:
address@hidden @code
address@hidden address@hidden
address@hidden -a @var{repo}
address@hidden identifies the archive repository from which to retrieve the
+information. Currently the supported repositories and their identifiers
+are:
address@hidden -
address@hidden
address@hidden://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+identifier. This is the default.
+
+Packages from @code{elpa.gnu.org} are signed with one of the keys
+contained in the GnuPG keyring at
address@hidden/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
address@hidden package (@pxref{Package Installation, ELPA package
+signatures,, emacs, The GNU Emacs Manual}).
address@hidden
@item
address@hidden://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
address@hidden://stable.melpa.org/packages, MELPA-Stable}, selected by the
address@hidden identifier.
+
@item
address@hidden://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
address@hidden://melpa.org/packages, MELPA}, selected by the @code{melpa}
+identifier.
@end itemize
address@hidden
-where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
address@hidden
address@hidden --recursive
address@hidden -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
address@hidden table
-Package developers can specify in package recipes the
address@hidden://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
-name and version of the package when they differ from the name or version
-that Guix uses, as in this example:
address@hidden crate
address@hidden crate
+Import metadata from the crates.io Rust package repository
address@hidden://crates.io, crates.io}.
address@hidden
-(package
- (name "grub")
- ;; @dots{}
- ;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2")
- (cpe-version . "2.3")))
address@hidden example
address@hidden opam
address@hidden OPAM
address@hidden OCaml
+Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
+repository used by the OCaml community.
address@hidden table
address@hidden See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
-Some entries in the CVE database do not specify which version of a
-package they apply to, and would thus ``stick around'' forever. Package
-developers who found CVE alerts and verified they can be ignored can
-declare them as in this example:
+The structure of the @command{guix import} code is modular. It would be
+useful to have more importers for other package formats, and your help
+is welcome here (@pxref{Contributing}).
address@hidden
-(package
- (name "t1lib")
- ;; @dots{}
- ;; These CVEs no longer apply and can be safely ignored.
- (properties `((lint-hidden-cve . ("CVE-2011-0433"
- "CVE-2011-1553"
- "CVE-2011-1554"
- "CVE-2011-5244")))))
address@hidden example
address@hidden Invoking guix refresh
address@hidden Invoking @command{guix refresh}
address@hidden formatting
-Warn about obvious source code formatting issues: trailing white space,
-use of tabulations, etc.
address@hidden table
address@hidden @command {guix refresh}
+The primary audience of the @command{guix refresh} command is developers
+of the GNU software distribution. By default, it reports any packages
+provided by the distribution that are outdated compared to the latest
+upstream version, like this:
+
address@hidden
+$ guix refresh
+gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to
0.18.2.1
+gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
address@hidden example
-The general syntax is:
+Alternately, one can specify packages to consider, in which case a
+warning is emitted for packages that lack an updater:
@example
-guix lint @var{options} @address@hidden
+$ guix refresh coreutils guile guile-ssh
+gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
+gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
@end example
-If no package is given on the command line, then all packages are checked.
-The @var{options} may be zero or more of the following:
address@hidden refresh} browses the upstream repository of each package and
determines
+the highest version number of the releases therein. The command
+knows how to update specific types of packages: GNU packages, ELPA
+packages, etc.---see the documentation for @option{--type} below. There
+are many packages, though, for which it lacks a method to determine
+whether a new upstream release is available. However, the mechanism is
+extensible, so feel free to get in touch with us to add a new method!
@table @code
address@hidden --list-checkers
address@hidden -l
-List and describe all the available checkers that will be run on packages
-and exit.
-
address@hidden --checkers
address@hidden -c
-Only enable the checkers specified in a comma-separated list using the
-names returned by @code{--list-checkers}.
-
address@hidden table
-
address@hidden Invoking guix size
address@hidden Invoking @command{guix size}
-
address@hidden size
address@hidden package size
address@hidden closure
address@hidden @command{guix size}
-The @command{guix size} command helps package developers profile the
-disk usage of packages. It is easy to overlook the impact of an
-additional dependency added to a package, or the impact of using a
-single output for a package that could easily be split (@pxref{Packages
-with Multiple Outputs}). Such are the typical issues that
address@hidden size} can highlight.
-The command can be passed one or more package specifications
-such as @code{gcc@@4.8}
-or @code{guile:debug}, or a file name in the store. Consider this
-example:
address@hidden --recursive
+Consider the packages specified, and all the packages upon which they depend.
@example
-$ guix size coreutils
-store item total self
-/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
-/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
-/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
-/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
-/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
-/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
-/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
-/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
-total: 78.9 MiB
+$ guix refresh --recursive coreutils
+gnu/packages/acl.scm:35:2: warning: no updater for acl
+gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
+gnu/packages/xml.scm:68:2: warning: no updater for expat
+gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest
version of gmp
address@hidden
@end example
address@hidden closure
-The store items listed here constitute the @dfn{transitive closure} of
-Coreutils---i.e., Coreutils and all its dependencies, recursively---as
-would be returned by:
address@hidden table
+
+Sometimes the upstream name differs from the package name used in Guix,
+and @command{guix refresh} needs a little help. Most updaters honor the
address@hidden property in package definitions, which can be used
+to that effect:
@example
-$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
+(define-public network-manager
+ (package
+ (name "network-manager")
+ ;; @dots{}
+ (properties '((upstream-name . "NetworkManager")))))
@end example
-Here the output shows three columns next to store items. The first column,
-labeled ``total'', shows the size in mebibytes (MiB) of the closure of
-the store item---that is, its own size plus the size of all its
-dependencies. The next column, labeled ``self'', shows the size of the
-item itself. The last column shows the ratio of the size of the item
-itself to the space occupied by all the items listed here.
+When passed @code{--update}, it modifies distribution source files to
+update the version numbers and source tarball hashes of those package
+recipes (@pxref{Defining Packages}). This is achieved by downloading
+each package's latest source tarball and its associated OpenPGP
+signature, authenticating the downloaded tarball against its signature
+using @command{gpg}, and finally computing its hash. When the public
+key used to sign the tarball is missing from the user's keyring, an
+attempt is made to automatically retrieve it from a public key server;
+when this is successful, the key is added to the user's keyring; otherwise,
address@hidden refresh} reports an error.
-In this example, we see that the closure of Coreutils weighs in at
address@hidden, most of which is taken by libc and GCC's run-time support
-libraries. (That libc and GCC's libraries represent a large fraction of
-the closure is not a problem @i{per se} because they are always available
-on the system anyway.)
+The following options are supported:
-When the package(s) passed to @command{guix size} are available in the
address@hidden precisely, @command{guix size} looks for the
address@hidden variant of the given package(s), as returned by
address@hidden build @var{package} --no-grafts}. @xref{Security Updates},
-for information on grafts.}, @command{guix size} queries the daemon to
determine its
-dependencies, and measures its size in the store, similar to @command{du
--ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
-Coreutils}).
address@hidden @code
-When the given packages are @emph{not} in the store, @command{guix size}
-reports information based on the available substitutes
-(@pxref{Substitutes}). This makes it possible it to profile disk usage of
-store items that are not even on disk, only available remotely.
address@hidden address@hidden
address@hidden -e @var{expr}
+Consider the package @var{expr} evaluates to.
-You can also specify several package names:
+This is useful to precisely refer to a package, as in this example:
@example
-$ guix size coreutils grep sed bash
-store item total self
-/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
-/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
-/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
-/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
address@hidden
-total: 102.3 MiB
+guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
@end example
address@hidden
-In this example we see that the combination of the four packages takes
address@hidden in total, which is much less than the sum of each closure
-since they have a lot of dependencies in common.
-
-The available options are:
-
address@hidden @option
+This command lists the dependents of the ``final'' libc (essentially all
+the packages.)
address@hidden address@hidden
-Use substitute information from @var{urls}.
address@hidden, the same option for @code{guix build}}.
address@hidden --update
address@hidden -u
+Update distribution source files (package recipes) in place. This is
+usually run from a checkout of the Guix source tree (@pxref{Running
+Guix Before It Is Installed}):
address@hidden address@hidden
-Sort lines according to @var{key}, one of the following options:
address@hidden
+$ ./pre-inst-env guix refresh -s non-core -u
address@hidden example
address@hidden @code
address@hidden self
-the size of each item (the default);
address@hidden closure
-the total size of the item's closure.
address@hidden table
address@hidden Packages}, for more information on package definitions.
address@hidden address@hidden
-Write a graphical map of disk usage in PNG format to @var{file}.
address@hidden address@hidden
address@hidden -s @var{subset}
+Select all the packages in @var{subset}, one of @code{core} or
address@hidden
-For the example above, the map looks like this:
+The @code{core} subset refers to all the packages at the core of the
+distribution---i.e., packages that are used to build ``everything
+else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
+changing one of these packages in the distribution entails a rebuild of
+all the others. Thus, such updates are an inconvenience to users in
+terms of build time or bandwidth used to achieve the upgrade.
address@hidden/coreutils-size-map,5in,, map of Coreutils disk usage
-produced by @command{guix size}}
+The @code{non-core} subset refers to the remaining packages. It is
+typically useful in cases where an update of the core packages would be
+inconvenient.
-This option requires that
address@hidden://wingolog.org/software/guile-charting/, Guile-Charting} be
-installed and visible in Guile's module search path. When that is not
-the case, @command{guix size} fails as it tries to load it.
address@hidden address@hidden
address@hidden -m @var{file}
+Select all the packages from the manifest in @var{file}. This is useful to
+check if any packages of the user manifest can be updated.
address@hidden address@hidden
address@hidden -s @var{system}
-Consider packages for @var{system}---e.g., @code{x86_64-linux}.
address@hidden address@hidden
address@hidden -t @var{updater}
+Select only packages handled by @var{updater} (may be a comma-separated
+list of updaters). Currently, @var{updater} may be one of:
address@hidden @code
address@hidden gnu
+the updater for GNU packages;
address@hidden gnome
+the updater for GNOME packages;
address@hidden kde
+the updater for KDE packages;
address@hidden xorg
+the updater for X.org packages;
address@hidden kernel.org
+the updater for packages hosted on kernel.org;
address@hidden elpa
+the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
address@hidden cran
+the updater for @uref{https://cran.r-project.org/, CRAN} packages;
address@hidden bioconductor
+the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
address@hidden cpan
+the updater for @uref{http://www.cpan.org/, CPAN} packages;
address@hidden pypi
+the updater for @uref{https://pypi.python.org, PyPI} packages.
address@hidden gem
+the updater for @uref{https://rubygems.org, RubyGems} packages.
address@hidden github
+the updater for @uref{https://github.com, GitHub} packages.
address@hidden hackage
+the updater for @uref{https://hackage.haskell.org, Hackage} packages.
address@hidden stackage
+the updater for @uref{https://www.stackage.org, Stackage} packages.
address@hidden crate
+the updater for @uref{https://crates.io, Crates} packages.
@end table
address@hidden Invoking guix graph
address@hidden Invoking @command{guix graph}
-
address@hidden DAG
address@hidden @command{guix graph}
address@hidden package dependencies
-Packages and their dependencies form a @dfn{graph}, specifically a
-directed acyclic graph (DAG). It can quickly become difficult to have a
-mental model of the package DAG, so the @command{guix graph} command
-provides a visual representation of the DAG. By default,
address@hidden graph} emits a DAG representation in the input format of
address@hidden://www.graphviz.org/, Graphviz}, so its output can be passed
-directly to the @command{dot} command of Graphviz. It can also emit an
-HTML page with embedded JavaScript code to display a ``chord diagram''
-in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
-emit Cypher queries to construct a graph in a graph database supporting
-the @uref{http://www.opencypher.org/, openCypher} query language.
-The general syntax is:
+For instance, the following command only checks for updates of Emacs
+packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
@example
-guix graph @var{options} @address@hidden
+$ guix refresh --type=elpa,cran
+gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0
to 0.11.0
+gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to
11.88.9
@end example
-For example, the following command generates a PDF file representing the
-package DAG for the address@hidden Utilities, showing its build-time
-dependencies:
address@hidden table
+
+In addition, @command{guix refresh} can be passed one or more package
+names, as in this example:
@example
-guix graph coreutils | dot -Tpdf > dag.pdf
+$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
@end example
-The output looks like this:
address@hidden
+The command above specifically updates the @code{emacs} and
address@hidden packages. The @code{--select} option would have no
+effect in this case.
address@hidden/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
+When considering whether to upgrade a package, it is sometimes
+convenient to know which packages would be affected by the upgrade and
+should be checked for compatibility. For this the following option may
+be used when passing @command{guix refresh} one or more package names:
-Nice little graph, no?
address@hidden @code
-But there is more than one graph! The one above is concise: it is the
-graph of package objects, omitting implicit inputs such as GCC, libc,
-grep, etc. It is often useful to have such a concise graph, but
-sometimes one may want to see more details. @command{guix graph} supports
-several types of graphs, allowing you to choose the level of detail:
address@hidden --list-updaters
address@hidden -L
+List available updaters and exit (see @option{--type} above.)
address@hidden @code
address@hidden package
-This is the default type used in the example above. It shows the DAG of
-package objects, excluding implicit dependencies. It is concise, but
-filters out many details.
+For each updater, display the fraction of packages it covers; at the
+end, display the fraction of packages covered by all these updaters.
address@hidden reverse-package
-This shows the @emph{reverse} DAG of packages. For example:
address@hidden --list-dependent
address@hidden -l
+List top-level dependent packages that would need to be rebuilt as a
+result of upgrading one or more packages.
+
address@hidden guix graph, the @code{reverse-package} type of
address@hidden graph}}, for information on how to visualize the list of
+dependents of a package.
+
address@hidden table
+
+Be aware that the @code{--list-dependent} option only
address@hidden the rebuilds that would be required as a result of
+an upgrade. More rebuilds might be required under some circumstances.
@example
-guix graph --type=reverse-package ocaml
+$ guix refresh --list-dependent flex
+Building the following 120 packages would ensure 213 dependent packages are
rebuilt:
+hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6
@dots{}
@end example
-...@: yields the graph of packages that depend on OCaml.
-
-Note that for core packages this can yield huge graphs. If all you want
-is to know the number of packages that depend on a given package, use
address@hidden refresh --list-dependent} (@pxref{Invoking guix refresh,
address@hidden).
+The command above lists a set of packages that could be built to check
+for compatibility with an upgraded @code{flex} package.
address@hidden bag-emerged
-This is the package DAG, @emph{including} implicit inputs.
address@hidden @code
-For instance, the following command:
address@hidden --list-transitive
+List all the packages which one or more packages depend upon.
@example
-guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
+$ guix refresh --list-transitive flex
+flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
+bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4
file@@5.33 @dots{}
@end example
-...@: yields this bigger graph:
address@hidden table
address@hidden/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU
Coreutils}
+The command above lists a set of packages which, when changed, would cause
address@hidden to be rebuilt.
-At the bottom of the graph, we see all the implicit inputs of
address@hidden (@pxref{Build Systems, @code{gnu-build-system}}).
+The following options can be used to customize GnuPG operation:
-Now, note that the dependencies of these implicit inputs---that is, the
address@hidden dependencies} (@pxref{Bootstrapping})---are not shown
-here, for conciseness.
address@hidden @code
address@hidden bag
-Similar to @code{bag-emerged}, but this time including all the bootstrap
-dependencies.
address@hidden address@hidden
+Use @var{command} as the GnuPG 2.x command. @var{command} is searched
+for in @code{$PATH}.
address@hidden bag-with-origins
-Similar to @code{bag}, but also showing origins and their dependencies.
address@hidden address@hidden
+Use @var{file} as the keyring for upstream keys. @var{file} must be in the
address@hidden format}. Keybox files usually have a name ending in @file{.kbx}
+and the address@hidden Guard (GPG) can manipulate these files
+(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
+information on a tool to manipulate keybox files).
address@hidden derivation
-This is the most detailed representation: It shows the DAG of
-derivations (@pxref{Derivations}) and plain store items. Compared to
-the above representation, many additional nodes are visible, including
-build scripts, patches, Guile modules, etc.
+When this option is omitted, @command{guix refresh} uses
address@hidden/.config/guix/upstream/trustedkeys.kbx} as the keyring for
upstream
+signing keys. OpenPGP signatures are checked against keys from this keyring;
+missing keys are downloaded to this keyring as well (see
address@hidden below.)
-For this type of graph, it is also possible to pass a @file{.drv} file
-name instead of a package name, as in:
+You can export keys from your default GPG keyring into a keybox file using
+commands like this one:
@example
-guix graph -t derivation `guix system build -d my-config.scm`
+gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
@end example
address@hidden module
-This is the graph of @dfn{package modules} (@pxref{Package Modules}).
-For example, the following command shows the graph for the package
-module that defines the @code{guile} package:
+Likewise, you can fetch keys to a specific keybox file like this:
@example
-guix graph -t module guile | dot -Tpdf > module-graph.pdf
+gpg --no-default-keyring --keyring mykeyring.kbx \
+ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
+
address@hidden Configuration Options, @option{--keyring},, gnupg, Using the GNU
+Privacy Guard}, for more information on GPG's @option{--keyring} option.
+
address@hidden address@hidden
+Handle missing OpenPGP keys according to @var{policy}, which may be one
+of:
+
address@hidden @code
address@hidden always
+Always download missing OpenPGP keys from the key server, and add them
+to the user's GnuPG keyring.
+
address@hidden never
+Never try to download missing OpenPGP keys. Instead just bail out.
+
address@hidden interactive
+When a package signed with an unknown OpenPGP key is encountered, ask
+the user whether to download it or not. This is the default behavior.
@end table
-All the types above correspond to @emph{build-time dependencies}. The
-following graph type represents the @emph{run-time dependencies}:
address@hidden address@hidden
+Use @var{host} as the OpenPGP key server when importing a public key.
+
address@hidden table
+
+The @code{github} updater uses the
address@hidden://developer.github.com/v3/, GitHub API} to query for new
+releases. When used repeatedly e.g.@: when refreshing all packages,
+GitHub will eventually refuse to answer any further API requests. By
+default 60 API requests per hour are allowed, and a full refresh on all
+GitHub packages in Guix requires more than this. Authentication with
+GitHub through the use of an API token alleviates these limits. To use
+an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
+token procured from @uref{https://github.com/settings/tokens} or
+otherwise.
+
+
address@hidden Invoking guix lint
address@hidden Invoking @command{guix lint}
+
address@hidden @command{guix lint}
address@hidden package, checking for errors
+The @command{guix lint} command is meant to help package developers avoid
+common errors and use a consistent style. It runs a number of checks on
+a given set of packages in order to find common mistakes in their
+definitions. Available @dfn{checkers} include (see
address@hidden for a complete list):
@table @code
address@hidden references
-This is the graph of @dfn{references} of a package output, as returned
-by @command{guix gc --references} (@pxref{Invoking guix gc}).
address@hidden synopsis
address@hidden description
+Validate certain typographical and stylistic rules about package
+descriptions and synopses.
-If the given package output is not available in the store, @command{guix
-graph} attempts to obtain dependency information from substitutes.
address@hidden inputs-should-be-native
+Identify inputs that should most likely be native inputs.
-Here you can also pass a store file name instead of a package name. For
-example, the command below produces the reference graph of your profile
-(which can be big!):
address@hidden source
address@hidden home-page
address@hidden mirror-url
address@hidden github-url
address@hidden source-file-name
+Probe @code{home-page} and @code{source} URLs and report those that are
+invalid. Suggest a @code{mirror://} URL when applicable. If the
address@hidden URL redirects to a GitHub URL, recommend usage of the GitHub
+URL. Check that the source file name is meaningful, e.g.@: is not just a
+version number or ``git-checkout'', without a declared @code{file-name}
+(@pxref{origin Reference}).
+
address@hidden source-unstable-tarball
+Parse the @code{source} URL to determine if a tarball from GitHub is
+autogenerated or if it is a release tarball. Unfortunately GitHub's
+autogenerated tarballs are sometimes regenerated.
+
address@hidden cve
address@hidden security vulnerabilities
address@hidden CVE, Common Vulnerabilities and Exposures
+Report known vulnerabilities found in the Common Vulnerabilities and
+Exposures (CVE) databases of the current and past year
address@hidden://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
+NIST}.
+
+To view information about a particular vulnerability, visit pages such as:
+
address@hidden
address@hidden
address@hidden://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
address@hidden
address@hidden://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
address@hidden itemize
+
address@hidden
+where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
address@hidden
+
+Package developers can specify in package recipes the
address@hidden://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
+name and version of the package when they differ from the name or version
+that Guix uses, as in this example:
@example
-guix graph -t references `readlink -f ~/.guix-profile`
+(package
+ (name "grub")
+ ;; @dots{}
+ ;; CPE calls this package "grub2".
+ (properties '((cpe-name . "grub2")
+ (cpe-version . "2.3")))
@end example
address@hidden referrers
-This is the graph of the @dfn{referrers} of a store item, as returned by
address@hidden gc --referrers} (@pxref{Invoking guix gc}).
-
-This relies exclusively on local information from your store. For
-instance, let us suppose that the current Inkscape is available in 10
-profiles on your machine; @command{guix graph -t referrers inkscape}
-will show a graph rooted at Inkscape and with those 10 profiles linked
-to it.
address@hidden See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+Some entries in the CVE database do not specify which version of a
+package they apply to, and would thus ``stick around'' forever. Package
+developers who found CVE alerts and verified they can be ignored can
+declare them as in this example:
-It can help determine what is preventing a store item from being garbage
-collected.
address@hidden
+(package
+ (name "t1lib")
+ ;; @dots{}
+ ;; These CVEs no longer apply and can be safely ignored.
+ (properties `((lint-hidden-cve . ("CVE-2011-0433"
+ "CVE-2011-1553"
+ "CVE-2011-1554"
+ "CVE-2011-5244")))))
address@hidden example
address@hidden formatting
+Warn about obvious source code formatting issues: trailing white space,
+use of tabulations, etc.
@end table
-The available options are the following:
+The general syntax is:
address@hidden @option
address@hidden address@hidden
address@hidden -t @var{type}
-Produce a graph output of @var{type}, where @var{type} must be one of
-the values listed above.
address@hidden
+guix lint @var{options} @address@hidden
address@hidden example
address@hidden --list-types
-List the supported graph types.
+If no package is given on the command line, then all packages are checked.
+The @var{options} may be zero or more of the following:
address@hidden address@hidden
address@hidden -b @var{backend}
-Produce a graph using the selected @var{backend}.
address@hidden @code
address@hidden --list-checkers
address@hidden -l
+List and describe all the available checkers that will be run on packages
+and exit.
address@hidden --list-backends
-List the supported graph backends.
address@hidden --checkers
address@hidden -c
+Only enable the checkers specified in a comma-separated list using the
+names returned by @code{--list-checkers}.
-Currently, the available backends are Graphviz and d3.js.
address@hidden table
address@hidden address@hidden
address@hidden -e @var{expr}
-Consider the package @var{expr} evaluates to.
address@hidden Invoking guix size
address@hidden Invoking @command{guix size}
-This is useful to precisely refer to a package, as in this example:
address@hidden size
address@hidden package size
address@hidden closure
address@hidden @command{guix size}
+The @command{guix size} command helps package developers profile the
+disk usage of packages. It is easy to overlook the impact of an
+additional dependency added to a package, or the impact of using a
+single output for a package that could easily be split (@pxref{Packages
+with Multiple Outputs}). Such are the typical issues that
address@hidden size} can highlight.
+
+The command can be passed one or more package specifications
+such as @code{gcc@@4.8}
+or @code{guile:debug}, or a file name in the store. Consider this
+example:
@example
-guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
+$ guix size coreutils
+store item total self
+/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
+/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
+/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
+/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
+/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
+/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
+/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
+/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
+total: 78.9 MiB
@end example
address@hidden address@hidden
address@hidden -s @var{system}
-Display the graph for @var{system}---e.g., @code{i686-linux}.
address@hidden closure
+The store items listed here constitute the @dfn{transitive closure} of
+Coreutils---i.e., Coreutils and all its dependencies, recursively---as
+would be returned by:
-The package dependency graph is largely architecture-independent, but there
-are some architecture-dependent bits that this option allows you to visualize.
address@hidden table
address@hidden
+$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
address@hidden example
+Here the output shows three columns next to store items. The first column,
+labeled ``total'', shows the size in mebibytes (MiB) of the closure of
+the store item---that is, its own size plus the size of all its
+dependencies. The next column, labeled ``self'', shows the size of the
+item itself. The last column shows the ratio of the size of the item
+itself to the space occupied by all the items listed here.
address@hidden Invoking guix environment
address@hidden Invoking @command{guix environment}
+In this example, we see that the closure of Coreutils weighs in at
address@hidden, most of which is taken by libc and GCC's run-time support
+libraries. (That libc and GCC's libraries represent a large fraction of
+the closure is not a problem @i{per se} because they are always available
+on the system anyway.)
address@hidden reproducible build environments
address@hidden development environments
address@hidden @command{guix environment}
address@hidden environment, package build environment
-The purpose of @command{guix environment} is to assist hackers in
-creating reproducible development environments without polluting their
-package profile. The @command{guix environment} tool takes one or more
-packages, builds all of their inputs, and creates a shell
-environment to use them.
+When the package(s) passed to @command{guix size} are available in the
address@hidden precisely, @command{guix size} looks for the
address@hidden variant of the given package(s), as returned by
address@hidden build @var{package} --no-grafts}. @xref{Security Updates},
+for information on grafts.}, @command{guix size} queries the daemon to
determine its
+dependencies, and measures its size in the store, similar to @command{du
+-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
+Coreutils}).
-The general syntax is:
+When the given packages are @emph{not} in the store, @command{guix size}
+reports information based on the available substitutes
+(@pxref{Substitutes}). This makes it possible it to profile disk usage of
+store items that are not even on disk, only available remotely.
+
+You can also specify several package names:
@example
-guix environment @var{options} @address@hidden
+$ guix size coreutils grep sed bash
+store item total self
+/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
+/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
+/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
+/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
address@hidden
+total: 102.3 MiB
@end example
-The following example spawns a new shell set up for the development of
address@hidden:
address@hidden
+In this example we see that the combination of the four packages takes
address@hidden in total, which is much less than the sum of each closure
+since they have a lot of dependencies in common.
address@hidden
-guix environment guile
address@hidden example
+The available options are:
-If the needed dependencies are not built yet, @command{guix environment}
-automatically builds them. The environment of the new shell is an augmented
-version of the environment that @command{guix environment} was run in.
-It contains the necessary search paths for building the given package
-added to the existing environment variables. To create a ``pure''
-environment, in which the original environment variables have been unset,
-use the @code{--pure} address@hidden sometimes wrongfully augment
-environment variables such as @code{PATH} in their @file{~/.bashrc}
-file. As a consequence, when @code{guix environment} launches it, Bash
-may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
-environment variables. It is an error to define such environment
-variables in @file{.bashrc}; instead, they should be defined in
address@hidden, which is sourced only by log-in shells.
address@hidden Startup Files,,, bash, The GNU Bash Reference Manual}, for
-details on Bash start-up files.}.
address@hidden @option
address@hidden GUIX_ENVIRONMENT
address@hidden environment} defines the @code{GUIX_ENVIRONMENT}
-variable in the shell it spawns; its value is the file name of the
-profile of this environment. This allows users to, say, define a
-specific prompt for development environments in their @file{.bashrc}
-(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
address@hidden address@hidden
+Use substitute information from @var{urls}.
address@hidden, the same option for @code{guix build}}.
address@hidden
-if [ -n "$GUIX_ENVIRONMENT" ]
-then
- export PS1="\u@@\h \w [dev]\$ "
-fi
address@hidden example
address@hidden address@hidden
+Sort lines according to @var{key}, one of the following options:
address@hidden
-...@: or to browse the profile:
address@hidden @code
address@hidden self
+the size of each item (the default);
address@hidden closure
+the total size of the item's closure.
address@hidden table
address@hidden
-$ ls "$GUIX_ENVIRONMENT/bin"
address@hidden example
address@hidden address@hidden
+Write a graphical map of disk usage in PNG format to @var{file}.
-Additionally, more than one package may be specified, in which case the
-union of the inputs for the given packages are used. For example, the
-command below spawns a shell where all of the dependencies of both Guile
-and Emacs are available:
+For the example above, the map looks like this:
address@hidden
-guix environment guile emacs
address@hidden example
address@hidden/coreutils-size-map,5in,, map of Coreutils disk usage
+produced by @command{guix size}}
-Sometimes an interactive shell session is not desired. An arbitrary
-command may be invoked by placing the @code{--} token to separate the
-command from the rest of the arguments:
+This option requires that
address@hidden://wingolog.org/software/guile-charting/, Guile-Charting} be
+installed and visible in Guile's module search path. When that is not
+the case, @command{guix size} fails as it tries to load it.
address@hidden
-guix environment guile -- make -j4
address@hidden example
address@hidden address@hidden
address@hidden -s @var{system}
+Consider packages for @var{system}---e.g., @code{x86_64-linux}.
-In other situations, it is more convenient to specify the list of
-packages needed in the environment. For example, the following command
-runs @command{python} from an environment containing address@hidden and
-NumPy:
address@hidden table
address@hidden
-guix environment --ad-hoc python2-numpy python-2.7 -- python
address@hidden example
address@hidden Invoking guix graph
address@hidden Invoking @command{guix graph}
-Furthermore, one might want the dependencies of a package and also some
-additional packages that are not build-time or runtime dependencies, but
-are useful when developing nonetheless. Because of this, the
address@hidden flag is positional. Packages appearing before
address@hidden are interpreted as packages whose dependencies will be
-added to the environment. Packages appearing after are interpreted as
-packages that will be added to the environment directly. For example,
-the following command creates a Guix development environment that
-additionally includes Git and strace:
address@hidden DAG
address@hidden @command{guix graph}
address@hidden package dependencies
+Packages and their dependencies form a @dfn{graph}, specifically a
+directed acyclic graph (DAG). It can quickly become difficult to have a
+mental model of the package DAG, so the @command{guix graph} command
+provides a visual representation of the DAG. By default,
address@hidden graph} emits a DAG representation in the input format of
address@hidden://www.graphviz.org/, Graphviz}, so its output can be passed
+directly to the @command{dot} command of Graphviz. It can also emit an
+HTML page with embedded JavaScript code to display a ``chord diagram''
+in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
+emit Cypher queries to construct a graph in a graph database supporting
+the @uref{http://www.opencypher.org/, openCypher} query language.
+The general syntax is:
@example
-guix environment guix --ad-hoc git strace
+guix graph @var{options} @address@hidden
@end example
-Sometimes it is desirable to isolate the environment as much as
-possible, for maximal purity and reproducibility. In particular, when
-using Guix on a host distro that is not Guix System, it is desirable to
-prevent access to @file{/usr/bin} and other system-wide resources from
-the development environment. For example, the following command spawns
-a Guile REPL in a ``container'' where only the store and the current
-working directory are mounted:
+For example, the following command generates a PDF file representing the
+package DAG for the address@hidden Utilities, showing its build-time
+dependencies:
@example
-guix environment --ad-hoc --container guile -- guile
address@hidden example
-
address@hidden Note
-The @code{--container} option requires Linux-libre 3.19 or newer.
address@hidden quotation
+guix graph coreutils | dot -Tpdf > dag.pdf
address@hidden example
-The available options are summarized below.
+The output looks like this:
address@hidden @code
address@hidden address@hidden
address@hidden -r @var{file}
address@hidden persistent environment
address@hidden garbage collector root, for environments
-Make @var{file} a symlink to the profile for this environment, and
-register it as a garbage collector root.
address@hidden/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
-This is useful if you want to protect your environment from garbage
-collection, to make it ``persistent''.
+Nice little graph, no?
-When this option is omitted, the environment is protected from garbage
-collection only for the duration of the @command{guix environment}
-session. This means that next time you recreate the same environment,
-you could have to rebuild or re-download packages. @xref{Invoking guix
-gc}, for more on GC roots.
+But there is more than one graph! The one above is concise: it is the
+graph of package objects, omitting implicit inputs such as GCC, libc,
+grep, etc. It is often useful to have such a concise graph, but
+sometimes one may want to see more details. @command{guix graph} supports
+several types of graphs, allowing you to choose the level of detail:
address@hidden address@hidden
address@hidden -e @var{expr}
-Create an environment for the package or list of packages that
address@hidden evaluates to.
address@hidden @code
address@hidden package
+This is the default type used in the example above. It shows the DAG of
+package objects, excluding implicit dependencies. It is concise, but
+filters out many details.
-For example, running:
address@hidden reverse-package
+This shows the @emph{reverse} DAG of packages. For example:
@example
-guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
+guix graph --type=reverse-package ocaml
@end example
-starts a shell with the environment for this specific variant of the
-PETSc package.
-
-Running:
+...@: yields the graph of packages that depend on OCaml.
address@hidden
-guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
address@hidden example
+Note that for core packages this can yield huge graphs. If all you want
+is to know the number of packages that depend on a given package, use
address@hidden refresh --list-dependent} (@pxref{Invoking guix refresh,
address@hidden).
-starts a shell with all the base system packages available.
address@hidden bag-emerged
+This is the package DAG, @emph{including} implicit inputs.
-The above commands only use the default output of the given packages.
-To select other outputs, two element tuples can be specified:
+For instance, the following command:
@example
-guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
+guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
@end example
address@hidden address@hidden
address@hidden -l @var{file}
-Create an environment for the package or list of packages that the code
-within @var{file} evaluates to.
+...@: yields this bigger graph:
-As an example, @var{file} might contain a definition like this
-(@pxref{Defining Packages}):
address@hidden/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU
Coreutils}
address@hidden
address@hidden environment-gdb.scm
address@hidden example
+At the bottom of the graph, we see all the implicit inputs of
address@hidden (@pxref{Build Systems, @code{gnu-build-system}}).
address@hidden address@hidden
address@hidden -m @var{file}
-Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
+Now, note that the dependencies of these implicit inputs---that is, the
address@hidden dependencies} (@pxref{Bootstrapping})---are not shown
+here, for conciseness.
-This is similar to the same-named option in @command{guix package}
-(@pxref{profile-manifest, @option{--manifest}}) and uses the same
-manifest files.
address@hidden bag
+Similar to @code{bag-emerged}, but this time including all the bootstrap
+dependencies.
address@hidden --ad-hoc
-Include all specified packages in the resulting environment, as if an
address@hidden hoc} package were defined with them as inputs. This option is
-useful for quickly creating an environment without having to write a
-package expression to contain the desired inputs.
address@hidden bag-with-origins
+Similar to @code{bag}, but also showing origins and their dependencies.
-For instance, the command:
address@hidden derivation
+This is the most detailed representation: It shows the DAG of
+derivations (@pxref{Derivations}) and plain store items. Compared to
+the above representation, many additional nodes are visible, including
+build scripts, patches, Guile modules, etc.
+
+For this type of graph, it is also possible to pass a @file{.drv} file
+name instead of a package name, as in:
@example
-guix environment --ad-hoc guile guile-sdl -- guile
+guix graph -t derivation `guix system build -d my-config.scm`
@end example
-runs @command{guile} in an environment where Guile and Guile-SDL are
-available.
address@hidden module
+This is the graph of @dfn{package modules} (@pxref{Package Modules}).
+For example, the following command shows the graph for the package
+module that defines the @code{guile} package:
-Note that this example implicitly asks for the default output of
address@hidden and @code{guile-sdl}, but it is possible to ask for a
-specific output---e.g., @code{glib:bin} asks for the @code{bin} output
-of @code{glib} (@pxref{Packages with Multiple Outputs}).
address@hidden
+guix graph -t module guile | dot -Tpdf > module-graph.pdf
address@hidden example
address@hidden table
-This option may be composed with the default behavior of @command{guix
-environment}. Packages appearing before @code{--ad-hoc} are interpreted
-as packages whose dependencies will be added to the environment, the
-default behavior. Packages appearing after are interpreted as packages
-that will be added to the environment directly.
+All the types above correspond to @emph{build-time dependencies}. The
+following graph type represents the @emph{run-time dependencies}:
address@hidden --pure
-Unset existing environment variables when building the new environment.
-This has the effect of creating an environment in which search paths
-only contain package inputs.
address@hidden @code
address@hidden references
+This is the graph of @dfn{references} of a package output, as returned
+by @command{guix gc --references} (@pxref{Invoking guix gc}).
address@hidden --search-paths
-Display the environment variable definitions that make up the
-environment.
+If the given package output is not available in the store, @command{guix
+graph} attempts to obtain dependency information from substitutes.
address@hidden address@hidden
address@hidden -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}.
+Here you can also pass a store file name instead of a package name. For
+example, the command below produces the reference graph of your profile
+(which can be big!):
address@hidden --container
address@hidden -C
address@hidden container
-Run @var{command} within an isolated container. The current working
-directory outside the container is mapped inside the container.
-Additionally, unless overridden with @code{--user}, a dummy home
-directory is created that matches the current user's home directory, and
address@hidden/etc/passwd} is configured accordingly. The spawned process runs
-as the current user outside the container, but has root privileges in
-the context of the container.
address@hidden
+guix graph -t references `readlink -f ~/.guix-profile`
address@hidden example
address@hidden --network
address@hidden -N
-For containers, share the network namespace with the host system.
-Containers created without this flag only have access to the loopback
-device.
address@hidden referrers
+This is the graph of the @dfn{referrers} of a store item, as returned by
address@hidden gc --referrers} (@pxref{Invoking guix gc}).
address@hidden --link-profile
address@hidden -P
-For containers, link the environment profile to
address@hidden/.guix-profile} within the container. This is equivalent to
-running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
-within the container. Linking will fail and abort the environment if
-the directory already exists, which will certainly be the case if
address@hidden environment} was invoked in the user's home directory.
+This relies exclusively on local information from your store. For
+instance, let us suppose that the current Inkscape is available in 10
+profiles on your machine; @command{guix graph -t referrers inkscape}
+will show a graph rooted at Inkscape and with those 10 profiles linked
+to it.
-Certain packages are configured to look in
address@hidden/.guix-profile} for configuration files and data;@footnote{For
-example, the @code{fontconfig} package inspects
address@hidden/.guix-profile/share/fonts} for additional fonts.}
address@hidden allows these programs to behave as expected within
-the environment.
+It can help determine what is preventing a store item from being garbage
+collected.
address@hidden address@hidden
address@hidden -u @var{user}
-For containers, use the username @var{user} in place of the current
-user. The generated @file{/etc/passwd} entry within the container will
-contain the name @var{user}; the home directory will be
address@hidden/home/USER}; and no user GECOS data will be copied. @var{user}
-need not exist on the system.
address@hidden table
-Additionally, any shared or exposed path (see @code{--share} and
address@hidden respectively) whose target is within the current user's
-home directory will be remapped relative to @file{/home/USER}; this
-includes the automatic mapping of the current working directory.
+The available options are the following:
address@hidden
-# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
-cd $HOME/wd
-guix environment --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
address@hidden example
address@hidden @option
address@hidden address@hidden
address@hidden -t @var{type}
+Produce a graph output of @var{type}, where @var{type} must be one of
+the values listed above.
-While this will limit the leaking of user identity through home paths
-and each of the user fields, this is only one useful component of a
-broader privacy/anonymity solution---not one in and of itself.
address@hidden --list-types
+List the supported graph types.
address@hidden address@hidden@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container. If
address@hidden is not specified, @var{source} is used as the target mount
-point in the container.
address@hidden address@hidden
address@hidden -b @var{backend}
+Produce a graph using the selected @var{backend}.
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible read-only via the @file{/exchange}
-directory:
address@hidden --list-backends
+List the supported graph backends.
address@hidden
-guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
address@hidden example
+Currently, the available backends are Graphviz and d3.js.
address@hidden address@hidden@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container. If
address@hidden is not specified, @var{source} is used as the target mount
-point in the container.
address@hidden address@hidden
address@hidden -e @var{expr}
+Consider the package @var{expr} evaluates to.
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
address@hidden/exchange} directory:
+This is useful to precisely refer to a package, as in this example:
@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
+guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example
+
address@hidden address@hidden
address@hidden -s @var{system}
+Display the graph for @var{system}---e.g., @code{i686-linux}.
+
+The package dependency graph is largely architecture-independent, but there
+are some architecture-dependent bits that this option allows you to visualize.
@end table
address@hidden environment}
-also supports all of the common build options that @command{guix
-build} supports (@pxref{Common Build Options}) as well as package
-transformation options (@pxref{Package Transformation Options}).
@node Invoking guix publish
@@ -9892,7 +9926,7 @@ instance to support new system services.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
-* Running Guix in a VM:: How to run Guix System in a virtual machine.
+* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
@end menu