guix.texi

@node Invoking guix gc
@section Invoking @command{guix gc}

@cindex garbage collector
Packages that are installed, but not used, may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
collector to reclaim space from the @file{/gnu/store} directory.  It is
the @emph{only} way to remove files from @file{/gnu/store}---removing
files or directories manually may break it beyond repair!

The garbage collector has a set of known @dfn{roots}: any file under
@file{/gnu/store} reachable from a root is considered @dfn{live} and
cannot be deleted; any other file is considered @dfn{dead} and may be
deleted.  The set of garbage collector roots includes default user
profiles, and may be augmented with @command{guix build --root}, for
example (@pxref{Invoking guix build}).

Prior to running @code{guix gc --collect-garbage} to make space, it is
often useful to remove old generations from user profiles; that way, old
package builds referenced by those generations can be reclaimed.  This
is achieved by running @code{guix package --delete-generations}
(@pxref{Invoking guix package}).

The @command{guix gc} command has three modes of operation: it can be
used to garbage-collect any dead files (the default), to delete specific
files (the @code{--delete} option), to print garbage-collector
information, or for more advanced queries.  The garbage collection
options are as follows:

@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Collect garbage---i.e., unreachable @file{/gnu/store} files and
sub-directories.  This is the default operation when no option is
specified.

When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).

When @var{min} is omitted, collect all the garbage.

@item --free-space=@var{free}
@itemx -F @var{free}
Collect garbage until @var{free} space is available under
@file{/gnu/store}, if possible; @var{free} denotes storage space, such
as @code{500MiB}, as described above.

When @var{free} or more is already available in @file{/gnu/store}, do
nothing and exit immediately.

@item --delete
@itemx -d
Attempt to delete all the store files and directories specified as
arguments.  This fails if some of the files are not in the store, or if
they are still live.

@item --list-failures
List store items corresponding to cached build failures.

This prints nothing unless the daemon was started with
@option{--cache-failures} (@pxref{Invoking guix-daemon,
@option{--cache-failures}}).

@item --clear-failures
Remove the specified store items from the failed-build cache.

Again, this option only makes sense when the daemon is started with
@option{--cache-failures}.  Otherwise, it does nothing.

@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.

@item --list-live
Show the list of live store files and directories.

@end table

In addition, the references among existing store files can be queried:

@table @code

@item --references
@itemx --referrers
List the references (respectively, the referrers) of store files given
as arguments.

@item --requisites
@itemx -R
@cindex closure
List the requisites of the store files passed as arguments.  Requisites
include the store files themselves, their references, and the references
of these, recursively.  In other words, the returned list is the
@dfn{transitive closure} of the store files.

@xref{Invoking guix size}, for a tool to profile the size of the closure
of an element.  @xref{Invoking guix graph}, for a tool to visualize
the graph of references.

@end table

Lastly, the following options allow you to check the integrity of the
store and to control disk usage.

@table @option

@item --verify[=@var{options}]
@cindex integrity, of the store
@cindex integrity checking
Verify the integrity of the store.

By default, make sure that all the store items marked as valid in the
database of the daemon actually exist in @file{/gnu/store}.

When provided, @var{options} must be a comma-separated list containing one
or more of @code{contents} and @code{repair}.

When passing @option{--verify=contents}, the daemon computse the
content hash of each store item and compares it against its hash in the
database.  Hash mismatches are reported as data corruptions.  Because it
traverses @emph{all the files in the store}, this command can take a
long time, especially on systems with a slow disk drive.

@cindex repairing the store
Using @option{--verify=repair} or @option{--verify=contents,repair}
causes the daemon to try to repair corrupt store items by fetching
substitutes for them (@pxref{Substitutes}).  Because repairing is not
atomic, and thus potentially dangerous, it is available only to the
system administrator.

@item --optimize
@cindex deduplication
Optimize the store by hard-linking identical files---this is
@dfn{deduplication}.

The daemon performs deduplication after each successful build or archive
import, unless it was started with @code{--disable-deduplication}
(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}).  Thus,
this option is primarily useful when the daemon was running with
@code{--disable-deduplication}.

@end table

@node Invoking guix pull
@section Invoking @command{guix pull}

Packages are installed or upgraded to the latest version available in
the distribution currently available on your local machine.  To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
descriptions, and deploys it.

On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix.  Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
version.  New @command{guix} sub-commands added by the update also
become available.

Any user can update their Guix copy using @command{guix pull}, and the
effect is limited to the user who run @command{guix pull}.  For
instance, when user @code{root} runs @command{guix pull}, this has no
effect on the version of Guix that user @code{alice} sees, and vice
versa@footnote{Under the hood, @command{guix pull} updates the
@file{~/.config/guix/latest} symbolic link to point to the latest Guix,
and the @command{guix} command loads code from there.}.

The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:

@table @code
@item --verbose
Produce verbose output, writing build logs to the standard error output.

@item --url=@var{url}
Download the source tarball of Guix from @var{url}.

By default, the tarball is taken from its canonical address at
@code{gnu.org}, for the stable branch of Guix.

@item --bootstrap
Use the bootstrap Guile to build the latest Guix.  This option is only
useful to Guix developers.
@end table


@node Invoking guix archive
@section Invoking @command{guix archive}

The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them.
In particular, it allows store files to be transferred from one machine
to the store on another machine.

To export store files as an archive to standard output, run:

@example
guix archive --export @var{options} @var{specifications}...
@end example

@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}).  For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:

@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example

If the specified packages are not built yet, @command{guix archive}
automatically builds them.  The build process may be controlled with the
common build options (@pxref{Common Build Options}).

To transfer the @code{emacs} package to a machine connected over SSH,
one would run:

@example
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example

@noindent
Similarly, a complete user profile may be transferred from one machine
to another like this:

@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh the-machine guix-archive --import
@end example

@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the store on the
target machine.  The @code{--missing} option can help figure out which
items are missing from the target store.

Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
comparable in spirit to `tar', but with a few noteworthy differences
that make it more appropriate for our purposes.  First, rather than
recording all Unix metadata for each file, the Nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed.  Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order.  This makes archive production fully
deterministic.

When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended.  When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.

The main options are:

@table @code
@item --export
Export the specified store files or packages (see below.)  Write the
resulting archive to the standard output.

Dependencies are @emph{not} included in the output, unless
@code{--recursive} is passed.

@item -r
@itemx --recursive
When combined with @code{--export}, this instructs @command{guix
archive} to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.

@item --import
Read an archive from the standard input, and import the files listed
therein into the store.  Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
keys (see @code{--authorize} below.)

@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.

@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemon.  This is a prerequisite before
archives can be exported with @code{--export}.  Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.

The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret.)  When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).

@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.

The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}.  The file contains
@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.

@item --extract=@var{directory}
@itemx -x @var{directory}
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
low-level operation needed in only very narrow use cases; see below.

For example, the following command extracts the substitute for Emacs
served by @code{hydra.gnu.org} to @file{/tmp/emacs}:

@example
$ wget -O - \
  https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
  | bunzip2 | guix archive -x /tmp/emacs
@end example

Single-item archives are different from multiple-item archives produced
by @command{guix archive --export}; they contain a single store item,
and they do @emph{not} embed a signature.  Thus this operation does
@emph{no} signature verification and its output should be considered
unsafe.

The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers.

@end table

@c *********************************************************************
@include emacs.texi

@c *********************************************************************
@node Programming Interface
@chapter Programming Interface

GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages.  The first interface allows users to
write high-level package definitions.  These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies.  These definitions can then be
turned into concrete build actions.

Build actions are performed by the Guix daemon, on behalf of users.  In a
standard setup, the daemon has write access to the store---the
@file{/gnu/store} directory---whereas users do not.  The recommended
setup also has the daemon perform builds in chroots, under a specific
build users, to minimize interference with the rest of the system.

@cindex derivation
Lower-level APIs are available to interact with the daemon and the
store.  To instruct the daemon to perform a build action, users actually
provide it with a @dfn{derivation}.  A derivation is a low-level
representation of the build actions to be taken, and the environment in
which they should occur---derivations are to package definitions what
assembly is to C programs.  The term ``derivation'' comes from the fact
that build results @emph{derive} from them.

This chapter describes all these APIs in turn, starting from high-level
package definitions.

@menu
* Defining Packages::           Defining new packages.
* Build Systems::               Specifying how packages are built.
* The Store::                   Manipulating the package store.
* Derivations::                 Low-level interface to package derivations.
* The Store Monad::             Purely functional interface to the store.
* G-Expressions::               Manipulating build expressions.
@end menu

@node Defining Packages
@section Defining Packages

The high-level interface to package definitions is implemented in the
@code{(guix packages)} and @code{(guix build-system)} modules.  As an
example, the package definition, or @dfn{recipe}, for the GNU Hello
package looks like this:

@example
(define-module (gnu packages hello)
  #:use-module (guix packages)
  #:use-module (guix download)
  #:use-module (guix build-system gnu)
  #:use-module (guix licenses)
  #:use-module (gnu packages gawk))

(define-public hello
  (package
    (name "hello")
    (version "2.10")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
    (build-system gnu-build-system)
    (arguments '(#:configure-flags '("--enable-silent-rules")))
    (inputs `(("gawk" ,gawk)))
    (synopsis "Hello, GNU world: An example GNU package")
    (description "Guess what GNU Hello prints!")
    (home-page "http://www.gnu.org/software/hello/")
    (license gpl3+)))
@end example

@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here.  This expression binds the variable
@code{hello} to a @code{<package>} object, which is essentially a record
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
This package object can be inspected using procedures found in the
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.

With luck, you may be able to import part or all of the definition of
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).

In the example above, @var{hello} is defined in a module of its own,
@code{(gnu packages hello)}.  Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
the command-line tools (@pxref{Package Modules}).

There are a few points worth noting in the above package definition:

@itemize
@item
The @code{source} field of the package is an @code{<origin>} object
(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.

The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
the GNU mirrors defined in @code{(guix download)}.

The @code{sha256} field specifies the expected SHA256 hash of the file
being downloaded.  It is mandatory, and allows Guix to check the
integrity of the file.  The @code{(base32 @dots{})} form introduces the
base32 representation of the hash.  You can obtain this information with
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).

@cindex patches
When needed, the @code{origin} form can also have a @code{patches} field
listing patches to be applied, and a @code{snippet} field giving a
Scheme expression to modify the source code.

@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
package (@pxref{Build Systems}).  Here, @var{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.

@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}).  Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag.

@cindex quote
@cindex quoting
@findex '
@findex quote
What about these quote (@code{'}) characters?  They are Scheme syntax to
introduce a literal list; @code{'} is synonymous with @code{quote}.
@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
for details.  Here the value of the @code{arguments} field is a list of
arguments passed to the build system down the road, as with @code{apply}
(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
Manual}).

The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
@code{#:configure-flags} is a keyword used to pass a keyword argument
to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
Reference Manual}).

@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package.  Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk}
variable; @var{gawk} is itself bound to a @code{<package>} object.

@cindex backquote (quasiquote)
@findex `
@findex quasiquote
@cindex comma (unquote)
@findex ,
@findex unquote
@findex ,@@
@findex unquote-splicing
Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
us to introduce a literal list in the @code{inputs} field, while
@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
Reference Manual}).

Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here.  Instead, @var{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).

However, any other dependencies need to be specified in the
@code{inputs} field.  Any dependency not specified here will simply be
unavailable to the build process, possibly leading to a build failure.
@end itemize

@xref{package Reference}, for a full description of possible fields.

Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}).  You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.

Finally, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).

Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).

@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).

@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system.  @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
@end deffn

@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:

@deffn {Scheme Procedure} package-cross-derivation @var{store} @
            @var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.

@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn

@menu
* package Reference ::          The package data type.
* origin Reference::            The origin data type.
@end menu


@node package Reference
@subsection @code{package} Reference

This section summarizes all the options available in @code{package}
declarations (@pxref{Defining Packages}).

@deftp {Data Type} package
This is the data type representing a package recipe.

@table @asis
@item @code{name}
The name of the package, as a string.

@item @code{version}
The version of the package, as a string.

@item @code{source}
An object telling how the source code for the package should be
acquired.  Most of the time, this is an @code{origin} object, which
denotes a file fetched from the Internet (@pxref{origin Reference}).  It
can also be any other ``file-like'' object such as a @code{local-file},
which denotes a file from the local file system (@pxref{G-Expressions,
@code{local-file}}).

@item @code{build-system}
The build system that should be used to build the package (@pxref{Build
Systems}).

@item @code{arguments} (default: @code{'()})
The arguments that should be passed to the build system.  This is a
list, typically containing sequential keyword-value pairs.

@item @code{inputs} (default: @code{'()})
@itemx @code{native-inputs} (default: @code{'()})
@itemx @code{propagated-inputs} (default: @code{'()})
@cindex inputs, of packages
These fields list dependencies of the package.  Each one is a list of
tuples, where each tuple has a label for the input (a string) as its
first element, a package, origin, or derivation as its second element,
and optionally the name of the output thereof that should be used, which
defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
more on package outputs).  For example, the list below specifies three
inputs:

@example
`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
@end example

@cindex cross compilation, package dependencies
The distinction between @code{native-inputs} and @code{inputs} is
necessary when considering cross-compilation.  When cross-compiling,
dependencies listed in @code{inputs} are built for the @emph{target}
architecture; conversely, dependencies listed in @code{native-inputs}
are built for the architecture of the @emph{build} machine.

@code{native-inputs} is typically used to list tools needed at
build time, but not at run time, such as Autoconf, Automake, pkg-config,
Gettext, or Bison.  @command{guix lint} can report likely mistakes in
this area (@pxref{Invoking guix lint}).

@anchor{package-propagated-inputs}
Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
specified packages will be automatically installed alongside the package
they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
package}}, for information on how @command{guix package} deals with
propagated inputs.)

For example this is necessary when a C/C++ library needs headers of
another library to compile, or when a pkg-config file refers to another
one @i{via} its @code{Requires} field.

Another example where @code{propagated-inputs} is useful is for languages
that lack a facility to record the run-time search path akin to the
@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, GHC, and
more.  To ensure that libraries written in those languages can find
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.

@item @code{self-native-input?} (default: @code{#f})
This is a Boolean field telling whether the package should use itself as
a native input when cross-compiling.

@item @code{outputs} (default: @code{'("out")})
The list of output names of the package.  @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.

@item @code{native-search-paths} (default: @code{'()})
@itemx @code{search-paths} (default: @code{'()})
A list of @code{search-path-specification} objects describing
search-path environment variables honored by the package.

@item @code{replacement} (default: @code{#f})
This must be either @code{#f} or a package object that will be used as a
@dfn{replacement} for this package.  @xref{Security Updates, grafts},
for details.

@item @code{synopsis}
A one-line description of the package.

@item @code{description}
A more elaborate description of the package.

@item @code{license}
The license of the package; a value from @code{(guix licenses)},
or a list of such values.

@item @code{home-page}
The URL to the home-page of the package, as a string.

@item @code{supported-systems} (default: @var{%supported-systems})
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.

@item @code{maintainers} (default: @code{'()})
The list of maintainers of the package, as @code{maintainer} objects.

@item @code{location} (default: source location of the @code{package} form)
The source location of the package.  It is useful to override this when
inheriting from another package, in which case this field is not
automatically corrected.
@end table
@end deftp


@node origin Reference
@subsection @code{origin} Reference

This section summarizes all the options available in @code{origin}
declarations (@pxref{Defining Packages}).

@deftp {Data Type} origin
This is the data type representing a source code origin.

@table @asis
@item @code{uri}
An object containing the URI of the source.  The object type depends on
the @code{method} (see below).  For example, when using the
@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
values are: a URL represented as a string, or a list thereof.

@item @code{method}
A procedure that handles the URI.

Examples include:

@table @asis
@item @var{url-fetch} from @code{(guix download)}
download a file from the HTTP, HTTPS, or FTP URL specified in the
@code{uri} field;

@vindex git-fetch
@item @var{git-fetch} from @code{(guix git-download)}
clone the Git version control repository, and check out the revision
specified in the @code{uri} field as a @code{git-reference} object; a
@code{git-reference} looks like this:

@example
(git-reference
  (url "git://git.debian.org/git/pkg-shadow/shadow")
  (commit "v4.1.5.1"))
@end example
@end table

@item @code{sha256}
A bytevector containing the SHA-256 hash of the source.  Typically the
@code{base32} form is used here to generate the bytevector from a
base-32 string.

You can obtain this information using @code{guix download}
(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
guix hash}).

@item @code{file-name} (default: @code{#f})
The file name under which the source code should be saved.  When this is
@code{#f}, a sensible default value will be used in most cases.  In case
the source is fetched from a URL, the file name from the URL will be
used.  For version control checkouts, it is recommended to provide the
file name explicitly because the default is not very descriptive.

@item @code{patches} (default: @code{'()})
A list of file names containing patches to be applied to the source.

@item @code{snippet} (default: @code{#f})
A G-expression (@pxref{G-Expressions}) or S-expression that will be run
in the source directory.  This is a convenient way to modify the source,
sometimes more convenient than a patch.

@item @code{patch-flags} (default: @code{'("-p1")})
A list of command-line flags that should be passed to the @code{patch}
command.

@item @code{patch-inputs} (default: @code{#f})
Input packages or derivations to the patching process.  When this is
@code{#f}, the usual set of inputs necessary for patching are provided,
such as GNU@tie{}Patch.

@item @code{modules} (default: @code{'()})
A list of Guile modules that should be loaded during the patching
process and while running the code in the @code{snippet} field.

@item @code{patch-guile} (default: @code{#f})
The Guile package that should be used in the patching process.  When
this is @code{#f}, a sensible default is used.
@end table
@end deftp


@node Build Systems
@section Build Systems

@cindex build system
Each package definition specifies a @dfn{build system} and arguments for
that build system (@pxref{Defining Packages}).  This @code{build-system}
field represents the build procedure of the package, as well as implicit
dependencies of that build procedure.

Build systems are @code{<build-system>} objects.  The interface to
create and manipulate them is provided by the @code{(guix build-system)}
module, and actual build systems are exported by specific modules.

@cindex bag (low-level package representation)
Under the hood, build systems first compile package objects to
@dfn{bags}.  A @dfn{bag} is like a package, but with less
ornamentation---in other words, a bag is a lower-level representation of
a package, which includes all the inputs of that package, including some
that were implicitly added by the build system.  This intermediate
representation is then compiled to a derivation (@pxref{Derivations}).

Build systems accept an optional list of @dfn{arguments}.  In package
definitions, these are passed @i{via} the @code{arguments} field
(@pxref{Defining Packages}).  They are typically keyword arguments
(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
Guile Reference Manual}).  The value of these arguments is usually
evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
by the daemon (@pxref{Derivations}).

The main build system is @var{gnu-build-system}, which implements the
standard build procedure for GNU and many other packages.  It
is provided by the @code{(guix build-system gnu)} module.

@defvr {Scheme Variable} gnu-build-system
@var{gnu-build-system} represents the GNU Build System, and variants
thereof (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).

@cindex build phases
In a nutshell, packages using it are configured, built, and installed with
the usual @code{./configure && make && make check && make install}
command sequence.  In practice, a few additional steps are often needed.
All these steps are split up in separate @dfn{phases},
notably@footnote{Please see the @code{(guix build gnu-build-system)}
modules for more details about the build phases.}:

@table @code
@item unpack
Unpack the source tarball, and change the current directory to the
extracted source tree.  If the source is actually a directory, copy it
to the build tree, and enter that directory.

@item patch-source-shebangs
Patch shebangs encountered in source files so they refer to the right
store file names.  For instance, this changes @code{#!/bin/sh} to
@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.

@item configure
Run the @file{configure} script with a number of default options, such
as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
by the @code{#:configure-flags} argument.

@item build
Run @code{make} with the list of flags specified with
@code{#:make-flags}.  If the @code{#:parallel-build?} argument is true
(the default), build with @code{make -j}.

@item check
Run @code{make check}, or some other target specified with
@code{#:test-target}, unless @code{#:tests? #f} is passed.  If the
@code{#:parallel-tests?} argument is true (the default), run @code{make
check -j}.

@item install
Run @code{make install} with the flags listed in @code{#:make-flags}.

@item patch-shebangs
Patch shebangs on the installed executable files.

@item strip
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
is false), copying them to the @code{debug} output when available
(@pxref{Installing Debugging Files}).
@end table

@vindex %standard-phases
The build-side module @code{(guix build gnu-build-system)} defines
@var{%standard-phases} as the default list of build phases.
@var{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.

The list of phases used for a particular package can be changed with the
@code{#:phases} parameter.  For instance, passing:

@example
#:phases (modify-phases %standard-phases (delete 'configure))
@end example

means that all the phases described above will be used, except the
@code{configure} phase.

In addition, this build system ensures that the ``standard'' environment
for GNU packages is available.  This includes tools such as GCC, libc,
Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
build-system gnu)} module for a complete list).  We call these the
@dfn{implicit inputs} of a package, because package definitions do not
have to mention them.
@end defvr

Other @code{<build-system>} objects are defined to support other
conventions and tools used by free software packages.  They inherit most
of @var{gnu-build-system}, and differ mainly in the set of inputs
implicitly added to the build process, and in the list of phases
executed.  Some of these build systems are listed below.

@defvr {Scheme Variable} ant-build-system
This variable is exported by @code{(guix build-system ant)}.  It
implements the build procedure for Java packages that can be built with
@url{http://ant.apache.org/, Ant build tool}.

It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
provided by the @code{icedtea} package to the set of inputs.  Different
packages can be specified with the @code{#:ant} and @code{#:jdk}
parameters, respectively.

When the original package does not provide a suitable Ant build file,
the parameter @code{#:jar-name} can be used to generate a minimal Ant
build file @file{build.xml} with tasks to build the specified jar
archive.

The parameter @code{#:build-target} can be used to specify the Ant task
that should be run during the @code{build} phase.  By default the
``jar'' task will be run.

@end defvr

@defvr {Scheme Variable} cmake-build-system
This variable is exported by @code{(guix build-system cmake)}.  It
implements the build procedure for packages using the
@url{http://www.cmake.org, CMake build tool}.

It automatically adds the @code{cmake} package to the set of inputs.
Which package is used can be specified with the @code{#:cmake}
parameter.

The @code{#:configure-flags} parameter is taken as a list of flags
passed to the @command{cmake} command.  The @code{#:build-type}
parameter specifies in abstract terms the flags passed to the compiler;
it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
debugging information''), which roughly means that code is compiled with
@code{-O2 -g}, as is the case for Autoconf-based packages by default.
@end defvr

@defvr {Scheme Variable} glib-or-gtk-build-system
This variable is exported by @code{(guix build-system glib-or-gtk)}.  It
is intended for use with packages making use of GLib or GTK+.

This build system adds the following two phases to the ones defined by
@var{gnu-build-system}:

@table @code
@item glib-or-gtk-wrap
The phase @code{glib-or-gtk-wrap} ensures that programs in
@file{bin/} are able to find GLib ``schemas'' and
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
modules}.  This is achieved by wrapping the programs in launch scripts
that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
environment variables.

It is possible to exclude specific package outputs from that wrapping
process by listing their names in the
@code{#:glib-or-gtk-wrap-excluded-outputs} parameter.  This is useful
when an output is known not to contain any GLib or GTK+ binaries, and
where wrapping would gratuitously add a dependency of that output on
GLib and GTK+.

@item glib-or-gtk-compile-schemas
The phase @code{glib-or-gtk-compile-schemas} makes sure that all
@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
GSettings schemas} of GLib are compiled.  Compilation is performed by the
@command{glib-compile-schemas} program.  It is provided by the package
@code{glib:bin} which is automatically imported by the build system.
The @code{glib} package providing @command{glib-compile-schemas} can be
specified with the @code{#:glib} parameter.
@end table

Both phases are executed after the @code{install} phase.
@end defvr

@defvr {Scheme Variable} python-build-system
This variable is exported by @code{(guix build-system python)}.  It
implements the more or less standard build procedure used by Python
packages, which consists in running @code{python setup.py build} and
then @code{python setup.py install --prefix=/gnu/store/@dots{}}.

For packages that install stand-alone Python programs under @code{bin/},
it takes care of wrapping these programs so that their @code{PYTHONPATH}
environment variable points to all the Python libraries they depend on.

Which Python package is used to perform the build can be specified with
the @code{#:python} parameter.  This is a useful way to force a package
to be built for a specific version of the Python interpreter, which
might be necessary if the package is only compatible with a single
interpreter version.
@end defvr

@defvr {Scheme Variable} perl-build-system
This variable is exported by @code{(guix build-system perl)}.  It
implements the standard build procedure for Perl packages, which either
consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
followed by @code{Build} and @code{Build install}; or in running
@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
@code{make} and @code{make install}, depending on which of
@code{Build.PL} or @code{Makefile.PL} is present in the package
distribution.  Preference is given to the former if both @code{Build.PL}