4.1 Defining Packages

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 to a <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, (package-name hello) returns—surprise!—"hello".

There are a few points worth noting in the above package definition:

• The source field of the package is an <origin> object. Here, the url-fetch method from (guix download) is used, meaning that the source is a file to be downloaded over FTP or HTTP.

  The mirror://gnu prefix instructs url-fetch to use one of the GNU mirrors defined in (guix download).

  The 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 guix hash (see Invoking guix hash).

• The build-system field 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 <build-system> object.

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

  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.

• The inputs field 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 <package> object.

  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 not run 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 place², 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 <package> object is first computed by the package-derivation procedure. 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).

Scheme Procedure: package-derivation store package [system]

Return the derivation path and corresponding <derivation> object of package for system (see Derivations).

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