guix.texi

This is equivalent to the reference below, which explicitly names the
commit:

@lisp
(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
@end lisp
@end deftp

For Mercurial repositories, the module @code{(guix hg-download)} defines
the @code{hg-fetch} origin method and @code{hg-reference} data type for
support of the Mercurial version control system.

@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
           [name]
Return a fixed-output derivation that fetches @var{ref}, a
@code{<hg-reference>} object.  The output is expected to have recursive
hash @var{hash} of type @var{hash-algo} (a symbol).  Use @var{name} as
the file name, or a generic name if @code{#false}.
@end deffn

@node Defining Package Variants
@section Defining Package Variants

@cindex customizing packages
@cindex variants, of packages
One of the nice things with Guix is that, given a package definition,
you can easily @emph{derive} variants of that package---for a different
upstream version, with different dependencies, different compilation
options, and so on.  Some of these custom packages can be defined
straight from the command line (@pxref{Package Transformation Options}).
This section describes how to define package variants in code.  This can
be useful in ``manifests'' (@pxref{profile-manifest,
@option{--manifest}}) and in your own package collection
(@pxref{Creating a Channel}), among others!

@cindex inherit, for package definitions
As discussed earlier, packages are first-class objects in the Scheme
language.  The @code{(guix packages)} module provides the @code{package}
construct to define new package objects (@pxref{package Reference}).
The easiest way to define a package variant is using the @code{inherit}
keyword together with @code{package}.  This allows you to inherit from a
package definition while overriding the fields you want.

For example, given the @code{hello} variable, which contains a
definition for the current version of GNU@tie{}Hello, here's how you
would define a variant for version 2.2 (released in 2006, it's
vintage!):

@lisp
(use-modules (gnu packages base))    ;for 'hello'

(define hello-2.2
  (package
    (inherit hello)
    (version "2.2")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
@end lisp

The example above corresponds to what the @option{--with-source} package
transformation option does.  Essentially @code{hello-2.2} preserves all
the fields of @code{hello}, except @code{version} and @code{source},
which it overrides.  Note that the original @code{hello} variable is
still there, in the @code{(gnu packages base)} module, unchanged.  When
you define a custom package like this, you are really @emph{adding} a
new package definition; the original one remains available.

You can just as well define variants with a different set of
dependencies than the original package.  For example, the default
@code{gdb} package depends on @code{guile}, but since that is an
optional dependency, you can define a variant that removes that
dependency like so:

@lisp
(use-modules (gnu packages gdb)    ;for 'gdb'
             (srfi srfi-1))        ;for 'alist-delete'

(define gdb-sans-guile
  (package
    (inherit gdb)
    (inputs (alist-delete "guile"
                          (package-inputs gdb)))))
@end lisp

The @code{alist-delete} call above removes the tuple from the
@code{inputs} field that has @code{"guile"} as its first element
(@pxref{SRFI-1 Association Lists,,, guile, GNU Guile Reference
Manual}).

In some cases, you may find it useful to write functions
(``procedures'', in Scheme parlance) that return a package based on some
parameters.  For example, consider the @code{luasocket} library for the
Lua programming language.  We want to create @code{luasocket} packages
for major versions of Lua.  One way to do that is to define a procedure
that takes a Lua package and returns a @code{luasocket} package that
depends on it:

@lisp
(define (make-lua-socket name lua)
  ;; Return a luasocket package built with LUA.
  (package
    (name name)
    (version "3.0")
    ;; several fields omitted
    (inputs
     `(("lua" ,lua)))
    (synopsis "Socket library for Lua")))

(define-public lua5.1-socket
  (make-lua-socket "lua5.1-socket" lua-5.1))

(define-public lua5.2-socket
  (make-lua-socket "lua5.2-socket" lua-5.2))
@end lisp

Here we have defined packages @code{lua5.1-socket} and
@code{lua5.2-socket} by calling @code{make-lua-socket} with different
arguments.  @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
more info on procedures.  Having top-level public definitions for these
two packages means that they can be referred to from the command line
(@pxref{Package Modules}).

@cindex package transformations
These are pretty simple package variants.  As a convenience, the
@code{(guix transformations)} module provides a high-level interface
that directly maps to the more sophisticated package transformation
options (@pxref{Package Transformation Options}):

@deffn {Scheme Procedure} options->transformation @var{opts}
Return a procedure that, when passed an object to build (package,
derivation, etc.), applies the transformations specified by @var{opts} and returns
the resulting objects.  @var{opts} must be a list of symbol/string pairs such as:

@lisp
((with-branch . "guile-gcrypt=master")
 (without-tests . "libgcrypt"))
@end lisp

Each symbol names a transformation and the corresponding string is an argument
to that transformation.
@end deffn

For instance, a manifest equivalent to this command:

@example
guix build guix \
  --with-branch=guile-gcrypt=master \
  --with-debug-info=zlib
@end example

@noindent
... would look like this:

@lisp
(use-modules (guix transformations))

(define transform
  ;; The package transformation procedure.
  (options->transformation
   '((with-branch . "guile-gcrypt=master")
     (with-debug-info . "zlib"))))

(packages->manifest
 (list (transform (specification->package "guix"))))
@end lisp

@cindex input rewriting
@cindex dependency graph rewriting
The @code{options->transformation} procedure is convenient, but it's
perhaps also not as flexible as you may like.  How is it implemented?
The astute reader probably noticed that most package transformation
options go beyond the superficial changes shown in the first examples of
this section: they involve @dfn{input rewriting}, whereby the dependency
graph of a package is rewritten by replacing specific inputs by others.

Dependency graph rewriting, for the purposes of swapping packages in the
graph, is what the @code{package-input-rewriting} procedure in
@code{(guix packages)} implements.

@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
           [@var{rewrite-name}] [#:deep? #t]
Return a procedure that, when passed a package, replaces its direct and
indirect dependencies, including implicit inputs when @var{deep?} is
true, 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:

@lisp
(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 lisp

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

The following variant of @code{package-input-rewriting} can match packages to
be replaced by name rather than by identity.

@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
Return a procedure that, given a package, applies the given
@var{replacements} to all the package graph, including implicit inputs
unless @var{deep?} is false.  @var{replacements} is a list of
spec/procedures pair; each spec is a package specification such as
@code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
package and returns a replacement for that package.
@end deffn

The example above could be rewritten this way:

@lisp
(define libressl-instead-of-openssl
  ;; Replace all the packages called "openssl" with LibreSSL.
  (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
@end lisp

The key difference here is that, this time, packages are matched by spec and
not by identity.  In other words, any package in the graph that is called
@code{openssl} will be replaced.

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?}] [#:deep? #f]
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.  When @var{deep?} is true, @var{proc} is
applied to implicit inputs as well.
@end deffn


@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}).
The @code{package-with-c-toolchain} is an example of a way to change the
implicit inputs that a package's build system pulls in (@pxref{package
Reference, @code{package-with-c-toolchain}}).

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 @code{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
@code{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 @option{--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
@code{%standard-phases} as the default list of build phases.
@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.

@xref{Build Phases}, for more info on build phases and ways to customize
them.

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 @code{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{https://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 @file{include} of the @code{out} output and
their libraries to the subdirectory @file{lib} the @code{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.

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-asdf-configuration} 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.

By default, all the @file{.asd} files present in the sources are read to
find system definitions.  The @code{#:asd-files} parameter can be used
to specify the list of @file{.asd} files to read.  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, or if several systems must be compiled, the
@code{#:asd-systems} parameter can be used to specify the list of system
names.

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

It adds @code{rustc} and @code{cargo} to the set of inputs.
A different Rust package can be specified with the @code{#:rust} parameter.

Regular cargo dependencies should be added to the package definition similarly
to other packages; those needed only at build time to native-inputs, others to
inputs.  If you need to add source-only crates then you should add them to via
the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
spec can be a package or a source definition.  Note that the spec must
evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
file at its root, or it will be ignored.  Similarly, cargo dev-dependencies
should be added to the package definition via the
@code{#:cargo-development-inputs} parameter.

In its @code{configure} phase, this build system will make any source inputs
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
parameters available to cargo.  It will also remove an included
@code{Cargo.lock} file to be recreated by @code{cargo} during the
@code{build} phase.  The @code{package} phase will run @code{cargo package}
to create a source crate for future use.  The @code{install} phase installs
the binaries defined by the crate.  Unless @code{install-source? #f} is
defined it will also install a source crate repository of itself and unpacked
sources, to ease in future hacking on rust packages.
@end defvr

@defvr {Scheme Variable} chicken-build-system
This variable is exported by @code{(guix build-system chicken)}.  It
builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
``eggs'' or ``extensions''.  CHICKEN generates C source code, which then
gets compiled by a C compiler, in this case GCC.

This build system adds @code{chicken} to the package inputs, as well as
the packages of @code{gnu-build-system}.

The build system can't (yet) deduce the egg's name automatically, so just like
with @code{go-build-system} and its @code{#:import-path}, you should define
@code{#:egg-name} in the package's @code{arguments} field.

For example, if you are packaging the @code{srfi-1} egg:

@lisp
(arguments '(#:egg-name "srfi-1"))
@end lisp

Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
because CHICKEN doesn't embed absolute references in compiled eggs.
Test dependencies should go to @code{native-inputs}, as usual.
@end defvr

@defvr {Scheme Variable} copy-build-system
This variable is exported by @code{(guix build-system copy)}.  It
supports builds of simple packages that don't require much compiling,
mostly just moving files around.

It adds much of the @code{gnu-build-system} packages to the set of
inputs.  Because of this, the @code{copy-build-system} does not require
all the boilerplate code often needed for the
@code{trivial-build-system}.

To further simplify the file installation process, an
@code{#:install-plan} argument is exposed to let the packager specify
which files go where.  The install plan is a list of @code{(@var{source}
@var{target} [@var{filters}])}.  @var{filters} are optional.

@itemize
@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
@itemize
@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
@item Otherwise install @var{source} as @var{target}.
@end itemize

@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
the trailing slash of @var{target} is implied with the same meaning
as above.
@itemize
@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
@code{#:exclude-regexp}, only select files are installed depending on
the filters.  Each filters is specified by a list of strings.
@itemize
@item With @code{#:include}, install all the files which the path suffix matches
at least one of the elements in the given list.
@item With @code{#:include-regexp}, install all the files which the
subpaths match at least one of the regular expressions in the given
list.
@item The @code{#:exclude} and @code{#:exclude-regexp} filters
are the complement of their inclusion counterpart.  Without @code{#:include} flags,
install all files but those matching the exclusion filters.
If both inclusions and exclusions are specified, the exclusions are done
on top of the inclusions.
@end itemize
@end itemize
In all cases, the paths relative to @var{source} are preserved within
@var{target}.
@end itemize

Examples:

@itemize
@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
@file{share/my-app/sub/file}.
@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
@file{share/my-app/file}.
@end itemize
@end defvr


@cindex Clojure (programming language)
@cindex simple Clojure build system
@defvr {Scheme Variable} clojure-build-system
This variable is exported by @code{(guix build-system clojure)}.  It implements
a simple build procedure for @uref{https://clojure.org/, Clojure} packages
using plain old @code{compile} in Clojure.  Cross-compilation is not supported
yet.

It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
@code{#:zip} parameters, respectively.

A list of source directories, test directories and jar names can be specified
with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
parameters, respectively.  Compile directory and main class can be specified
with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
Other parameters are documented below.

This build system is an extension of @code{ant-build-system}, but with the
following phases changed:

@table @code

@item build
This phase calls @code{compile} in Clojure to compile source files and runs
@command{jar} to create jars from both source files and compiled files
according to the include list and exclude list specified in
@code{#:aot-include} and @code{#:aot-exclude}, respectively.  The exclude list
has priority over the include list.  These lists consist of symbols
representing Clojure libraries or the special keyword @code{#:all} representing
all Clojure libraries found under the source directories.  The parameter
@code{#:omit-source?} decides if source should be included into the jars.

@item check
This phase runs tests according to the include list and exclude list specified
in @code{#:test-include} and @code{#:test-exclude}, respectively.  Their
meanings are analogous to that of @code{#:aot-include} and
@code{#:aot-exclude}, except that the special keyword @code{#:all} now
stands for all Clojure libraries found under the test directories.  The
parameter @code{#:tests?} decides if tests should be run.

@item install
This phase installs all jars built previously.
@end table

Apart from the above, this build system also contains an additional phase:

@table @code

@item install-doc
This phase installs all top-level files with base name matching
@code{%doc-regex}.  A different regex can be specified with the
@code{#:doc-regex} parameter.  All files (recursively) inside the documentation
directories specified in @code{#:doc-dirs} are installed as well.
@end table
@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{https://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} dune-build-system
This variable is exported by @code{(guix build-system dune)}.  It
supports builds of packages using @uref{https://dune.build/, Dune}, a build
tool for the OCaml programming language.  It is implemented as an extension
of the @code{ocaml-build-system} which is described below.  As such, the
@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
system.

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

There is no @code{configure} phase because dune packages typically don't
need to be configured.  The @code{#:build-flags} parameter is taken as a
list of flags passed to the @code{dune} command during the build.

The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
command instead of the more recent @code{dune} command while building
a package.  Its default value is @code{#f}.

The @code{#:package} parameter can be passed to specify a package name, which
is useful when a package contains multiple packages and you want to build
only one of them.  This is equivalent to passing the @code{-p} argument to
@code{dune}.
@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 install their source code into
the built output.  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
@code{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 @env{XDG_DATA_DIRS} and @env{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} guile-build-system
This build system is for Guile packages that consist exclusively of Scheme
code and that are so lean that they don't even have a makefile, let alone a
@file{configure} script.  It compiles Scheme code using @command{guild
compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
installs the @file{.scm} and @file{.go} files in the right place.  It also
installs documentation.

This build system supports cross-compilation by using the
@option{--target} option of @samp{guild compile}.

Packages built with @code{guile-build-system} must provide a Guile package in
their @code{native-inputs} field.
@end defvr

@defvr {Scheme Variable} julia-build-system
This variable is exported by @code{(guix build-system julia)}.  It
implements the build procedure used by @uref{https://julialang.org/,
julia} packages, which essentially is similar to running @samp{julia -e
'using Pkg; Pkg.add(package)'} in an environment where
@env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
Tests are run by calling @code{/test/runtests.jl}.

The Julia package name is read from the file @file{Project.toml}.  This
value can be overridden by passing the argument @code{#:julia-package-name}
(which must be correctly capitalized).

Julia packages usually manage their binary dependencies via
@code{JLLWrappers.jl}, a Julia package that creates a module (named
after the wrapped library followed by @code{_jll.jl}.

To add the binary path @code{_jll.jl} packages, you need to patch the
files under @file{src/wrappers/}, replacing the call to the macro
@code{JLLWrappers.@@generate_wrapper_header}, adding as a secound
argument containing the store path the binary.

As an example, in the MbedTLS Julia package, we add a build phase
(@pxref{Build Phases}) to insert the absolute file name of the wrapped
MbedTLS package:

@lisp
(add-after 'unpack 'override-binary-path
  (lambda* (#:key inputs #:allow-other-keys)
    (for-each (lambda (wrapper)
                (substitute* wrapper
                  (("generate_wrapper_header.*")
                   (string-append
                    "generate_wrapper_header(\"MbedTLS\", \""
                    (assoc-ref inputs "mbedtls-apache") "\")\n"))))
              ;; There's a Julia file for each platform, override them all.
              (find-files "src/wrappers/" "\\.jl$"))))
@end lisp

Some older packages that aren't using @file{Package.toml} yet, will require
this file to be created, too.  The function @code{julia-create-package-toml}
helps creating the file.  You need to pass the outputs and the source of the
package, it's name (the same as the @code{file-name} parameter), the package
uuid, the package version, and a list of dependencies specified by their name
and their uuid.
@end defvr

@defvr {Scheme Variable} maven-build-system
This variable is exported by @code{(guix build-system maven)}.  It implements
a build procedure for @uref{https://maven.apache.org, Maven} packages.  Maven
is a dependency and lifecycle management tool for Java.  A user of Maven
specifies dependencies and plugins in a @file{pom.xml} file that Maven reads.
When Maven does not have one of the dependencies or plugins in its repository,
it will download them and use them to build the package.

The maven build system ensures that maven will not try to download any
dependency by running in offline mode.  Maven will fail if a dependency is
missing.  Before running Maven, the @file{pom.xml} (and subprojects) are
modified to specify the version of dependencies and plugins that match the
versions available in the guix build environment.  Dependencies and plugins
must be installed in the fake maven repository at @file{lib/m2}, and are
symlinked into a proper repository before maven is run.  Maven is instructed
to use that repository for the build and installs built artifacts there.
Changed files are copied to the @file{lib/m2} directory of the package output.

You can specify a @file{pom.xml} file with the @code{#:pom-file} argument,
or let the build system use the default @file{pom.xml} file in the sources.

In case you need to specify a dependency's version manually, you can use the
@code{#:local-packages} argument.  It takes an association list where the key
is the groupId of the package and its value is an association list where the
key is the artifactId of the package and its value is the version you want to
override in the @file{pom.xml}.

Some packages use dependencies or plugins that are not useful at runtime nor
at build time in Guix.  You can alter the @file{pom.xml} file to remove them
using the @code{#:exclude} argument.  Its value is an association list where
the key is the groupId of the plugin or dependency you want to remove, and
the value is a list of artifactId you want to remove.

You can override the default @code{jdk} and @code{maven} packages with the
corresponding argument, @code{#:jdk} and @code{#:maven}.

The @code{#:maven-plugins} argument is a list of maven plugins used during
the build, with the same format as the @code{inputs} fields of the package
declaration.  Its default value is @code{(default-maven-plugins)} which is
also exported.
@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 @env{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 @env{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} renpy-build-system
This variable is exported by @code{(guix build-system renpy)}.  It implements
the more or less standard build procedure used by Ren'py games, which consists
of loading @code{#:game} once, thereby creating bytecode for it.

It further creates a wrapper script in @code{bin/} and a desktop entry in
@code{share/applications}, both of which can be used to launch the game.

Which Ren'py package is used can be specified with @code{#:renpy}.
Games can also be installed in outputs other than ``out'' by using
@code{#:output}.
@end defvr

@defvr {Scheme Variable} qt-build-system
This variable is exported by @code{(guix build-system qt)}.  It
is intended for use with applications using Qt or KDE.

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

@table @code
@item check-setup
The phase @code{check-setup} prepares the environment for running
the checks as commonly used by Qt test programs.
For now this only sets some environment variables:
@code{QT_QPA_PLATFORM=offscreen},
@code{DBUS_FATAL_WARNINGS=0} and
@code{CTEST_OUTPUT_ON_FAILURE=1}.

This phase is added before the @code{check} phase.
It's a separate phase to ease adjusting if necessary.

@item qt-wrap
The phase @code{qt-wrap}
searches for Qt5 plugin paths, QML paths and some XDG in the inputs
and output.  In case some path is found, all programs in the output's
@file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
are wrapped in scripts defining the necessary environment variables.

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

This phase is added after the @code{install} phase.
@end table
@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{https://r-project.org, R}
packages, which essentially is little more than running @samp{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
@env{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