Newer
Older
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 @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.
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 @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
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.
@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.
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 @file{.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}.
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 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{install} phase installs any crate the binaries
if they are defined by the crate.
@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.
@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
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}.
@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
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 not run.
Julia packages require the source @code{file-name} to be the real name of the
package, correctly capitalized.
For packages requiring shared library dependencies, you may need to write the
@file{/deps/deps.jl} file manually. It's usually a line of @code{const
variable = /gnu/store/library.so} for each dependency, plus a void function
@code{check_deps() = nothing}.
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} 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} 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
@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
@defvr {Scheme Variable} rakudo-build-system
This variable is exported by @code{(guix build-system rakudo)}. It
implements the build procedure used by @uref{https://rakudo.org/,
Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
installs the binaries, library files and the resources, as well as wrap
the files under the @code{bin/} directory. Tests can be skipped by
passing @code{#f} to the @code{tests?} parameter.
Which rakudo package is used can be specified with @code{rakudo}.
Which perl6-tap-harness package used for the tests can be specified with
@code{#:prove6} or removed by passing @code{#f} to the
@code{with-prove6?} parameter.
Which perl6-zef package used for tests and installing can be specified
with @code{#:zef} or removed by passing @code{#f} to the
@code{with-zef?} parameter.
@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 @env{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 default build and install targets
can be overridden with @code{#:build-targets} and
@code{#:install-targets} respectively. 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{@code{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. The Elisp
package files are installed directly under @file{share/emacs/site-lisp}.
@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{https://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 @code{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 @option{--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.
Apart from that, the build system also adds the following phases:
@table @code
@item fix-runpath
This phase ensures that all binaries can find the libraries they need.
It searches for required libraries in subdirectories of the package being
built, and adds those to @code{RUNPATH} where needed. It also removes
references to libraries left over from the build phase by
@code{meson-for-build}, such as test dependencies, that aren't actually
required for the program to run.
@item glib-or-gtk-wrap
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
@item glib-or-gtk-compile-schemas
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
@end table
@end defvr
@defvr {Scheme Variable} linux-module-build-system
@code{linux-module-build-system} allows building Linux kernel modules.
This build system is an extension of @code{gnu-build-system}, but with the
following phases changed:
@table @code
@item configure
This phase configures the environment so that the Linux kernel's Makefile
can be used to build the external kernel module.
@item build
This phase uses the Linux kernel's Makefile in order to build the external
kernel module.
@item install
This phase uses the Linux kernel's Makefile in order to install the external
kernel module.
@end table
It is possible and useful to specify the Linux kernel to use for building
the module (in the @code{arguments} form of a package using the
@code{linux-module-build-system}, use the key @code{#:linux} to specify it).
@defvr {Scheme Variable} node-build-system
This variable is exported by @code{(guix build-system node)}. It
implements the build procedure used by @uref{https://nodejs.org,
Node.js}, which implements an approximation of the @code{npm install}
command, followed by an @code{npm test} command.
Which Node.js package is used to interpret the @code{npm} commands can
be specified with the @code{#:node} parameter which defaults to
@code{node}.
@end defvr
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
it provides basically no support: it does not pull any implicit inputs,
and does not have a notion of build phases.
@defvr {Scheme Variable} trivial-build-system
This variable is exported by @code{(guix build-system trivial)}.
This build system requires a @code{#:builder} argument. This argument
must be a Scheme expression that builds the package output(s)---as
with @code{build-expression->derivation} (@pxref{Derivations,
@code{build-expression->derivation}}).
@end defvr
@node The Store
@section The Store
@cindex store
@cindex store items
@cindex store paths
Conceptually, the @dfn{store} is the place where derivations that have
been built successfully are stored---by default, @file{/gnu/store}.
Sub-directories in the store are referred to as @dfn{store items} or
sometimes @dfn{store paths}. The store has an associated database that
contains information such as the store paths referred to by each store
path, and the list of @emph{valid} store items---results of successful
builds. This database resides in @file{@var{localstatedir}/guix/db},
where @var{localstatedir} is the state directory specified @i{via}
@option{--localstatedir} at configure time, usually @file{/var}.
The store is @emph{always} accessed by the daemon on behalf of its clients
(@pxref{Invoking guix-daemon}). To manipulate the store, clients
connect to the daemon over a Unix-domain socket, send requests to it,
and read the result---these are remote procedure calls, or RPCs.
@quotation Note
Users must @emph{never} modify files under @file{/gnu/store} directly.
This would lead to inconsistencies and break the immutability
assumptions of Guix's functional model (@pxref{Introduction}).
@xref{Invoking guix gc, @command{guix gc --verify}}, for information on
how to check the integrity of the store and attempt recovery from
accidental modifications.
@end quotation
The @code{(guix store)} module provides procedures to connect to the
daemon, and to perform RPCs. These are described below. By default,
@code{open-connection}, and thus all the @command{guix} commands,
connect to the local daemon or to the URI specified by the
@env{GUIX_DAEMON_SOCKET} environment variable.
@defvr {Environment Variable} GUIX_DAEMON_SOCKET
When set, the value of this variable should be a file name or a URI
designating the daemon endpoint. When it is a file name, it denotes a
Unix-domain socket to connect to. In addition to file names, the
supported URI schemes are:
@table @code
@item file
@itemx unix
These are for Unix-domain sockets.
@code{file:///var/guix/daemon-socket/socket} is equivalent to
@file{/var/guix/daemon-socket/socket}.
@item guix
@cindex daemon, remote access
@cindex remote access to the daemon
@cindex daemon, cluster setup
@cindex clusters, daemon setup
These URIs denote connections over TCP/IP, without encryption nor
authentication of the remote host. The URI must specify the host name
and optionally a port number (by default port 44146 is used):
guix://master.guix.example.org:1234
This setup is suitable on local networks, such as clusters, where only
trusted nodes may connect to the build daemon at
@code{master.guix.example.org}.
The @option{--listen} option of @command{guix-daemon} can be used to
instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
@item ssh
@cindex SSH access to build daemons
These URIs allow you to connect to a remote daemon over SSH. This
feature requires Guile-SSH (@pxref{Requirements}) and a working
@command{guile} binary in @env{PATH} on the destination machine. It
supports public key and GSSAPI authentication. A typical URL might look
like this:
ssh://charlie@@guix.example.org:22
As for @command{guix copy}, the usual OpenSSH client configuration files
are honored (@pxref{Invoking guix copy}).
@end table
Additional URI schemes may be supported in the future.
@c XXX: Remove this note when the protocol incurs fewer round trips
@c and when (guix derivations) no longer relies on file system access.
@quotation Note
The ability to connect to remote build daemons is considered
experimental as of @value{VERSION}. Please get in touch with us to
share any problems or suggestions you may have (@pxref{Contributing}).
@end quotation
@end defvr
@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
@var{reserve-space?} is true, instruct it to reserve a little bit of
extra space on the file system so that the garbage collector can still
operate should the disk become full. Return a server object.
@var{file} defaults to @code{%default-socket-path}, which is the normal
location given the options that were passed to @command{configure}.
@deffn {Scheme Procedure} close-connection @var{server}
Close the connection to @var{server}.
@defvr {Scheme Variable} current-build-output-port
This variable is bound to a SRFI-39 parameter, which refers to the port
where build and error logs sent by the daemon should be written.
@end defvr
Procedures that make RPCs all take a server object as their first
argument.
@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
@cindex invalid store items
Return @code{#t} when @var{path} designates a valid store item and
@code{#f} otherwise (an invalid item may exist on disk but still be
invalid, for instance because it is the result of an aborted or failed
build.)
A @code{&store-protocol-error} condition is raised if @var{path} is not
prefixed by the store directory (@file{/gnu/store}).
@end deffn