Next: Build Phases, Previous: 书写清单, Up: 编程接口 [Contents][Index]
Each package definition specifies a build system and arguments for
that build system (see 定义软件包). This build-system
field represents the build procedure of the package, as well as implicit
dependencies of that build procedure.
Build systems are <build-system> objects. The interface to create
and manipulate them is provided by the (guix build-system) module,
and actual build systems are exported by specific modules.
Under the hood, build systems first compile package objects to bags.
A 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 (see Derivations). The package-with-c-toolchain is an
example of a way to change the implicit inputs that a package’s build system
pulls in (see package-with-c-toolchain).
Build systems accept an optional list of arguments. In package
definitions, these are passed via the arguments field
(see 定义软件包). They are typically keyword arguments
(see keyword arguments in Guile in GNU Guile
Reference Manual). The value of these arguments is usually evaluated in
the build stratum—i.e., by a Guile process launched by the daemon
(see Derivations).
The main build system is gnu-build-system, which implements the
standard build procedure for GNU and many other packages. It is provided by
the (guix build-system gnu) module.
gnu-build-system represents the GNU Build System, and variants
thereof (see configuration and makefile conventions in GNU Coding Standards).
In a nutshell, packages using it are configured, built, and installed with
the usual ./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 phases. See 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 (guix
build-system gnu) module for a complete list). We call these the
implicit inputs of a package, because package definitions do not have
to mention them.
This build system supports a number of keyword arguments, which can be
passed via the arguments field of a package. Here are some of
the main parameters:
#:phasesThis argument specifies build-side code that evaluates to an alist of build phases. See Build Phases, for more information.
#:configure-flagsThis is a list of flags (strings) passed to the configure script.
See 定义软件包, for an example.
#:make-flagsThis list of strings contains flags passed as arguments to make
invocations in the build, check, and install phases.
#:out-of-source?This Boolean, #f by default, indicates whether to run builds in a
build directory separate from the source tree.
When it is true, the configure phase creates a separate build
directory, changes to that directory, and runs the configure script
from there. This is useful for packages that require it, such as
glibc.
#:tests?This Boolean, #t by default, indicates whether the check phase
should run the package’s test suite.
#:test-targetThis string, "check" by default, gives the name of the makefile
target used by the check phase.
#:parallel-build?#:parallel-tests?These Boolean values specify whether to build, respectively run the test
suite, in parallel, with the -j flag of make. When they
are true, make is passed -jn, where n is the
number specified as the --cores option of guix-daemon or
that of the guix client command (see --cores).
#:validate-runpath?This Boolean, #t by default, determines whether to “validate” the
RUNPATH of ELF binaries (.so shared libraries as well as
executables) previously installed by the install phase.
See the validate-runpath phase, for
details.
#:substitutable?This Boolean, #t by default, tells whether the package outputs should
be substitutable—i.e., whether users should be able to obtain substitutes
for them instead of building locally (see substitutes).
#:allowed-references#:disallowed-referencesWhen true, these arguments must be a list of dependencies that must not appear among the references of the build results. If, upon build completion, some of these references are retained, the build process fails.
This is useful to ensure that a package does not erroneously keep a
reference to some of it build-time inputs, in cases where doing so would,
for example, unnecessarily increase its size (see Invoking guix size).
Most other build systems support these keyword arguments.
Other <build-system> objects are defined to support other conventions
and tools used by free software packages. They inherit most of
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.
This variable is exported by (guix build-system agda). It implements
a build procedure for Agda libraries.
It adds agda to the set of inputs. A different Agda can be specified
with the #:agda key.
The #:plan key is a list of cons cells (regexp
. parameters), where regexp is a regexp that should match the
.agda files to build, and parameters is an optional list of
parameters that will be passed to agda when type-checking it.
When the library uses Haskell to generate a file containing all imports, the
convenience #:gnu-and-haskell? can be set to #t to add
ghc and the standard inputs of gnu-build-system to the input
list. You will still need to manually add a phase or tweak the
'build phase, as in the definition of agda-stdlib.
This variable is exported by (guix build-system ant). It implements
the build procedure for Java packages that can be built with
Ant build tool.
It adds both ant and the Java Development Kit (JDK) as provided
by the icedtea package to the set of inputs. Different packages can
be specified with the #:ant and #:jdk parameters,
respectively.
When the original package does not provide a suitable Ant build file, the
parameter #:jar-name can be used to generate a minimal Ant build file
build.xml with tasks to build the specified jar archive. In this
case the parameter #:source-dir can be used to specify the source
sub-directory, defaulting to “src”.
The #: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 #:test-include parameter can be used to specify the
list of junit tests to run. It defaults to (list "**/*Test.java").
The #:test-exclude can be used to disable some tests. It defaults to
(list "**/Abstract*.java"), because abstract classes cannot be run as
tests.
The parameter #:build-target can be used to specify the Ant task that
should be run during the build phase. By default the “jar” task
will be run.
This variable is exported by (guix build-system android-ndk). It
implements a build procedure for Android NDK (native development kit)
packages using a Guix-specific build process.
The build system assumes that packages install their public interface
(header) files to the subdirectory include of the out output
and their libraries to the subdirectory lib the out output.
It’s also assumed that the union of all the dependencies of a package has no conflicting files.
For the time being, cross-compilation is not supported - so right now the libraries and header files are assumed to be host tools.
These variables, exported by (guix build-system asdf), implement
build procedures for Common Lisp packages using
“ASDF”. ASDF is a system
definition facility for Common Lisp programs and libraries.
The 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 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 sbcl-
for asdf-build-system/sbcl.
Additionally, the corresponding source package should be labeled using the
same convention as Python packages (see Python模块), using the
cl- prefix.
In order to create executable programs and images, the build-side procedures
build-program and build-image can be used. They should be
called in a build phase after the create-asdf-configuration phase, so
that the system which was just built can be used within the resulting
image. build-program requires a list of Common Lisp expressions to
be passed as the #:entry-program argument.
By default, all the .asd files present in the sources are read to
find system definitions. The #:asd-files parameter can be used to
specify the list of .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 #:test-asd-file
parameter. If it is not set, the files <system>-tests.asd,
<system>-test.asd, tests.asd, and 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
#:asd-systems parameter can be used to specify the list of system
names.
This variable is exported by (guix build-system cargo). It supports
builds of packages using Cargo, the build tool of the
Rust programming language.
It adds rustc and cargo to the set of inputs. A different
Rust package can be specified with the #: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 #: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 Cargo.toml file at its root, or it will be ignored.
Similarly, cargo dev-dependencies should be added to the package definition
via the #:cargo-development-inputs parameter.
In its configure phase, this build system will make any source inputs
specified in the #:cargo-inputs and #:cargo-development-inputs
parameters available to cargo. It will also remove an included
Cargo.lock file to be recreated by cargo during the
build phase. The package phase will run cargo package
to create a source crate for future use. The install phase installs
the binaries defined by the crate. Unless 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.
This variable is exported by (guix build-system chicken). It builds
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 chicken to the package inputs, as well as the
packages of gnu-build-system.
The build system can’t (yet) deduce the egg’s name automatically, so just
like with go-build-system and its #:import-path, you should
define #:egg-name in the package’s arguments field.
For example, if you are packaging the srfi-1 egg:
(arguments '(#:egg-name "srfi-1"))
Egg dependencies must be defined in propagated-inputs, not
inputs because CHICKEN doesn’t embed absolute references in compiled
eggs. Test dependencies should go to native-inputs, as usual.
This variable is exported by (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 gnu-build-system packages to the set of inputs.
Because of this, the copy-build-system does not require all the
boilerplate code often needed for the trivial-build-system.
To further simplify the file installation process, an #:install-plan
argument is exposed to let the packager specify which files go where. The
install plan is a list of (source target
[filters]). filters are optional.
#:include, #:include-regexp, #:exclude,
#:exclude-regexp, only select files are installed depending on the
filters. Each filters is specified by a list of strings.
#:include, install all the files which the path suffix matches
at least one of the elements in the given list.
#:include-regexp, install all the files which the
subpaths match at least one of the regular expressions in the given list.
#:exclude and #:exclude-regexp filters
are the complement of their inclusion counterpart. Without #: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.
#:output argument
can be used to specify which output label the files should be installed to.
In all cases, the paths relative to source are preserved within target.
Examples:
("foo/bar" "share/my-app/"): Install bar to share/my-app/bar.
("foo/bar" "share/my-app/baz"): Install bar to share/my-app/baz.
("foo/" "share/my-app"): Install the content of foo inside share/my-app,
e.g., install foo/sub/file to share/my-app/sub/file.
("foo/" "share/my-app" #:include ("sub/file")): Install only foo/sub/file to
share/my-app/sub/file.
("foo/sub" "share/my-app" #:include ("file")): Install foo/sub/file to
share/my-app/file.
("foo/doc" "share/my-app/doc" #:output "doc"): Install
"foo/doc" to "share/my-app/doc" within the "doc"
output.
This variable is exported by (guix build-system vim). It is an
extension of the copy-build-system, installing Vim and Neovim plugins
into locations where these two text editors know to find their plugins,
using their packpaths.
Packages which are prefixed with vim- will be installed in Vim’s
packpath, while those prefixed with neovim- will be installed in
Neovim’s packpath. If there is a doc directory with the plugin then
helptags will be generated automatically.
There are a couple of keywords added with the vim-build-system:
plugin-name it is possible to set the name of the plugin.
While by default this is set to the name and version of the package, it is
often more helpful to set this to name which the upstream author calls their
plugin. This is the name used for :packadd from inside Vim.
install-plan it is possible to augment the built-in
install-plan of the vim-build-system. This is particularly helpful
if you have files which should be installed in other locations. For more
information about using the install-plan, see the
copy-build-system (see copy-build-system).
#:vim it is possible to add this package to Vim’s packpath,
in addition to if it is added automatically because of the vim-
prefix in the package’s name.
#:neovim it is possible to add this package to Neovim’s
packpath, in addition to if it is added automatically because of the
neovim- prefix in the package’s name.
#:mode it is possible to adjust the path which the plugin is
installed into. By default the plugin is installed into start and
other options are available, including opt. Adding a plugin into
opt will mean you will need to run, for example, :packadd
foo to load the foo plugin from inside of Vim.
This variable is exported by (guix build-system clojure). It
implements a simple build procedure for Clojure
packages using plain old compile in Clojure. Cross-compilation is
not supported yet.
It adds clojure, icedtea and zip to the set of inputs.
Different packages can be specified with the #:clojure, #:jdk
and #:zip parameters, respectively.
A list of source directories, test directories and jar names can be
specified with the #:source-dirs, #:test-dirs and
#:jar-names parameters, respectively. Compile directory and main
class can be specified with the #:compile-dir and #:main-class
parameters, respectively. Other parameters are documented below.
This build system is an extension of ant-build-system, but with the
following phases changed:
buildThis phase calls compile in Clojure to compile source files and runs
jar to create jars from both source files and compiled files
according to the include list and exclude list specified in
#:aot-include and #:aot-exclude, respectively. The exclude
list has priority over the include list. These lists consist of symbols
representing Clojure libraries or the special keyword #:all
representing all Clojure libraries found under the source directories. The
parameter #:omit-source? decides if source should be included into
the jars.
checkThis phase runs tests according to the include list and exclude list
specified in #:test-include and #:test-exclude, respectively.
Their meanings are analogous to that of #:aot-include and
#:aot-exclude, except that the special keyword #:all now
stands for all Clojure libraries found under the test directories. The
parameter #:tests? decides if tests should be run.
installThis phase installs all jars built previously.
Apart from the above, this build system also contains an additional phase:
install-docThis phase installs all top-level files with base name matching
%doc-regex. A different regex can be specified with the
#:doc-regex parameter. All files (recursively) inside the
documentation directories specified in #:doc-dirs are installed as
well.
This variable is exported by (guix build-system cmake). It
implements the build procedure for packages using the
CMake build tool.
It automatically adds the cmake package to the set of inputs. Which
package is used can be specified with the #:cmake parameter.
The #:configure-flags parameter is taken as a list of flags passed to
the cmake command. The #:build-type parameter specifies in
abstract terms the flags passed to the compiler; it defaults to
"RelWithDebInfo" (short for “release mode with debugging
information”), which roughly means that code is compiled with -O2
-g, as is the case for Autoconf-based packages by default.
This variable is exported by (guix build-system composer). It
implements the build procedure for packages using
Composer, the PHP package manager.
It automatically adds the php package to the set of inputs. Which
package is used can be specified with the #:php parameter.
The #:test-target parameter is used to control which script is run
for the tests. By default, the test script is run if it exists. If
the script does not exist, the build system will run phpunit from the
source directory, assuming there is a phpunit.xml file.
This variable is exported by (guix build-system dune). It supports
builds of packages using Dune, a build tool for
the OCaml programming language. It is implemented as an extension of the
ocaml-build-system which is described below. As such, the
#:ocaml and #:findlib parameters can be passed to this build
system.
It automatically adds the dune package to the set of inputs. Which
package is used can be specified with the #:dune parameter.
There is no configure phase because dune packages typically don’t
need to be configured. The #:build-flags parameter is taken as a
list of flags passed to the dune command during the build.
The #:jbuild? parameter can be passed to use the jbuild
command instead of the more recent dune command while building a
package. Its default value is #f.
The #: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 -p
argument to dune.
This variable is exported by (guix build-system elm). It implements
a build procedure for Elm packages similar to
‘elm install’.
The build system adds an Elm compiler package to the set of inputs. The
default compiler package (currently elm-sans-reactor) can be
overridden using the #:elm argument. Additionally, Elm packages
needed by the build system itself are added as implicit inputs if they are
not already present: to suppress this behavior, use the
#:implicit-elm-package-inputs? argument, which is primarily useful
for bootstrapping.
The "dependencies" and "test-dependencies" in an Elm package’s
elm.json file correspond to propagated-inputs and
inputs, respectively.
Elm requires a particular structure for package names: see Elm包
for more details, including utilities provided by (guix build-system
elm).
There are currently a few noteworthy limitations to elm-build-system:
{ "type": "package" } in their
elm.json files. Using elm-build-system to build Elm
applications (which declare { "type": "application" }) is
possible, but requires ad-hoc modifications to the build phases. For
examples, see the definitions of the elm-todomvc example application
and the elm package itself (because the front-end for the ‘elm
reactor’ command is an Elm application).
ELM_HOME, but this does not yet work well with
elm-build-system. This limitation primarily affects Elm
applications, because they specify exact versions for their dependencies,
whereas Elm packages specify supported version ranges. As a workaround, the
example applications mentioned above use the
patch-application-dependencies procedure provided by (guix
build elm-build-system) to rewrite their elm.json files to refer to
the package versions actually present in the build environment.
Alternatively, Guix package transformations (see Defining Package Variants) could be used to rewrite an application’s entire dependency
graph.
elm-test-rs nor
the Node.js-based elm-test runner has been packaged for Guix yet.
This variable is exported by (guix build-system go). It implements a
build procedure for Go packages using the standard
Go
build mechanisms.
The user is expected to provide a value for the key #:import-path
and, in some cases, #:unpack-path. The
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 #:unpack-path should be used in
such cases.
Packages that provide Go libraries should install their source code into the
built output. The key #:install-source?, which defaults to
#t, controls whether or not the source code is installed. It can be
set to #f for packages that only provide executable files.
Packages can be cross-built, and if a specific architecture or operating
system is desired then the keywords #:goarch and #:goos can be
used to force the package to be built for that architecture and operating
system. The combinations known to Go can be found
in their
documentation.
The key #:go can be used to specify the Go compiler package with
which to build the package.
The phase check provides a wrapper for go test which builds a
test binary (or multiple binaries), vets the code and then runs the test
binary. Build, test and test binary flags can be provided as
#:test-flags parameter, default is '(). See go help
test and go help testflag for more details.
The key #:embed-files, default is '(), provides a list of
future embedded files or regexps matching files. They will be copied to
build directory after unpack phase. See
https://pkg.go.dev/embed for more details.
This variable is exported by (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
gnu-build-system:
glib-or-gtk-wrapThe phase glib-or-gtk-wrap ensures that programs in bin/ are
able to find GLib “schemas” and
GTK+
modules. This is achieved by wrapping the programs in launch scripts that
appropriately set the XDG_DATA_DIRS and GTK_PATH environment
variables.
It is possible to exclude specific package outputs from that wrapping
process by listing their names in the
#: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+.
glib-or-gtk-compile-schemasThe phase glib-or-gtk-compile-schemas makes sure that all
GSettings schemas of GLib are compiled. Compilation is performed by the
glib-compile-schemas program. It is provided by the package
glib:bin which is automatically imported by the build system. The
glib package providing glib-compile-schemas can be
specified with the #:glib parameter.
Both phases are executed after the install phase.
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
configure script. It compiles Scheme code using guild
compile (see Compilation in GNU Guile Reference Manual) and
installs the .scm and .go files in the right place. It also
installs documentation.
This build system supports cross-compilation by using the --target option of ‘guild compile’.
Packages built with guile-build-system must provide a Guile package
in their native-inputs field.
This variable is exported by (guix build-system julia). It
implements the build procedure used by julia
packages, which essentially is similar to running ‘julia -e 'using Pkg;
Pkg.add(package)'’ in an environment where JULIA_LOAD_PATH contains
the paths to all Julia package inputs. Tests are run by calling
/test/runtests.jl.
The Julia package name and uuid is read from the file Project.toml.
These values can be overridden by passing the argument
#:julia-package-name (which must be correctly capitalized) or
#:julia-package-uuid.
Julia packages usually manage their binary dependencies via
JLLWrappers.jl, a Julia package that creates a module (named after
the wrapped library followed by _jll.jl.
To add the binary path _jll.jl packages, you need to patch the files
under src/wrappers/, replacing the call to the macro
JLLWrappers.@generate_wrapper_header, adding as a second argument
containing the store path the binary.
As an example, in the MbedTLS Julia package, we add a build phase (see Build Phases) to insert the absolute file name of the wrapped MbedTLS package:
(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") "\")\n"))))
;; There's a Julia file for each platform, override them all.
(find-files "src/wrappers/" "\\.jl$"))))
Some older packages that aren’t using Project.toml yet, will require
this file to be created, too. It is internally done if the arguments
#:julia-package-name and #:julia-package-uuid are provided.
This variable is exported by (guix build-system maven). It
implements a build procedure for Maven
packages. Maven is a dependency and lifecycle management tool for Java. A
user of Maven specifies dependencies and plugins in a 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 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 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 lib/m2 directory of the package output.
You can specify a pom.xml file with the #:pom-file argument,
or let the build system use the default pom.xml file in the sources.
In case you need to specify a dependency’s version manually, you can use the
#: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 pom.xml.
Some packages use dependencies or plugins that are not useful at runtime nor
at build time in Guix. You can alter the pom.xml file to remove them
using the #: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 jdk and maven packages with the
corresponding argument, #:jdk and #:maven.
The #:maven-plugins argument is a list of maven plugins used during
the build, with the same format as the inputs fields of the package
declaration. Its default value is (default-maven-plugins) which is
also exported.
This variable is exported by (guix build-system minetest). It
implements a build procedure for Minetest
mods, which consists of copying Lua code, images and other resources to the
location Minetest searches for mods. The build system also minimises PNG
images and verifies that Minetest can load the mod without errors.
This variable is exported by (guix build-system minify). It
implements a minification procedure for simple JavaScript packages.
It adds uglify-js to the set of inputs and uses it to compress all
JavaScript files in the src directory. A different minifier package
can be specified with the #: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 src
directory, the parameter #:javascript-files can be used to specify a
list of file names to feed to the minifier.
This variable is exported by (guix build-system mozilla). It sets
the --target and --host configuration flags to what software
developed by Mozilla expects – due to historical reasons, Mozilla software
expects --host to be the system that is cross-compiled from and
--target to be the system that is cross-compiled to, contrary to the
standard Autotools conventions.
This variable is exported by (guix build-system ocaml). It
implements a build procedure for 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 setup.ml file present at the top-level, it
will run ocaml setup.ml -configure, ocaml setup.ml -build and
ocaml setup.ml -install. The build system will assume that this file
was generated by 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
#:configure-flags and #:build-flags. The #:test-flags
key can be passed to change the set of flags used to enable tests. The
#:use-make? key can be used to bypass this system in the build and
install phases.
When the package has a configure file, it is assumed that it is a
hand-made configure script that requires a different argument format than in
the gnu-build-system. You can add more flags with the
#:configure-flags key.
When the package has a Makefile file (or #:use-make? is
#t), it will be used and more flags can be passed to the build and
install phases with the #: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
ocaml pkg/pkg.ml or ocaml pkg/build.ml and take care of
providing the path to the required findlib module. Additional flags can be
passed via the #:build-flags key. Install is taken care of by
opam-installer. In this case, the opam package must be
added to the 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 .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 CAML_LD_LIBRARY_PATH. This
variable points to lib/ocaml/site-lib/stubslibs and this is where
.so libraries should be installed.
This variable is exported by (guix build-system python). It
implements the more or less standard build procedure used by Python
packages, which consists in running python setup.py build and then
python setup.py install --prefix=/gnu/store/….
For packages that install stand-alone Python programs under bin/, it
takes care of wrapping these programs so that their GUIX_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
#: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 setup.py under control of setuptools,
much like pip does. Some packages are not compatible with
setuptools (and pip), thus you can disable this by setting the
#:use-setuptools? parameter to #f.
If a "python" output is available, the package is installed into it
instead of the default "out" output. This is useful for packages that
include a Python package as only a part of the software, and thus want to
combine the phases of python-build-system with another build system.
Python bindings are a common usecase.
This is a variable exported by guix build-system pyproject. It is
based on python-build-system, and adds support for
pyproject.toml and PEP 517.
It also supports a variety of build backends and test frameworks.
The API is slightly different from python-build-system:
#:use-setuptools? and #:test-target is removed.
#:configure-flags is changed. Instead of a list this option must be a
JSON object, whose interpretation depends on the build backend. For instance
the example from PEP
517 should be written as '(@ ("CC" "gcc") ("--global-option"
("--some-global-option")) ("--build-option" ("--build-option1"
"--build-option2")))
#:backend-path is added. It defaults to #false, but when set
to a list it will be appended to Python’s search path and overrides the
definition in pyproject.toml.
#:build-backend is added. It defaults to #false and will try
to guess the appropriate backend based on pyproject.toml.
#:test-backend is added. It defaults to #false and will guess
an appropriate test backend based on what is available in package inputs.
#:test-flags is added. The default is '(). These flags are
passed as arguments to the test command. Note that flags for verbose output
is always enabled on supported backends.
It is considered “experimental” in that the implementation details are not set in stone yet, however users are encouraged to try it for new Python projects (even those using setup.py). The API is subject to change, but any breaking changes in the Guix channel will be dealt with.
Eventually this build system will be deprecated and merged back into python-build-system, probably some time in 2024.
This variable is exported by (guix build-system perl). It implements
the standard build procedure for Perl packages, which either consists in
running perl Build.PL --prefix=/gnu/store/…, followed by
Build and Build install; or in running perl Makefile.PL
PREFIX=/gnu/store/…, followed by make and make install,
depending on which of Build.PL or Makefile.PL is present in
the package distribution. Preference is given to the former if both
Build.PL and Makefile.PL exist in the package distribution.
This preference can be reversed by specifying #t for the
#:make-maker? parameter.
The initial perl Makefile.PL or perl Build.PL invocation
passes flags specified by the #:make-maker-flags or
#:module-build-flags parameter, respectively.
Which Perl package is used can be specified with #:perl.
This variable is exported by (guix build-system renpy). It
implements the more or less standard build procedure used by Ren’py games,
which consists of loading #:game once, thereby creating bytecode for
it.
It further creates a wrapper script in bin/ and a desktop entry in
share/applications, both of which can be used to launch the game.
Which Ren’py package is used can be specified with #:renpy. Games
can also be installed in outputs other than “out” by using
#:output.
This variable is exported by (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
cmake-build-system:
check-setupThe phase check-setup prepares the environment for running the checks
as commonly used by Qt test programs. For now this only sets some
environment variables: QT_QPA_PLATFORM=offscreen,
DBUS_FATAL_WARNINGS=0 and CTEST_OUTPUT_ON_FAILURE=1.
This phase is added before the check phase. It’s a separate phase to
ease adjusting if necessary.
qt-wrapThe phase 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 bin/, sbin/, libexec/ and
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 #: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 install phase.
This variable is exported by (guix build-system r). It implements
the build procedure used by R packages, which
essentially is little more than running ‘R CMD INSTALL
--library=/gnu/store/…’ in an environment where R_LIBS_SITE
contains the paths to all R package inputs. Tests are run after
installation using the R function tools::testInstalledPackage.
This variable is exported by (guix build-system rakudo). It
implements the build procedure used by Rakudo
for Perl6 packages. It installs the package to
/gnu/store/…/NAME-VERSION/share/perl6 and installs the
binaries, library files and the resources, as well as wrap the files under
the bin/ directory. Tests can be skipped by passing #f to the
tests? parameter.
Which rakudo package is used can be specified with rakudo. Which
perl6-tap-harness package used for the tests can be specified with
#:prove6 or removed by passing #f to the with-prove6?
parameter. Which perl6-zef package used for tests and installing can be
specified with #:zef or removed by passing #f to the
with-zef? parameter.
This variable is exported by (guix build-system rebar). It
implements a build procedure around rebar3, a
build system for programs written in the Erlang language.
It adds both rebar3 and the erlang to the set of inputs.
Different packages can be specified with the #:rebar and
#:erlang parameters, respectively.
This build system is based on gnu-build-system, but with the
following phases changed:
unpackThis phase, after unpacking the source like the gnu-build-system
does, checks for a file contents.tar.gz at the top-level of the
source. If this file exists, it will be unpacked, too. This eases handling
of package hosted at https://hex.pm/, the Erlang and Elixir package
repository.
bootstrapconfigureThere are no bootstrap and configure phase because erlang
packages typically don’t need to be configured.
buildThis phase runs rebar3 compile with the flags listed in
#:rebar-flags.
checkUnless #:tests? #f is passed, this phase runs rebar3 eunit, or
some other target specified with #:test-target, with the flags listed
in #:rebar-flags,
installThis installs the files created in the default profile, or some other
profile specified with #:install-profile.
This variable is exported by (guix build-system texlive). It is used
to build TeX packages in batch mode with a specified engine. The build
system sets the TEXINPUTS variable to find all TeX source files in the
inputs.
By default it tries to run luatex on all .ins files, and if it
fails to find any, on all .dtx files. A different engine and format
can be specified with, respectively, the #:tex-engine and
#:tex-format arguments. Different build targets can be specified
with the #:build-targets argument, which expects a list of file
names.
It also generates font metrics (i.e., .tfm files) out of Metafont
files whenever possible. Likewise, it can also create TeX formats (i.e.,
.fmt files) listed in the #:create-formats argument, and
generate a symbolic link from bin/ directory to any script located in
texmf-dist/scripts/, provided its file name is listed in
#:link-scripts argument.
The build system adds texlive-bin from (gnu packages tex) to
the native inputs. It can be overridden with the #:texlive-bin
argument.
The package texlive-latex-bin, from the same module, contains most of
the tools for building TeX Live packages; for convenience, it is also added
by default to the native inputs. However, this can be troublesome when
building a dependency of texlive-latex-bin itself. In this
particular situation, the #:texlive-latex-bin? argument should be set
to #f.
This variable is exported by (guix build-system ruby). It implements
the RubyGems build procedure used by Ruby packages, which involves running
gem build followed by gem install.
The 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 #:ruby
parameter. A list of additional flags to be passed to the gem
command can be specified with the #:gem-flags parameter.
This variable is exported by (guix build-system waf). It implements
a build procedure around the waf script. The common
phases—configure, build, and install—are
implemented by passing their names as arguments to the waf script.
The waf script is executed by the Python interpreter. Which Python
package is used to run the script can be specified with the #:python
parameter.
This variable is exported by (guix build-system zig). It implements
the build procedures for the Zig build system
(zig build command).
Selecting this build system adds zig to the package inputs, in
addition to the packages of gnu-build-system.
There is no configure phase because Zig packages typically do not
need to be configured. The #:zig-build-flags parameter is a list of
flags that are passed to the zig command during the build. The
#:zig-test-flags parameter is a list of flags that are passed to the
zig test command during the check phase. The default compiler
package can be overridden with the #:zig argument.
The optional zig-release-type parameter declares the type of
release. Possible values are: safe, fast, or
small. The default value is #f, which causes the release flag
to be omitted from the zig command. That results in a debug
build.
This variable is exported by (guix build-system scons). It
implements the build procedure used by the SCons software construction
tool. This build system runs scons to build the package, scons
test to run tests, and then scons install to install the package.
Additional flags to be passed to scons can be specified with the
#:scons-flags parameter. The default build and install targets can
be overridden with #:build-targets and #:install-targets
respectively. The version of Python used to run SCons can be specified by
selecting the appropriate SCons package with the #:scons parameter.
This variable is exported by (guix build-system haskell). It
implements the Cabal build procedure used by Haskell packages, which
involves running runhaskell Setup.hs configure
--prefix=/gnu/store/… and runhaskell Setup.hs build. Instead
of installing the package by running runhaskell Setup.hs install, to
avoid trying to register libraries in the read-only compiler store
directory, the build system uses runhaskell Setup.hs copy, followed
by runhaskell Setup.hs register. In addition, the build system
generates the package documentation by running runhaskell Setup.hs
haddock, unless #:haddock? #f is passed. Optional Haddock
parameters can be passed with the help of the #:haddock-flags
parameter. If the file Setup.hs is not found, the build system looks
for Setup.lhs instead.
Which Haskell compiler is used can be specified with the #:haskell
parameter which defaults to ghc.
This variable is exported by (guix build-system dub). It implements
the Dub build procedure used by D packages, which involves running dub
build and dub run. Installation is done by copying the files
manually.
Which D compiler is used can be specified with the #:ldc parameter
which defaults to ldc.
This variable is exported by (guix build-system emacs). It
implements an installation procedure similar to the packaging system of
Emacs itself (see Packages in The GNU Emacs Manual).
It first creates the package-autoloads.el
This variable is exported by (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.
This variable is exported by (guix build-system meson). It
implements the build procedure for packages that use
Meson as their build system.
It adds both Meson and Ninja to the set of
inputs, and they can be changed with the parameters #:meson and
#:ninja if needed.
This build system is an extension of gnu-build-system, but with the
following phases changed to some specific for Meson:
configureThe phase runs meson with the flags specified in
#:configure-flags. The flag --buildtype is always set to
debugoptimized unless something else is specified in
#:build-type.
buildThe phase runs ninja to build the package in parallel by default, but
this can be changed with #:parallel-build?.
checkThe phase runs ‘meson test’ with a base set of options that cannot be
overridden. This base set of options can be extended via the
#:test-options argument, for example to select or skip a specific
test suite.
installThe phase runs ninja install and can not be changed.
Apart from that, the build system also adds the following phases:
fix-runpathThis 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 RUNPATH where needed. It also removes
references to libraries left over from the build phase by meson, such
as test dependencies, that aren’t actually required for the program to run.
glib-or-gtk-wrapThis phase is the phase provided by glib-or-gtk-build-system, and it
is not enabled by default. It can be enabled with #:glib-or-gtk?.
glib-or-gtk-compile-schemasThis phase is the phase provided by glib-or-gtk-build-system, and it
is not enabled by default. It can be enabled with #:glib-or-gtk?.
linux-module-build-system allows building Linux kernel modules.
This build system is an extension of gnu-build-system, but with the
following phases changed:
configureThis phase configures the environment so that the Linux kernel’s Makefile can be used to build the external kernel module.
buildThis phase uses the Linux kernel’s Makefile in order to build the external kernel module.
installThis phase uses the Linux kernel’s Makefile in order to install the external kernel module.
It is possible and useful to specify the Linux kernel to use for building
the module (in the arguments form of a package using the
linux-module-build-system, use the key #:linux to specify it).
This variable is exported by (guix build-system node). It implements
the build procedure used by Node.js, which
implements an approximation of the npm install command, followed by
an npm test command.
Which Node.js package is used to interpret the npm commands can be
specified with the #:node parameter which defaults to node.
This variable is exported by (guix build-system tree-sitter). It
implements procedures to compile grammars for the
Tree-sitter parsing
library. It essentially runs tree-sitter generate to translate
grammar.js grammars to JSON and then to C. Which it then compiles to
native code.
Tree-sitter packages may support multiple grammars, so this build system
supports a #:grammar-directories keyword to specify a list of
locations where a grammar.js file may be found.
Grammars sometimes depend on each other, such as C++ depending on C and TypeScript depending on JavaScript. You may use inputs to declare such dependencies.
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.
This variable is exported by (guix build-system trivial).
This build system requires a #:builder argument. This argument must
be a Scheme expression that builds the package output(s)—as with
build-expression->derivation (see build-expression->derivation).
This variable is exported by (guix build-system channel).
This build system is meant primarily for internal use. A package using this
build system must have a channel specification as its source field
(see 频道); alternatively, its source can be a directory name, in
which case an additional #:commit argument must be supplied to
specify the commit being built (a hexadecimal string).
Optionally, a #:channels argument specifying additional channels can
be provided.
The resulting package is a Guix instance of the given channel(s), similar to
how guix time-machine would build it.
Next: Build Phases, Previous: 书写清单, Up: 编程接口 [Contents][Index]