guix.texi

format supports it---currently @code{docker} and @code{squashfs} (Singularity)
support it.  @var{command} must be relative to the profile contained in the
pack.

The entry point specifies the command that tools like @code{docker run} or
@code{singularity run} automatically start by default.  For example, you can
do:

@example
guix pack -f docker --entry-point=bin/guile guile
@end example

The resulting pack can easily be loaded and @code{docker run} with no extra
arguments will spawn @code{bin/guile}:

@example
docker load -i pack.tar.gz
docker run @var{image-id}
@end example

@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.

This has the same purpose as the same-named option in @command{guix
build} (@pxref{Additional Build Options, @option{--expression} in
@command{guix build}}).

@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
code in @var{file}.  This option can be repeated several times, in which
case the manifests are concatenated.

This has a similar purpose as the same-named option in @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
same manifest files.  It allows you to define a collection of packages
once and use it both for creating profiles and for creating archives
for use on machines that do not have Guix installed.  Note that you can
specify @emph{either} a manifest file @emph{or} a list of packages,
but not both.

@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the system type of the build host.

@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
configuration triplets,, autoconf, Autoconf}).

@item --compression=@var{tool}
@itemx -C @var{tool}
Compress the resulting tarball using @var{tool}---one of @code{gzip},
@code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no
compression.

@item --symlink=@var{spec}
@itemx -S @var{spec}
Add the symlinks specified by @var{spec} to the pack.  This option can
appear several times.

@var{spec} has the form @code{@var{source}=@var{target}}, where
@var{source} is the symlink that will be created and @var{target} is the
symlink target.

For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
symlink pointing to the @file{bin} sub-directory of the profile.

@item --save-provenance
Save provenance information for the packages passed on the command line.
Provenance information includes the URL and commit of the channels in use
(@pxref{Channels}).

Provenance information is saved in the
@file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the
usual package metadata---the name and version of each package, their
propagated inputs, and so on.  It is useful information to the recipient of
the pack, who then knows how the pack was (supposedly) obtained.

This option is not enabled by default because, like timestamps, provenance
information contributes nothing to the build process.  In other words, there
is an infinity of channel URLs and commit IDs that can lead to the same pack.
Recording such ``silent'' metadata in the output thus potentially breaks the
source-to-binary bitwise reproducibility property.

@item --root=@var{file}
@itemx -r @var{file}
@cindex garbage collector root, for packs
Make @var{file} a symlink to the resulting pack, and register it as a garbage
collector root.

@item --localstatedir
@itemx --profile-name=@var{name}
Include the ``local state directory'', @file{/var/guix}, in the resulting
pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
profile---by default @var{name} is @code{guix-profile}, which corresponds to
@file{~root/.guix-profile}.

@file{/var/guix} contains the store database (@pxref{The Store}) as well
as garbage-collector roots (@pxref{Invoking guix gc}).  Providing it in
the pack means that the store is ``complete'' and manageable by Guix;
not providing it pack means that the store is ``dead'': items cannot be
added to it or removed from it after extraction of the pack.

One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).

@item --derivation
@itemx -d
Print the name of the derivation that builds the pack.

@item --bootstrap
Use the bootstrap binaries to build the pack.  This option is only
useful to Guix developers.
@end table

In addition, @command{guix pack} supports all the common build options
(@pxref{Common Build Options}) and all the package transformation
options (@pxref{Package Transformation Options}).


@node The GCC toolchain
@section The GCC toolchain

@cindex GCC
@cindex ld-wrapper
@cindex linker wrapper
@cindex toolchain, for C development
@cindex toolchain, for Fortran development

If you need a complete toolchain for compiling and linking C or C++
source code, use the @code{gcc-toolchain} package.  This package
provides a complete GCC toolchain for C/C++ development, including GCC
itself, the GNU C Library (headers and binaries, plus debugging symbols
in the @code{debug} output), Binutils, and a linker wrapper.

The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
invoke the actual linker with this new set of arguments.  You can instruct the
wrapper to refuse to link against libraries not in the store by setting the
@env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.

The package @code{gfortran-toolchain} provides a complete GCC toolchain
for Fortran development.  For other languages, please use
@samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}).


@node Invoking guix git authenticate
@section Invoking @command{guix git authenticate}

The @command{guix git authenticate} command authenticates a Git checkout
following the same rule as for channels (@pxref{channel-authentication,
channel authentication}).  That is, starting from a given commit, it
ensures that all subsequent commits are signed by an OpenPGP key whose
fingerprint appears in the @file{.guix-authorizations} file of its
parent commit(s).

You will find this command useful if you maintain a channel.  But in
fact, this authentication mechanism is useful in a broader context, so
you might want to use it for Git repositories that have nothing to do
with Guix.

The general syntax is:

@example
guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
@end example

By default, this command authenticates the Git checkout in the current
directory; it outputs nothing and exits with exit code zero on success
and non-zero on failure.  @var{commit} above denotes the first commit
where authentication takes place, and @var{signer} is the OpenPGP
fingerprint of public key used to sign @var{commit}.  Together, they
form a ``channel introduction'' (@pxref{channel-authentication, channel
introduction}).  The options below allow you to fine-tune the process.

@table @code
@item --repository=@var{directory}
@itemx -r @var{directory}
Open the Git repository in @var{directory} instead of the current
directory.

@item --keyring=@var{reference}
@itemx -k @var{reference}
Load OpenPGP keyring from @var{reference}, the reference of a branch
such as @code{origin/keyring} or @code{my-keyring}.  The branch must
contain OpenPGP public keys in @file{.key} files, either in binary form
or ``ASCII-armored''.  By default the keyring is loaded from the branch
named @code{keyring}.

@item --stats
Display commit signing statistics upon completion.

@item --cache-key=@var{key}
Previously-authenticated commits are cached in a file under
@file{~/.cache/guix/authentication}.  This option forces the cache to be
stored in file @var{key} in that directory.

@item --historical-authorizations=@var{file}
By default, any commit whose parent commit(s) lack the
@file{.guix-authorizations} file is considered inauthentic.  In
contrast, this option considers the authorizations in @var{file} for any
commit that lacks @file{.guix-authorizations}.  The format of @var{file}
is the same as that of @file{.guix-authorizations}
(@pxref{channel-authorizations, @file{.guix-authorizations} format}).
@end table


@c *********************************************************************
@node Programming Interface
@chapter Programming Interface

GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages.  The first interface allows users to
write high-level package definitions.  These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies.  These definitions can then be
turned into concrete build actions.

Build actions are performed by the Guix daemon, on behalf of users.  In a
standard setup, the daemon has write access to the store---the
@file{/gnu/store} directory---whereas users do not.  The recommended
setup also has the daemon perform builds in chroots, under specific
build users, to minimize interference with the rest of the system.

@cindex derivation
Lower-level APIs are available to interact with the daemon and the
store.  To instruct the daemon to perform a build action, users actually
provide it with a @dfn{derivation}.  A derivation is a low-level
representation of the build actions to be taken, and the environment in
which they should occur---derivations are to package definitions what
assembly is to C programs.  The term ``derivation'' comes from the fact
that build results @emph{derive} from them.

This chapter describes all these APIs in turn, starting from high-level
package definitions.

@menu
* Package Modules::             Packages from the programmer's viewpoint.
* Defining Packages::           Defining new packages.
* Defining Package Variants::   Customizing packages.
* Build Systems::               Specifying how packages are built.
* Build Phases::                Phases of the build process of a package.
* Build Utilities::             Helpers for your package definitions and more.
* The Store::                   Manipulating the package store.
* Derivations::                 Low-level interface to package derivations.
* The Store Monad::             Purely functional interface to the store.
* G-Expressions::               Manipulating build expressions.
* Invoking guix repl::          Programming Guix in Guile
@end menu

@node Package Modules
@section Package Modules

From a programming viewpoint, the package definitions of the
GNU distribution are provided by Guile modules in the @code{(gnu packages
@dots{})} name space@footnote{Note that packages under the @code{(gnu
packages @dots{})} module name space are not necessarily ``GNU
packages''.  This module naming scheme follows the usual Guile module
naming convention: @code{gnu} means that these modules are distributed
as part of the GNU system, and @code{packages} identifies modules that
define packages.}  (@pxref{Modules, Guile modules,, guile, GNU Guile
Reference Manual}).  For instance, the @code{(gnu packages emacs)}
module exports a variable named @code{emacs}, which is bound to a
@code{<package>} object (@pxref{Defining Packages}).

The @code{(gnu packages @dots{})} module name space is
automatically scanned for packages by the command-line tools.  For
instance, when running @code{guix install emacs}, all the @code{(gnu
packages @dots{})} modules are scanned until one that exports a package
object whose name is @code{emacs} is found.  This package search
facility is implemented in the @code{(gnu packages)} module.

@cindex customization, of packages
@cindex package module search path
Users can store package definitions in modules with different
names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
name and module name must match.  For instance, the @code{(my-packages
emacs)} module must be stored in a @file{my-packages/emacs.scm} file
relative to the load path specified with @option{--load-path} or
@env{GUIX_PACKAGE_PATH}.  @xref{Modules and the File System,,,
guile, GNU Guile Reference Manual}, for details.}.  There are two ways to make
these package definitions visible to the user interfaces:

@enumerate
@item
By adding the directory containing your package modules to the search path
with the @code{-L} flag of @command{guix package} and other commands
(@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
environment variable described below.

@item
By defining a @dfn{channel} and configuring @command{guix pull} so that it
pulls from it.  A channel is essentially a Git repository containing package
modules.  @xref{Channels}, for more information on how to define and use
channels.
@end enumerate

@env{GUIX_PACKAGE_PATH} works similarly to other search path variables:

@defvr {Environment Variable} GUIX_PACKAGE_PATH
This is a colon-separated list of directories to search for additional
package modules.  Directories listed in this variable take precedence
over the own modules of the distribution.
@end defvr

The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
each package is built based solely on other packages in the
distribution.  The root of this dependency graph is a small set of
@dfn{bootstrap binaries}, provided by the @code{(gnu packages
bootstrap)} module.  For more information on bootstrapping,
@pxref{Bootstrapping}.

@node Defining Packages
@section Defining Packages

The high-level interface to package definitions is implemented in the
@code{(guix packages)} and @code{(guix build-system)} modules.  As an
example, the package definition, or @dfn{recipe}, for the GNU Hello
package looks like this:

@lisp
(define-module (gnu packages hello)
  #:use-module (guix packages)
  #:use-module (guix download)
  #:use-module (guix build-system gnu)
  #:use-module (guix licenses)
  #:use-module (gnu packages gawk))

(define-public hello
  (package
    (name "hello")
    (version "2.10")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
    (build-system gnu-build-system)
    (arguments '(#:configure-flags '("--enable-silent-rules")))
    (inputs `(("gawk" ,gawk)))
    (synopsis "Hello, GNU world: An example GNU package")
    (description "Guess what GNU Hello prints!")
    (home-page "https://www.gnu.org/software/hello/")
    (license gpl3+)))
@end lisp

@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here.  This expression binds the variable
@code{hello} to a @code{<package>} object, which is essentially a record
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
This package object can be inspected using procedures found in the
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.

With luck, you may be able to import part or all of the definition of
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).

In the example above, @code{hello} is defined in a module of its own,
@code{(gnu packages hello)}.  Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
the command-line tools (@pxref{Package Modules}).

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

@itemize
@item
The @code{source} field of the package is an @code{<origin>} object
(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.

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

The @code{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 @code{(base32 @dots{})} form introduces the
base32 representation of the hash.  You can obtain this information with
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).

@cindex patches
When needed, the @code{origin} form can also have a @code{patches} field
listing patches to be applied, and a @code{snippet} field giving a
Scheme expression to modify the source code.

@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
package (@pxref{Build Systems}).  Here, @code{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.

When you start packaging non-trivial software, you may need tools to
manipulate those build phases, manipulate files, and so on.  @xref{Build
Utilities}, for more on this.

@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}).  Here it is interpreted by
@code{gnu-build-system} as a request run @file{configure} with the
@option{--enable-silent-rules} flag.

@cindex quote
@cindex quoting
@findex '
@findex quote
What about these quote (@code{'}) characters?  They are Scheme syntax to
introduce a literal list; @code{'} is synonymous with @code{quote}.
@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
for details.  Here the value of the @code{arguments} field is a list of
arguments passed to the build system down the road, as with @code{apply}
(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
Manual}).

The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
@code{#:configure-flags} is a keyword used to pass a keyword argument
to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
Reference Manual}).

@item
The @code{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 @code{"gawk"} whose value is that of the @code{gawk}
variable; @code{gawk} is itself bound to a @code{<package>} object.

@cindex backquote (quasiquote)
@findex `
@findex quasiquote
@cindex comma (unquote)
@findex ,
@findex unquote
@findex ,@@
@findex unquote-splicing
Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
us to introduce a literal list in the @code{inputs} field, while
@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
Reference Manual}).

Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here.  Instead, @code{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).

However, any other dependencies need to be specified in the
@code{inputs} field.  Any dependency not specified here will simply be
unavailable to the build process, possibly leading to a build failure.
@end itemize

@xref{package Reference}, for a full description of possible fields.

Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}), troubleshooting any build failures
you encounter (@pxref{Debugging Build Failures}).  You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
@vindex GUIX_PACKAGE_PATH
Lastly, @pxref{Channels}, for information
on how to extend the distribution by adding your own package definitions
in a ``channel''.

Finally, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).

Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
That derivation is stored in a @file{.drv} file under @file{/gnu/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).

@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).

@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system.  @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
@end deffn

@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:

@deffn {Scheme Procedure} package-cross-derivation @var{store} @
            @var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.

@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"aarch64-linux-gnu"}
(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
@end deffn

Once you have package definitions, you can easily define @emph{variants}
of those packages.  @xref{Defining Package Variants}, for more on that.

@menu
* package Reference::           The package data type.
* origin Reference::            The origin data type.
@end menu


@node package Reference
@subsection @code{package} Reference

This section summarizes all the options available in @code{package}
declarations (@pxref{Defining Packages}).

@deftp {Data Type} package
This is the data type representing a package recipe.

@table @asis
@item @code{name}
The name of the package, as a string.

@item @code{version}
The version of the package, as a string.

@item @code{source}
An object telling how the source code for the package should be
acquired.  Most of the time, this is an @code{origin} object, which
denotes a file fetched from the Internet (@pxref{origin Reference}).  It
can also be any other ``file-like'' object such as a @code{local-file},
which denotes a file from the local file system (@pxref{G-Expressions,
@code{local-file}}).

@item @code{build-system}
The build system that should be used to build the package (@pxref{Build
Systems}).

@item @code{arguments} (default: @code{'()})
The arguments that should be passed to the build system.  This is a
list, typically containing sequential keyword-value pairs.

@item @code{inputs} (default: @code{'()})
@itemx @code{native-inputs} (default: @code{'()})
@itemx @code{propagated-inputs} (default: @code{'()})
@cindex inputs, of packages
These fields list dependencies of the package.  Each one is 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 @code{"out"} (@pxref{Packages with Multiple Outputs}, for
more on package outputs).  For example, the list below specifies three
inputs:

@lisp
`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
@end lisp

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

@code{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.  @command{guix lint} can report likely mistakes in
this area (@pxref{Invoking guix lint}).

@anchor{package-propagated-inputs}
Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
specified packages will be automatically installed to profiles
(@pxref{Features, the role of profiles in Guix}) alongside the package
they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
package}}, for information on how @command{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 @i{via} its @code{Requires} field.

Another example where @code{propagated-inputs} is useful is for languages
that lack a facility to record the run-time search path akin to the
@code{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 @code{propagated-inputs} rather than @code{inputs}.

@item @code{outputs} (default: @code{'("out")})
The list of output names of the package.  @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.

@item @code{native-search-paths} (default: @code{'()})
@itemx @code{search-paths} (default: @code{'()})
A list of @code{search-path-specification} objects describing
search-path environment variables honored by the package.

@item @code{replacement} (default: @code{#f})
This must be either @code{#f} or a package object that will be used as a
@dfn{replacement} for this package.  @xref{Security Updates, grafts},
for details.

@item @code{synopsis}
A one-line description of the package.

@item @code{description}
A more elaborate description of the package.

@item @code{license}
@cindex license, of packages
The license of the package; a value from @code{(guix licenses)},
or a list of such values.

@item @code{home-page}
The URL to the home-page of the package, as a string.

@item @code{supported-systems} (default: @code{%supported-systems})
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.

@item @code{location} (default: source location of the @code{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.
@end table
@end deftp

@deffn {Scheme Syntax} this-package
When used in the @emph{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:

@lisp
(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)
                     `(("self" ,this-package))
                     '())))
@end lisp

It is an error to refer to @code{this-package} outside a package definition.
@end deffn

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.

@cindex tool chain, choosing a package's tool chain
@deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
Return a variant of @var{package} that uses @var{toolchain} instead of
the default GNU C/C++ toolchain.  @var{toolchain} must be a list of
inputs (label/package tuples) providing equivalent functionality, such
as the @code{gcc-toolchain} package.

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

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

The build tool chain is part of the @dfn{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 @var{package} so that it
pulls in @var{toolchain} instead of the defaults.  @ref{Build Systems},
for more on build systems.
@end deffn

@node origin Reference
@subsection @code{origin} Reference

This section documents @dfn{origins}.  An @code{origin} declaration
specifies data that must be ``produced''---downloaded, usually---and
whose content hash is known in advance.  Origins are primarily used to
represent the source code of packages (@pxref{Defining Packages}).  For
that reason, the @code{origin} form allows you to declare patches to
apply to the original source code as well as code snippets to modify it.

@deftp {Data Type} origin
This is the data type representing a source code origin.

@table @asis
@item @code{uri}
An object containing the URI of the source.  The object type depends on
the @code{method} (see below).  For example, when using the
@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
values are: a URL represented as a string, or a list thereof.

@cindex fixed-output derivations, for download
@item @code{method}
A monadic procedure that handles the given URI.  The procedure must
accept at least three arguments: the value of the @code{uri} field and
the hash algorithm and hash value specified by the @code{hash} field.
It must return a store item or a derivation in the store monad
(@pxref{The Store Monad}); most methods return a fixed-output derivation
(@pxref{Derivations}).

Commonly used methods include @code{url-fetch}, which fetches data from
a URL, and @code{git-fetch}, which fetches data from a Git repository
(see below).

@item @code{sha256}
A bytevector containing the SHA-256 hash of the source.  This is
equivalent to providing a @code{content-hash} SHA256 object in the
@code{hash} field described below.

@item @code{hash}
The @code{content-hash} object of the source---see below for how to use
@code{content-hash}.

You can obtain this information using @code{guix download}
(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
guix hash}).

@item @code{file-name} (default: @code{#f})
The file name under which the source code should be saved.  When this is
@code{#f}, a sensible default value will be used in most cases.  In case
the source is fetched from a URL, the file name from the URL will be
used.  For version control checkouts, it is recommended to provide the
file name explicitly because the default is not very descriptive.

@item @code{patches} (default: @code{'()})
A list of file names, origins, or file-like objects (@pxref{G-Expressions,
file-like objects}) pointing to patches to be applied to the source.

This list of patches must be unconditional.  In particular, it cannot
depend on the value of @code{%current-system} or
@code{%current-target-system}.

@item @code{snippet} (default: @code{#f})
A G-expression (@pxref{G-Expressions}) or S-expression that will be run
in the source directory.  This is a convenient way to modify the source,
sometimes more convenient than a patch.

@item @code{patch-flags} (default: @code{'("-p1")})
A list of command-line flags that should be passed to the @code{patch}
command.

@item @code{patch-inputs} (default: @code{#f})
Input packages or derivations to the patching process.  When this is
@code{#f}, the usual set of inputs necessary for patching are provided,
such as GNU@tie{}Patch.

@item @code{modules} (default: @code{'()})
A list of Guile modules that should be loaded during the patching
process and while running the code in the @code{snippet} field.

@item @code{patch-guile} (default: @code{#f})
The Guile package that should be used in the patching process.  When
this is @code{#f}, a sensible default is used.
@end table
@end deftp

@deftp {Data Type} content-hash @var{value} [@var{algorithm}]
Construct a content hash object for the given @var{algorithm}, and with
@var{value} as its hash value.  When @var{algorithm} is omitted, assume
it is @code{sha256}.

@var{value} can be a literal string, in which case it is base32-decoded,
or it can be a bytevector.

The following forms are all equivalent:

@lisp
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
              sha256)
(content-hash (base32
               "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
              sha256)
@end lisp

Technically, @code{content-hash} is currently implemented as a macro.
It performs sanity checks at macro-expansion time, when possible, such
as ensuring that @var{value} has the right size for @var{algorithm}.
@end deftp

As we have seen above, how exactly the data an origin refers to is
retrieved is determined by its @code{method} field.  The @code{(guix
download)} module provides the most common method, @code{url-fetch},
described below.

@deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
           [name] [#:executable? #f]
Return a fixed-output derivation that fetches data from @var{url} (a
string, or a list of strings denoting alternate URLs), which is expected
to have hash @var{hash} of type @var{hash-algo} (a symbol).  By default,
the file name is the base name of URL; optionally, @var{name} can
specify a different file name.  When @var{executable?} is true, make the
downloaded file executable.

When one of the URL starts with @code{mirror://}, then its host part is
interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.

Alternatively, when URL starts with @code{file://}, return the
corresponding file name in the store.
@end deffn

Likewise, the @code{(guix git-download)} module defines the
@code{git-fetch} origin method, which fetches data from a Git version
control repository, and the @code{git-reference} data type to describe
the repository and revision to fetch.

@deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
Return a fixed-output derivation that fetches @var{ref}, a
@code{<git-reference>} object.  The output is expected to have recursive
hash @var{hash} of type @var{hash-algo} (a symbol).  Use @var{name} as
the file name, or a generic name if @code{#f}.
@end deffn

@deftp {Data Type} git-reference
This data type represents a Git reference for @code{git-fetch} to
retrieve.

@table @asis
@item @code{url}
The URL of the Git repository to clone.

@item @code{commit}
This string denotes either the commit to fetch (a hexadecimal string,
either the full SHA1 commit or a ``short'' commit string; the latter is
not recommended) or the tag to fetch.

@item @code{recursive?} (default: @code{#f})
This Boolean indicates whether to recursively fetch Git sub-modules.
@end table

The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
repository:

@lisp
(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "v2.10"))
@end lisp

This is equivalent to the reference below, which explicitly names the
commit:

@lisp
(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
@end lisp
@end deftp

For Mercurial repositories, the module @code{(guix hg-download)} defines
the @code{hg-fetch} origin method and @code{hg-reference} data type for
support of the Mercurial version control system.

@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
           [name]
Return a fixed-output derivation that fetches @var{ref}, a
@code{<hg-reference>} object.  The output is expected to have recursive
hash @var{hash} of type @var{hash-algo} (a symbol).  Use @var{name} as
the file name, or a generic name if @code{#false}.
@end deffn

@node Defining Package Variants
@section Defining Package Variants

@cindex customizing packages
@cindex variants, of packages
One of the nice things with Guix is that, given a package definition,
you can easily @emph{derive} variants of that package---for a different
upstream version, with different dependencies, different compilation
options, and so on.  Some of these custom packages can be defined
straight from the command line (@pxref{Package Transformation Options}).
This section describes how to define package variants in code.  This can
be useful in ``manifests'' (@pxref{profile-manifest,
@option{--manifest}}) and in your own package collection
(@pxref{Creating a Channel}), among others!

@cindex inherit, for package definitions
As discussed earlier, packages are first-class objects in the Scheme
language.  The @code{(guix packages)} module provides the @code{package}
construct to define new package objects (@pxref{package Reference}).
The easiest way to define a package variant is using the @code{inherit}
keyword together with @code{package}.  This allows you to inherit from a
package definition while overriding the fields you want.

For example, given the @code{hello} variable, which contains a
definition for the current version of GNU@tie{}Hello, here's how you
would define a variant for version 2.2 (released in 2006, it's
vintage!):

@lisp
(use-modules (gnu packages base))    ;for 'hello'

(define hello-2.2
  (package
    (inherit hello)
    (version "2.2")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
@end lisp

The example above corresponds to what the @option{--with-source} package
transformation option does.  Essentially @code{hello-2.2} preserves all
the fields of @code{hello}, except @code{version} and @code{source},
which it overrides.  Note that the original @code{hello} variable is
still there, in the @code{(gnu packages base)} module, unchanged.  When
you define a custom package like this, you are really @emph{adding} a
new package definition; the original one remains available.

You can just as well define variants with a different set of
dependencies than the original package.  For example, the default
@code{gdb} package depends on @code{guile}, but since that is an
optional dependency, you can define a variant that removes that
dependency like so:

@lisp
(use-modules (gnu packages gdb)    ;for 'gdb'
             (srfi srfi-1))        ;for 'alist-delete'

(define gdb-sans-guile
  (package
    (inherit gdb)
    (inputs (alist-delete "guile"
                          (package-inputs gdb)))))
@end lisp

The @code{alist-delete} call above removes the tuple from the
@code{inputs} field that has @code{"guile"} as its first element
(@pxref{SRFI-1 Association Lists,,, guile, GNU Guile Reference
Manual}).

In some cases, you may find it useful to write functions
(``procedures'', in Scheme parlance) that return a package based on some
parameters.  For example, consider the @code{luasocket} library for the
Lua programming language.  We want to create @code{luasocket} packages
for major versions of Lua.  One way to do that is to define a procedure
that takes a Lua package and returns a @code{luasocket} package that
depends on it:

@lisp
(define (make-lua-socket name lua)
  ;; Return a luasocket package built with LUA.
  (package
    (name name)
    (version "3.0")
    ;; several fields omitted
    (inputs
     `(("lua" ,lua)))
    (synopsis "Socket library for Lua")))

(define-public lua5.1-socket
  (make-lua-socket "lua5.1-socket" lua-5.1))

(define-public lua5.2-socket
  (make-lua-socket "lua5.2-socket" lua-5.2))
@end lisp

Here we have defined packages @code{lua5.1-socket} and
@code{lua5.2-socket} by calling @code{make-lua-socket} with different
arguments.  @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
more info on procedures.  Having top-level public definitions for these
two packages means that they can be referred to from the command line
(@pxref{Package Modules}).

@cindex package transformations
These are pretty simple package variants.  As a convenience, the
@code{(guix transformations)} module provides a high-level interface
that directly maps to the more sophisticated package transformation
options (@pxref{Package Transformation Options}):

@deffn {Scheme Procedure} options->transformation @var{opts}
Return a procedure that, when passed an object to build (package,
derivation, etc.), applies the transformations specified by @var{opts} and returns