Next: , Previous: , Up: Programming Interface   [Contents][Index]

4.2 Build Systems

Each package definition specifies a build system and arguments for that build system (see Defining Packages). 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).

Build systems accept an optional list of arguments. In package definitions, these are passed via the arguments field (see Defining Packages). 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.

Scheme Variable: gnu-build-system

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, notably6:


Unpack the source tarball, and change the current directory to the extracted source tree. If the source is actually a directory, copy it to the build tree, and enter that directory.


Patch shebangs encountered in source files so they refer to the right store file names. For instance, this changes #!/bin/sh to #!/gnu/store/…-bash-4.3/bin/sh.


Run the configure script with a number of default options, such as --prefix=/gnu/store/…, as well as the options specified by the #:configure-flags argument.


Run make with the list of flags specified with #:make-flags. If the #:parallel-build? argument is true (the default), build with make -j.


Run make check, or some other target specified with #:test-target, unless #:tests? #f is passed. If the #:parallel-tests? argument is true (the default), run make check -j.


Run make install with the flags listed in #:make-flags.


Patch shebangs on the installed executable files.


Strip debugging symbols from ELF files (unless #:strip-binaries? is false), copying them to the debug output when available (see Installing Debugging Files).

The build-side module (guix build gnu-build-system) defines %standard-phases as the default list of build phases. %standard-phases is a list of symbol/procedure pairs, where the procedure implements the actual phase.

The list of phases used for a particular package can be changed with the #:phases parameter. For instance, passing:

#:phases (modify-phases %standard-phases (delete 'configure))

means that all the phases described above will be used, except the configure phase.

In addition, this build system ensures that the “standard” environment for GNU packages is available. This includes tools such as GCC, libc, Coreutils, Bash, Make, Diffutils, grep, and sed (see the (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.

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.

Scheme Variable: ant-build-system

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

Scheme Variable: asdf-build-system/source
Scheme Variable: asdf-build-system/sbcl
Scheme Variable: asdf-build-system/ecl

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 itself as well as its run-time dependencies should begin their name with the lisp implementation, such as sbcl- for asdf-build-system/sbcl. Beginning the input name with this prefix will allow the build system to encode its location into the resulting library, so that the input can be found at run-time.

If dependencies are used only for tests, it is convenient to use a different prefix in order to avoid having a run-time dependency on such systems. For example,

(define-public sbcl-bordeaux-threads
    (native-inputs `(("tests:cl-fiveam" ,sbcl-fiveam)))

Additionally, the corresponding source package should be labeled using the same convention as python packages (see Python Modules), using the cl- prefix.

For binary packages, each system should be defined as a Guix package. If one package origin contains several systems, package variants can be created in order to build all the systems. Source packages, which use asdf-build-system/source, may contain several systems.

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-symlinks 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.

If the system is not defined within its own .asd file of the same name, then the #:asd-file parameter should be used to specify which file the system is defined in.

Scheme Variable: cargo-build-system

This variable is exported by (guix build-system cargo). It supports builds of packages using Cargo, the build tool of the Rust programming language.

In its configure phase, this build system replaces dependencies specified in the Carto.toml file with inputs to the Guix package. The install phase installs the binaries, and it also installs the source code and Cargo.toml file.

Scheme Variable: cmake-build-system

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.

Scheme Variable: glib-or-gtk-build-system

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:


The 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+.


The 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.

Scheme Variable: ocaml-build-system

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 file present at the top-level, it will run ocaml -configure, ocaml -build and ocaml -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/ or ocaml pkg/ 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.

Scheme Variable: python-build-system

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 build and then python install --prefix=/gnu/store/….

For packages that install stand-alone Python programs under bin/, it takes care of wrapping these programs so that their 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 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.

Scheme Variable: perl-build-system

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.

Scheme Variable: r-build-system

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.

Scheme Variable: ruby-build-system

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.

Scheme Variable: waf-build-system

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.

Scheme Variable: haskell-build-system

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.

Scheme Variable: dub-build-system

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.

Scheme Variable: emacs-build-system

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 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 dir file is deleted. Each package is installed in its own directory under share/emacs/site-lisp/guix.d.

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.

Scheme Variable: trivial-build-system

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



Please see the (guix build gnu-build-system) modules for more details about the build phases.

Next: , Previous: , Up: Programming Interface   [Contents][Index]