The high-level interface to package definitions is implemented in the
(guix packages) and
(guix build-system) modules. As an
example, the package definition, or recipe, for the GNU Hello
package looks like this:
(use-modules (guix packages) (guix download) (guix build-system gnu) (guix licenses)) (define hello (package (name "hello") (version "2.8") (source (origin (method url-fetch) (uri (string-append "mirror://gnu/hello/hello-" version ".tar.gz")) (sha256 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6")))) (build-system gnu-build-system) (inputs `(("gawk" ,gawk))) (synopsis "GNU Hello") (description "Yeah...") (home-page "http://www.gnu.org/software/hello/") (license gpl3+)))
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here. This expression binds variable hello
<package> object, which is essentially a record
(see Scheme records in GNU Guile Reference Manual).
This package object can be inspected using procedures found in the
(guix packages) module; for instance,
There are a few points worth noting in the above package definition:
sourcefield of the package is an
<origin>object. Here, the
(guix download)is used, meaning that the source is a file to be downloaded over FTP or HTTP.
mirror://gnu prefix instructs
url-fetch to use one of
the GNU mirrors defined in
sha256 field specifies the expected SHA256 hash of the file
being downloaded. It is mandatory, and allows Guix to check the
integrity of the file. The
(base32 …) form introduces the
base32 representation of the hash. You can obtain this information with
guix download (see Invoking guix download) and
hash (see Invoking guix hash).
When needed, the
origin form can also have a
listing patches to be applied, and a
snippet field giving a
Scheme expression to modify the source code.
build-systemfield is set to gnu-build-system. The gnu-build-system variable is defined in the
(guix build-system gnu)module, and is bound to a
Naturally, gnu-build-system represents the familiar GNU Build
System, and variants thereof (see configuration and
makefile conventions in GNU Coding Standards). In a
nutshell, packages using the GNU Build System may be configured, built,
and installed with the usual
./configure && make && make check &&
make install command sequence. This is what gnu-build-system
In addition, gnu-build-system ensures that the “standard” environment for GNU packages is available. This includes tools such as GCC, Coreutils, Bash, Make, Diffutils, and Patch.
inputsfield specifies inputs to the build process—i.e., build-time or run-time dependencies of the package. Here, we define an input called
"gawk"whose value is that of the gawk variable; gawk is itself bound to a
Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, gnu-build-system takes care of ensuring that they are present.
However, any other dependencies need to be specified in the
inputs field. Any dependency not specified here will simply be
unavailable to the build process, possibly leading to a build failure.
There are other fields that package definitions may provide. Of
particular interest is the
arguments field. When specified, it
must be bound to a list of additional arguments to be passed to the
build system. For instance, the above definition could be augmented
with the following field initializer:
(arguments `(#:tests? #f #:configure-flags '("--enable-silent-rules")))
These are keyword arguments (see keyword
arguments in Guile in GNU Guile Reference Manual). They are
passed to gnu-build-system, which interprets them as meaning “do
make check”, and “run configure with the
--enable-silent-rules flag”. The value of these keyword
parameters is actually evaluated in the build stratum—i.e., by a
Guile process launched by the daemon (see Derivations).
Once a package definition is in place4, the
package may actually be built using the
guix build command-line
tool (see Invoking guix build). Eventually, updating the package
definition to a new upstream version can be partly automated by the
guix refresh command (see Invoking guix refresh).
Behind the scenes, a derivation corresponding to the
object is first computed by the
That derivation is stored in a
.drv file under /nix/store.
The build actions it prescribes may then be realized by using the
build-derivations procedure (see The Store).
<derivation> object of package for system
package must be a valid
<package> object, and system
must be a string denoting the target system type—e.g.,
"x86_64-linux" for an x86_64 Linux-based GNU system. store
must be a connection to the daemon, which operates on the store
(see The Store).
Similarly, it is possible to compute a derivation that cross-builds a package for some other system:
<derivation> object of package cross-built from
system to target.
target must be a valid GNU triplet denoting the target hardware
and operating system, such as
(see GNU configuration triplets in GNU
Configure and Build System).
definitions like the one above may be automatically converted from the
Nixpkgs distribution using the
guix import command.