guix.texi

  #: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} 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 filesystem 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 filesystem 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
@code{ocaml 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
@code{#: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.

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
@code{#:configure-flags} key.

When the package has a @file{Makefile} file (or @code{#:use-make?} is
@code{#t}), it will be used and more flags can be passed to the build and
install phases with the @code{#:make-flags} key.

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
@code{ocaml 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
@command{opam-installer}.  In this case, the @code{opam} package must
be added to the @code{native-inputs} field of the package definition.

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
@file{.so} libraries should be installed.
@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.

By default guix calls @code{setup.py} under control of
@code{setuptools}, 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}.
@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}
and @code{Makefile.PL} exist in the package distribution.  This
preference can be reversed by specifying @code{#t} for the
@code{#:make-maker?} parameter.

The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
passes flags specified by the @code{#:make-maker-flags} or
@code{#:module-build-flags} parameter, respectively.

Which Perl package is used can be specified with @code{#:perl}.
@end defvr

@defvr {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
@code{R_LIBS_SITE} contains the paths to all R package inputs.  Tests
are run after installation using the R function
@code{tools::testInstalledPackage}.
@end defvr

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

By default it runs @code{luatex} on all files ending on @code{ins}.  A
different engine and format can be specified with the
@code{#: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
@code{texlive-latex-base} (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 @code{#:tex-directory} parameter tells the build system where to
install the built files under the texmf tree.
@end defvr

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

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

@defvr {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
phases---@code{configure}, @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
@code{#:python} parameter.
@end defvr

@defvr {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,
@code{scons test} to run tests, and then @code{scons install} to install
the package.

Additional flags to be passed to @code{scons} can be specified with the
@code{#:scons-flags} parameter.  The version of Python used to run SCons
can be specified by selecting the appropriate SCons package with the
@code{#:scons} parameter.
@end defvr

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

Which Haskell compiler is used can be specified with the @code{#:haskell}
parameter which defaults to @code{ghc}.
@end defvr

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

Which D compiler is used can be specified with the @code{#:ldc}
parameter which defaults to @code{ldc}.
@end defvr

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

It first creates the @code{@var{package}-autoloads.el} 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
@file{share/emacs/site-lisp/guix.d}.
@end defvr

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

@defvr {Scheme Variable} meson-build-system
This variable is exported by @code{(guix build-system meson)}.  It
implements the build procedure for packages that use
@url{http://mesonbuild.com, Meson} as their build system.

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
@code{meson-for-build}, which is special because it doesn't clear the
@code{RUNPATH} of binaries and libraries when they are installed.

This build system is an extension of @var{gnu-build-system}, but with the
following phases changed to some specific for Meson:

@table @code

@item configure
The phase runs @code{meson} with the flags specified in
@code{#:configure-flags}.  The flag @code{--build-type} is always set to
@code{plain} 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?}.

@item check
The phase runs @code{ninja} with the target specified in @code{#:test-target},
which is @code{"test"} by default.

@item install
The phase runs @code{ninja install} and can not be changed.
@end table

Apart from that, the build system also adds the following phases:

@table @code

@item fix-runpath
This phase tries to locate the local directories in the package being build,
which has libraries that some of the binaries need.  If any are found, they will
be added to the programs @code{RUNPATH}.  It is needed because
@code{meson-for-build} keeps the @code{RUNPATH} of binaries and libraries from
when they are build, but often that is not the @code{RUNPATH} we want.