Next: , Up: Utilities   [Contents][Index]


5.1 Invoking guix build

The guix build command builds packages or derivations and their dependencies, and prints the resulting store paths. Note that it does not modify the user’s profile—this is the job of the guix package command (see Invoking guix package). Thus, it is mainly useful for distribution developers.

The general syntax is:

guix build options package-or-derivation

package-or-derivation may be either the name of a package found in the software distribution such as coreutils or coreutils-8.20, or a derivation such as /gnu/store/…-coreutils-8.19.drv. In the former case, a package with the corresponding name (and optionally version) is searched for among the GNU distribution modules (see Package Modules).

Alternatively, the --expression option may be used to specify a Scheme expression that evaluates to a package; this is useful when disambiguation among several same-named packages or package variants is needed.

The options may be zero or more of the following:

--expression=expr
-e expr

Build the package or derivation expr evaluates to.

For example, expr may be (@ (gnu packages guile) guile-1.8), which unambiguously designates this specific variant of version 1.8 of Guile.

Alternately, expr may refer to a zero-argument monadic procedure (see The Store Monad). The procedure must return a derivation as a monadic value, which is then passed through run-with-store.

--source
-S

Build the packages’ source derivations, rather than the packages themselves.

For instance, guix build -S gcc returns something like /gnu/store/…-gcc-4.7.2.tar.bz2, which is GCC’s source tarball.

The returned source tarball is the result of applying any patches and code snippets specified in the package’s origin (see Defining Packages).

--system=system
-s system

Attempt to build for system—e.g., i686-linux—instead of the host’s system type.

An example use of this is on Linux-based systems, which can emulate different personalities. For instance, passing --system=i686-linux on an x86_64-linux system allows users to build packages in a complete 32-bit environment.

--target=triplet

Cross-build for triplet, which must be a valid GNU triplet, such as "mips64el-linux-gnu" (see GNU configuration triplets in GNU Configure and Build System).

--with-source=source

Use source as the source of the corresponding package. source must be a file name or a URL, as for guix download (see Invoking guix download).

The “corresponding package” is taken to be one specified on the command line whose name matches the base of source—e.g., if source is /src/guile-2.0.10.tar.gz, the corresponding package is guile. Likewise, the version string is inferred from source; in the previous example, it’s 2.0.10.

This option allows users to try out versions of packages other than the one provided by the distribution. The example below downloads ed-1.7.tar.gz from a GNU mirror and uses that as the source for the ed package:

guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz

As a developer, --with-source makes it easy to test release candidates:

guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
--derivations
-d

Return the derivation paths, not the output paths, of the given packages.

--root=file
-r file

Make file a symlink to the result, and register it as a garbage collector root.

--log-file

Return the build log file names for the given package-or-derivations, or raise an error if build logs are missing.

This works regardless of how packages or derivations are specified. For instance, the following invocations are equivalent:

guix build --log-file `guix build -d guile`
guix build --log-file `guix build guile`
guix build --log-file guile
guix build --log-file -e '(@ (gnu packages guile) guile-2.0)'

In addition, a number of options that control the build process are common to guix build and other commands that can spawn builds, such as guix package or guix archive. These are the following:

--keep-failed
-K

Keep the build tree of failed builds. Thus, if a build fail, its build tree is kept under /tmp, in a directory whose name is shown at the end of the build log. This is useful when debugging build issues.

--dry-run
-n

Do not build the derivations.

--fallback

When substituting a pre-built binary fails, fall back to building packages locally.

--no-substitutes

Do not use substitutes for build products. That is, always build things locally instead of allowing downloads of pre-built binaries (see Substitutes).

--no-build-hook

Do not attempt to offload builds via the daemon’s “build hook” (see Daemon Offload Setup). That is, always build things locally instead of offloading builds to remote machines.

--max-silent-time=seconds

When the build or substitution process remains silent for more than seconds, terminate it and report a build failure.

--timeout=seconds

Likewise, when the build or substitution process lasts for more than seconds, terminate it and report a build failure.

By default there is no timeout. This behavior can be restored with --timeout=0.

--verbosity=level

Use the given verbosity level. level must be an integer between 0 and 5; higher means more verbose output. Setting a level of 4 or more may be helpful when debugging setup issues with the build daemon.

--cores=n
-c n

Allow the use of up to n CPU cores for the build. The special value 0 means to use as many CPU cores as available.

Behind the scenes, guix build is essentially an interface to the package-derivation procedure of the (guix packages) module, and to the build-derivations procedure of the (guix store) module.


Next: , Up: Utilities   [Contents][Index]