guix.texi

In addition, @command{guix pack} supports all the common build options
(@pxref{Common Build Options}) and all the package transformation
options (@pxref{Package Transformation Options}).


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

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

@quotation Note
If you're looking for a way to produce archives in a format suitable for
tools other than Guix, @pxref{Invoking guix pack}.
@end quotation

@cindex exporting store items
To export store files as an archive to standard output, run:

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

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

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

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

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

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

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

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

@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the store on the
target machine.  The @code{--missing} option can help figure out which
items are missing from the target store.  The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).

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

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

The main options are:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@end table

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

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

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

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

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

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

@node Defining Packages
@section Defining Packages

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}), troubleshooting any build failures
you encounter (@pxref{Debugging Build Failures}).  You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
@vindex GUIX_PACKAGE_PATH
Lastly, @pxref{Package Modules}, for information
on how to extend the distribution by adding your own package definitions
to @code{GUIX_PACKAGE_PATH}.

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

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

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

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

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

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

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

@cindex package transformations
@cindex input rewriting
@cindex dependency tree rewriting
Packages can be manipulated in arbitrary ways.  An example of a useful
transformation is @dfn{input rewriting}, whereby the dependency tree of
a package is rewritten by replacing specific inputs by others:

@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
           [@var{rewrite-name}]
Return a procedure that, when passed a package, replaces its direct and
indirect dependencies (but not its implicit inputs) according to
@var{replacements}.  @var{replacements} is a list of package pairs; the
first element of each pair is the package to replace, and the second one
is the replacement.

Optionally, @var{rewrite-name} is a one-argument procedure that takes
the name of a package and returns its new name after rewrite.
@end deffn

@noindent
Consider this example:

@example
(define libressl-instead-of-openssl
  ;; This is a procedure to replace OPENSSL by LIBRESSL,
  ;; recursively.
  (package-input-rewriting `((,openssl . ,libressl))))

(define git-with-libressl
  (libressl-instead-of-openssl git))
@end example

@noindent
Here we first define a rewriting procedure that replaces @var{openssl}
with @var{libressl}.  Then we use it to define a @dfn{variant} of the
@var{git} package that uses @var{libressl} instead of @var{openssl}.
This is exactly what the @option{--with-input} command-line option does
(@pxref{Package Transformation Options, @option{--with-input}}).

A more generic procedure to rewrite a package dependency graph is
@code{package-mapping}: it supports arbitrary changes to nodes in the
graph.

@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
Return a procedure that, given a package, applies @var{proc} to all the packages
depended on and returns the resulting package.  The procedure stops recursion
when @var{cut?} returns true for a given package.
@end deffn

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

Examples include:

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

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

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

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

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

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

@item @code{patches} (default: @code{'()})
A list of file names, origins, or file-like objects (@pxref{G-Expressions,
file-like objects}) pointing to patches to be applied to the source.

This list of patches must be unconditional.  In particular, it cannot
depend on the value of @code{%current-system} or
@code{%current-target-system}.

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

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

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

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

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


@node Build Systems
@section Build Systems

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

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

@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.  In this case the parameter @code{#:source-dir} can be used to
specify the source sub-directory, defaulting to ``src''.

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
@code{(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.

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} android-ndk-build-system
@cindex Android distribution
@cindex 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 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.

It's also assumed that the union of all the dependencies of a package
has no conflicting files.

For the time being, cross-compilation is not supported - so right now
the libraries and header files are assumed to be host tools.

@end defvr

@defvr {Scheme Variable} asdf-build-system/source
@defvrx {Scheme Variable} asdf-build-system/sbcl
@defvrx {Scheme Variable} asdf-build-system/ecl

These variables, exported by @code{(guix build-system asdf)}, implement
build procedures for Common Lisp packages using
@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
definition facility for Common Lisp programs and libraries.

The @code{asdf-build-system/source} system installs the packages in
source form, and can be loaded using any common lisp implementation, via
ASDF.  The others, such as @code{asdf-build-system/sbcl}, install binary
systems in the format which a particular implementation understands.
These build systems can also be used to produce executable programs, or
lisp images which contain a set of packages pre-loaded.

The build system uses naming conventions.  For binary packages, the
package name should be prefixed with the lisp implementation, such as
@code{sbcl-} for @code{asdf-build-system/sbcl}.

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
@code{#:test-asd-file} parameter.  If it is not set, the files
@code{<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.

@end defvr

@defvr {Scheme Variable} cargo-build-system
@cindex Rust programming language
@cindex Cargo (Rust build system)
This variable is exported by @code{(guix build-system cargo)}.  It
supports builds of packages using Cargo, the build tool of the
@uref{https://www.rust-lang.org, Rust programming language}.

In its @code{configure} phase, this build system replaces dependencies
specified in the @file{Carto.toml} file with inputs to the Guix package.
The @code{install} phase installs the binaries, and it also installs the
source code and @file{Cargo.toml} file.
@end defvr

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

It automatically adds the @code{cmake} package to the set of inputs.
Which 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} go-build-system
This variable is exported by @code{(guix build-system go)}.  It
implements a build procedure for Go packages using the standard
@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
Go build mechanisms}.

The user is expected to provide a value for the key @code{#:import-path}
and, in some cases, @code{#:unpack-path}.  The
@url{https://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.

Packages that provide Go libraries should be installed along with their
source code.  The key @code{#:install-source?}, which defaults to
@code{#t}, controls whether or not the source code is installed.  It can
be set to @code{#f} for packages that only provide executable files.
@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} minify-build-system
This variable is exported by @code{(guix build-system minify)}.  It
implements a minification procedure for simple JavaScript packages.

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.

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

@defvr {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.

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