8.2.1 package Reference

This section summarizes all the options available in package declarations (see Defining Packages).

Data Type: package

This is the data type representing a package recipe.

name

The name of the package, as a string.

version

The version of the package, as a string. See Version Numbers, for guidelines.

source

An object telling how the source code for the package should be acquired. Most of the time, this is an origin object, which denotes a file fetched from the Internet (see origin Reference). It can also be any other “file-like” object such as a local-file, which denotes a file from the local file system (see local-file).

build-system

The build system that should be used to build the package (see Build Systems).

arguments (default: '())

The arguments that should be passed to the build system. This is a list, typically containing sequential keyword-value pairs.

inputs (default: '())

native-inputs (default: '())

propagated-inputs (default: '())

These fields list dependencies of the package. Each element of these lists is either a package, origin, or other “file-like object” (see G-Expressions); to specify the output of that file-like object that should be used, pass a two-element list where the second element is the output (see Packages with Multiple Outputs, for more on package outputs). For example, the list below specifies three inputs:

(list libffi libunistring
      `(,glib "bin"))      ;the "bin" output of GLib

In the example above, the "out" output of libffi and libunistring is used.

Compatibility Note: Until version 1.3.0, input lists were a list of tuples, where each tuple has a label for the input (a string) as its first element, a package, origin, or derivation as its second element, and optionally the name of the output thereof that should be used, which defaults to "out". For example, the list below is equivalent to the one above, but using the old input style:

;; Old input style (deprecated).
`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;the "bin" output of GLib

This style is now deprecated; it is still supported but support will be removed in a future version. It should not be used for new package definitions. See Invoking guix style, on how to migrate to the new style.

The distinction between native-inputs and inputs is necessary when considering cross-compilation. When cross-compiling, dependencies listed in inputs are built for the target architecture; conversely, dependencies listed in native-inputs are built for the architecture of the build machine.

native-inputs is typically used to list tools needed at build time, but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or Bison. guix lint can report likely mistakes in this area (see Invoking guix lint).

Lastly, propagated-inputs is similar to inputs, but the specified packages will be automatically installed to profiles (see the role of profiles in Guix) alongside the package they belong to (see guix package, for information on how guix package deals with propagated inputs).

For example this is necessary when packaging a C/C++ library that needs headers of another library to compile, or when a pkg-config file refers to another one via its Requires field.

Another example where propagated-inputs is useful is for languages that lack a facility to record the run-time search path akin to the RUNPATH of ELF files; this includes Guile, Python, Perl, and more. When packaging libraries written in those languages, ensure they can find library code they depend on at run time by listing run-time dependencies in propagated-inputs rather than inputs.

outputs (default: '("out"))

The list of output names of the package. See Packages with Multiple Outputs, for typical uses of additional outputs.

native-search-paths (default: '())

search-paths (default: '())

A list of search-path-specification objects describing search-path environment variables honored by the package. See Search Paths, for more on search path specifications.

As for inputs, the distinction between native-search-paths and search-paths only matters when cross-compiling. In a cross-compilation context, native-search-paths applies exclusively to native inputs whereas search-paths applies only to host inputs.

Packages such as cross-compilers care about target inputs—for instance, our (modified) GCC cross-compiler has CROSS_C_INCLUDE_PATH in search-paths, which allows it to pick .h files for the target system and not those of native inputs. For the majority of packages though, only native-search-paths makes sense.

replacement (default: #f)

This must be either #f or a package object that will be used as a replacement for this package. See grafts, for details.

synopsis

A one-line description of the package.

description

A more elaborate description of the package.

license

The license of the package; a value from (guix licenses), or a list of such values.

home-page

The URL to the home-page of the package, as a string.

supported-systems (default: %supported-systems)

The list of systems supported by the package, as strings of the form architecture-kernel, for example "x86_64-linux".

location (default: source location of the package form)

The source location of the package. It is useful to override this when inheriting from another package, in which case this field is not automatically corrected.

Scheme Syntax: this-package

When used in the lexical scope of a package field definition, this identifier resolves to the package being defined.

The example below shows how to add a package as a native input of itself when cross-compiling:

(package
  (name "guile")
  ;; ...

  ;; When cross-compiled, Guile, for example, depends on
  ;; a native version of itself.  Add it here.
  (native-inputs (if (%current-target-system)
                     (list this-package)
                     '())))

It is an error to refer to this-package outside a package definition.

The following helper procedures are provided to help deal with package inputs.

Scheme Procedure: lookup-package-input package name

Scheme Procedure: lookup-package-native-input package name

Scheme Procedure: lookup-package-propagated-input package name

Scheme Procedure: lookup-package-direct-input package name

Look up name among package’s inputs (or native, propagated, or direct inputs). Return it if found, #f otherwise.

name is the name of a package depended on. Here’s how you might use it:

(use-modules (guix packages) (gnu packages base))

(lookup-package-direct-input coreutils "gmp")
⇒ #<package gmp@6.2.1 …>

In this example we obtain the gmp package that is among the direct inputs of coreutils.

Sometimes you will want to obtain the list of inputs needed to develop a package—all the inputs that are visible when the package is compiled. This is what the package-development-inputs procedure returns.

Scheme Procedure: package-development-inputs package [system] [#:target #f]

Return the list of inputs required by package for development purposes on system. When target is true, return the inputs needed to cross-compile package from system to triplet, where triplet is a triplet such as "aarch64-linux-gnu".

Note that the result includes both explicit inputs and implicit inputs—inputs automatically added by the build system (see Build Systems). Let us take the hello package to illustrate that:

(use-modules (gnu packages base) (guix packages))

hello
⇒ #<package hello@2.10 gnu/packages/base.scm:79 7f585d4f6790>

(package-direct-inputs hello)
⇒ ()

(package-development-inputs hello)
⇒ (("source" …) ("tar" #<package tar@1.32 …>) …)

In this example, package-direct-inputs returns the empty list, because hello has zero explicit dependencies. Conversely, package-development-inputs includes inputs implicitly added by gnu-build-system that are required to build hello: tar, gzip, GCC, libc, Bash, and more. To visualize it, guix graph hello would show you explicit inputs, whereas guix graph -t bag hello would include implicit inputs (see Invoking guix graph).

Because packages are regular Scheme objects that capture a complete dependency graph and associated build procedures, it is often useful to write procedures that take a package and return a modified version thereof according to some parameters. Below are a few examples.

Scheme Procedure: package-with-c-toolchain package toolchain

Return a variant of package that uses toolchain instead of the default GNU C/C++ toolchain. toolchain must be a list of inputs (label/package tuples) providing equivalent functionality, such as the gcc-toolchain package.

The example below returns a variant of the hello package built with GCC 10.x and the rest of the GNU tool chain (Binutils and the GNU C Library) instead of the default tool chain:

(let ((toolchain (specification->package "gcc-toolchain@10")))
  (package-with-c-toolchain hello `(("toolchain" ,toolchain))))

The build tool chain is part of the implicit inputs of packages—it’s usually not listed as part of the various “inputs” fields and is instead pulled in by the build system. Consequently, this procedure works by changing the build system of package so that it pulls in toolchain instead of the defaults. Build Systems, for more on build systems.