guix.texi

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 with @code{Pkg.test}.

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

@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{--buildtype} is always set to
@code{debugoptimized} 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 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.

@cindex build phases
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).
@end defvr

@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 Build Utilities
@section Build Utilities

As soon as you start writing non-trivial package definitions
(@pxref{Defining Packages}) or other build actions
(@pxref{G-Expressions}), you will likely start looking for helpers for
``shell-like'' actions---creating directories, copying and deleting
files recursively, manipulating build phases, and so on.  The
@code{(guix build utils)} module provides such utility procedures.

Most build systems load @code{(guix build utils)} (@pxref{Build
Systems}).  Thus, when writing custom build phases for your package
definitions, you can usually assume those procedures are in scope.

When writing G-expressions, you can import @code{(guix build utils)} on
the ``build side'' using @code{with-imported-modules} and then put it in
scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
guile, GNU Guile Reference Manual}):

@lisp
(with-imported-modules '((guix build utils))  ;import it
  (computed-file "empty-tree"
                 #~(begin
                     ;; Put it in scope.
                     (use-modules (guix build utils))

                     ;; Happily use its 'mkdir-p' procedure.
                     (mkdir-p (string-append #$output "/a/b/c")))))
@end lisp

The remainder of this section is the reference for most of the utility
procedures provided by @code{(guix build utils)}.

@c TODO Document what's missing.

@subsection Dealing with Store File Names

This section documents procedures that deal with store file names.

@deffn {Scheme Procedure} %store-directory
Return the directory name of the store.
@end deffn

@deffn {Scheme Procedure} store-file-name? @var{file}
Return true if @var{file} is in the store.
@end deffn

@deffn {Scheme Procedure} strip-store-file-name @var{file}
Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
The result is typically a @code{"@var{package}-@var{version}"} string.
@end deffn

@deffn {Scheme Procedure} package-name->name+version @var{name}
Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
values: @code{"foo"} and @code{"0.9.1b"}.  When the version part is
unavailable, @var{name} and @code{#f} are returned.  The first hyphen
followed by a digit is considered to introduce the version part.
@end deffn

@subsection File Types

The procedures below deal with files and file types.

@deffn {Scheme Procedure} directory-exists? @var{dir}
Return @code{#t} if @var{dir} exists and is a directory.
@end deffn

@deffn {Scheme Procedure} executable-file? @var{file}
Return @code{#t} if @var{file} exists and is executable.
@end deffn

@deffn {Scheme Procedure} symbolic-link? @var{file}
Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
@end deffn

@deffn {Scheme Procedure} elf-file? @var{file}
@deffnx {Scheme Procedure} ar-file? @var{file}
@deffnx {Scheme Procedure} gzip-file? @var{file}
Return @code{#t} if @var{file} is, respectively, an ELF file, an
@code{ar} archive (such as a @file{.a} static library), or a gzip file.
@end deffn

@deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
If @var{file} is a gzip file, reset its embedded timestamp (as with
@command{gzip --no-name}) and return true.  Otherwise return @code{#f}.
When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
@end deffn

@subsection File Manipulation

The following procedures and macros help create, modify, and delete
files.  They provide functionality comparable to common shell utilities
such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
@command{sed}.  They complement Guile's extensive, but low-level, file
system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).

@deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
Run @var{body} with @var{directory} as the process's current directory.

Essentially, this macro changes the current directory to @var{directory}
before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
guile, GNU Guile Reference Manual}).  It changes back to the initial
directory when the dynamic extent of @var{body} is left, be it @i{via}
normal procedure return or @i{via} a non-local exit such as an
exception.
@end deffn

@deffn {Scheme Procedure} mkdir-p @var{dir}
Create directory @var{dir} and all its ancestors.
@end deffn

@deffn {Scheme Procedure} install-file @var{file} @var{directory}
Create @var{directory} if it does not exist and copy @var{file} in there
under the same name.
@end deffn

@deffn {Scheme Procedure} make-file-writable @var{file}
Make @var{file} writable for its owner.
@end deffn

@deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
  [#:log (current-output-port)] [#:follow-symlinks? #f] [#:keep-mtime? #f]
Copy @var{source} directory to @var{destination}.  Follow symlinks if
@var{follow-symlinks?}  is true; otherwise, just preserve them.  When
@var{keep-mtime?} is true, keep the modification time of the files in
@var{source} on those of @var{destination}.  Write verbose output to the
@var{log} port.
@end deffn

@deffn {Scheme Procedure} delete-file-recursively @var{dir} @
  [#:follow-mounts? #f]
Delete @var{dir} recursively, like @command{rm -rf}, without following
symlinks.  Don't follow mount points either, unless @var{follow-mounts?}
is true.  Report but ignore errors.
@end deffn

@deffn {Scheme Syntax} substitute* @var{file} @
  ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
Substitute @var{regexp} in @var{file} by the string returned by
@var{body}.  @var{body} is evaluated with each @var{match-var} bound to
the corresponding positional regexp sub-expression.  For example:

@lisp
(substitute* file
  (("hello")
   "good morning\n")
  (("foo([a-z]+)bar(.*)$" all letters end)
   (string-append "baz" letter end)))
@end lisp

Here, anytime a line of @var{file} contains @code{hello}, it is replaced
by @code{good morning}.  Anytime a line of @var{file} matches the second
regexp, @code{all} is bound to the complete match, @code{letters} is bound
to the first sub-expression, and @code{end} is bound to the last one.

When one of the @var{match-var} is @code{_}, no variable is bound to the
corresponding match substring.

Alternatively, @var{file} may be a list of file names, in which case
they are all subject to the substitutions.

Be careful about using @code{$} to match the end of a line; by itself it
won't match the terminating newline of a line.
@end deffn

@subsection File Search

@cindex file, searching
This section documents procedures to search and filter files.

@deffn {Scheme Procedure} file-name-predicate @var{regexp}
Return a predicate that returns true when passed a file name whose base
name matches @var{regexp}.
@end deffn

@deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
  [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
Return the lexicographically sorted list of files under @var{dir} for
which @var{pred} returns true.  @var{pred} is passed two arguments: the
absolute file name, and its stat buffer; the default predicate always
returns true.  @var{pred} can also be a regular expression, in which
case it is equivalent to @code{(file-name-predicate @var{pred})}.
@var{stat} is used to obtain file information; using @code{lstat} means
that symlinks are not followed.  If @var{directories?} is true, then
directories will also be included.  If @var{fail-on-error?} is true,
raise an exception upon error.
@end deffn

Here are a few examples where we assume that the current directory is
the root of the Guix source tree:

@lisp
;; List all the regular files in the current directory.
(find-files ".")
@result{} ("./.dir-locals.el" "./.gitignore" @dots{})

;; List all the .scm files under gnu/services.
(find-files "gnu/services" "\\.scm$")
@result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})

;; List ar files in the current directory.
(find-files "." (lambda (file stat) (ar-file? file)))
@result{} ("./libformat.a" "./libstore.a" @dots{})
@end lisp

@deffn {Scheme Procedure} which @var{program}
Return the complete file name for @var{program} as found in
@code{$PATH}, or @code{#f} if @var{program} could not be found.
@end deffn

@subsection Build Phases

@cindex build phases
The @code{(guix build utils)} also contains tools to manipulate
@dfn{build phases} as found in @code{gnu-build-system} and in fact most
build systems (@pxref{Build Systems}).  Build phases are represented as
association lists or ``alists'' (@pxref{Association Lists,,, guile, GNU
Guile Reference Manual}) where each key is a symbol for the name of the
phase, and the associated value is a procedure that accepts an arbitrary
number of arguments.

Guile core and the @code{(srfi srfi-1)} module both provide tools to
manipulate alists.  The @code{(guix build utils)} module complements
those with tools written with build phases in mind.

@cindex build phases, modifying
@deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
Modify @var{phases} sequentially as per each @var{clause}, which may
have one of the following forms:

@lisp
(delete @var{old-phase-name})
(replace @var{old-phase-name} @var{new-phase})
(add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
(add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
@end lisp

Where every @var{phase-name} above is an expression evaluating to a
symbol, and @var{new-phase} an expression evaluating to a procedure.
@end deffn

The example below is taken from the definition of the @code{grep}
package.  It adds a phase to run after the @code{install} phase, called
@code{fix-egrep-and-fgrep}.  That phase is a procedure (@code{lambda*}
is for anonymous procedures) that takes a @code{#:outputs} keyword
argument and ignores extra keyword arguments (@pxref{Optional
Arguments,,, guile, GNU Guile Reference Manual}, for more on
@code{lambda*} and optional and keyword arguments.)  The phase uses
@code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
scripts so that they refer to @code{grep} by its absolute file name:

@lisp
(modify-phases %standard-phases
  (add-after 'install 'fix-egrep-and-fgrep
    ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
    ;; absolute file name instead of searching for it in $PATH.
    (lambda* (#:key outputs #:allow-other-keys)
      (let* ((out (assoc-ref outputs "out"))
             (bin (string-append out "/bin")))
        (substitute* (list (string-append bin "/egrep")
                           (string-append bin "/fgrep"))
          (("^exec grep")
           (string-append "exec " bin "/grep")))
        #t))))
@end lisp

In the example below, phases are modified in two ways: the standard
@code{configure} phase is deleted, presumably because the package does
not have a @file{configure} script or anything similar, and the default
@code{install} phase is replaced by one that manually copies the
executable files to be installed:

@lisp
(modify-phases %standard-phases
  (delete 'configure)      ;no 'configure' script
  (replace 'install
    (lambda* (#:key outputs #:allow-other-keys)
      ;; The package's Makefile doesn't provide an "install"
      ;; rule so do it by ourselves.
      (let ((bin (string-append (assoc-ref outputs "out")
                                "/bin")))
        (install-file "footswitch" bin)
        (install-file "scythe" bin)
        #t))))
@end lisp

@c TODO: Add more examples.

@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