guix.texi

Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  my-personal-packages dd3df5e
    repository URL: https://example.org/personal-packages.git
    branch: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
  11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example

@noindent
The output of @command{guix pull} above shows that Generation@tie{}19 includes
both Guix and packages from the @code{my-personal-packages} channel.  Among
the new and upgraded packages that are listed, some like @code{my-gimp} and
@code{my-emacs-with-cool-features} might come from
@code{my-personal-packages}, while others come from the Guix default channel.

@subsection Replicating Guix

@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
The @command{guix pull --list-generations} output above shows precisely which
commits were used to build this instance of Guix.  We can thus replicate it,
say, on another machine, by providing a channel specification in
@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:

@lisp
;; Deploy specific commits of my channels of interest.
(list (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
      (channel
       (name 'my-personal-packages)
       (url "https://example.org/personal-packages.git")
       (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp

The @command{guix describe --format=channels} command can even generate this
list of channels directly (@pxref{Invoking guix describe}).

At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}.  The output of @command{guix build gimp} on
one machine will be exactly the same, bit for bit, as the output of the same
command on the other machine.  It also means both machines have access to all
the source code of Guix and, transitively, to all the source code of every
package it defines.

This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
will---some sort of ``meta reproducibility'' capabilities, if you will.

@node Invoking guix describe
@section Invoking @command{guix describe}

@cindex reproducibility
@cindex replicating Guix
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?''  This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
machine or user account, if you want to report a bug or to determine what
change in the channels you are using caused it, or if you want to record your
system state for reproducibility purposes.  The @command{guix describe}
command answers these questions.

When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
displays the channel(s) that it was built from, including their repository URL
and commit IDs (@pxref{Channels}):

@example
$ guix describe
Generation 10	Sep 03 2018 17:32:44	(current)
  guix e0fa68c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
@end example

If you're familiar with the Git version control system, this is similar in
spirit to @command{git describe}; the output is also similar to that of
@command{guix pull --list-generations}, but limited to the current generation
(@pxref{Invoking guix pull, the @option{--list-generations} option}).  Because
the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
information is all it takes to describe the revision of Guix you're using, and
also to replicate it.

To make it easier to replicate Guix, @command{guix describe} can also be asked
to return a list of channels instead of the human-readable description above:

@example
$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")))
@end example

@noindent
You can save this to a file and feed it to @command{guix pull -C} on some
other machine or at a later point in time, which will instantiate @emph{this
exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
From there on, since you're able to deploy the same revision of Guix, you can
just as well @emph{replicate a complete software environment}.  We humbly
think that this is @emph{awesome}, and we hope you'll like it too!

The details of the options supported by @command{guix describe} are as
follows:

@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce output in the specified @var{format}, one of:

@table @code
@item human
produce human-readable output;
@item channels
produce a list of channel specifications that can be passed to @command{guix
pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
guix pull}).
@end table
@end table

@node Invoking guix pack
@section Invoking @command{guix pack}

Occasionally you want to pass software to people who are not (yet!)
lucky enough to be using Guix.  You'd tell them to run @command{guix
package -i @var{something}}, but that's not possible in this case.  This
is where @command{guix pack} comes in.

@quotation Note
If you are looking for ways to exchange binaries among machines that
already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
publish}, and @ref{Invoking guix archive}.
@end quotation

@cindex pack
@cindex bundle
@cindex application bundle
@cindex software bundle
The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
@dfn{software bundle}: it creates a tarball or some other archive
containing the binaries of the software you're interested in, and all
its dependencies.  The resulting archive can be used on any machine that
does not have Guix, and people can run the exact same binaries as those
you have with Guix.  The pack itself is created in a bit-reproducible
fashion, so anyone can verify that it really contains the build results
that you pretend to be shipping.

For example, to create a bundle containing Guile, Emacs, Geiser, and all
their dependencies, you can run:

@example
$ guix pack guile emacs geiser
@dots{}
/gnu/store/@dots{}-pack.tar.gz
@end example

The result here is a tarball containing a @file{/gnu/store} directory
with all the relevant packages.  The resulting tarball contains a
@dfn{profile} with the three packages of interest; the profile is the
same as would be created by @command{guix package -i}.  It is this
mechanism that is used to create Guix's own standalone binary tarball
(@pxref{Binary Installation}).

Users of this pack would have to run
@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
find inconvenient.  To work around it, you can create, say, a
@file{/opt/gnu/bin} symlink to the profile:

@example
guix pack -S /opt/gnu/bin=bin guile emacs geiser
@end example

@noindent
That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.

@cindex relocatable binaries, with @command{guix pack}
What if the recipient of your pack does not have root privileges on
their machine, and thus cannot unpack it in the root file system?  In
that case, you will want to use the @code{--relocatable} option (see
below).  This option produces @dfn{relocatable binaries}, meaning they
they can be placed anywhere in the file system hierarchy: in the example
above, users can unpack your tarball in their home directory and
directly run @file{./opt/gnu/bin/guile}.

@cindex Docker, build an image with guix pack
Alternatively, you can produce a pack in the Docker image format using
the following command:

@example
guix pack -f docker guile emacs geiser
@end example

@noindent
The result is a tarball that can be passed to the @command{docker load}
command.  See the
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.

@cindex Singularity, build an image with guix pack
@cindex SquashFS, build an image with guix pack
Yet another option is to produce a SquashFS image with the following
command:

@example
guix pack -f squashfs guile emacs geiser
@end example

@noindent
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
@uref{http://singularity.lbl.gov, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.

Several command-line options allow you to customize your pack:

@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce a pack in the given @var{format}.

The available formats are:

@table @code
@item tarball
This is the default format.  It produces a tarball containing all the
specified binaries and symlinks.

@item docker
This produces a tarball that follows the
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
Docker Image Specification}.

@item squashfs
This produces a SquashFS image containing all the specified binaries and
symlinks, as well as empty mount points for virtual file systems like
procfs.
@end table

@item --relocatable
@itemx -R
Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
anywhere in the file system hierarchy and run from there.  For example,
if you create a pack containing Bash with:

@example
guix pack -R -S /mybin=bin bash
@end example

@noindent
... you can copy that pack to a machine that lacks Guix, and from your
home directory as a normal user, run:

@example
tar xf pack.tar.gz
./mybin/sh
@end example

@noindent
In that shell, if you type @code{ls /gnu/store}, you'll notice that
@file{/gnu/store} shows up and contains all the dependencies of
@code{bash}, even though the machine actually lacks @file{/gnu/store}
altogether!  That is probably the simplest way to deploy Guix-built
software on a non-Guix machine.

There's a gotcha though: this technique relies on the @dfn{user
namespace} feature of the kernel Linux, which allows unprivileged users
to mount or change root.  Old versions of Linux did not support it, and
some GNU/Linux distributions turn it off; on these systems, programs
from the pack @emph{will fail to run}, unless they are unpacked in the
root file system.

@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, @code{--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 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{"mips64el-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{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 --localstatedir
Include the ``local state directory'', @file{/var/guix}, in the
resulting pack.

@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 --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 Invoking guix archive
@section Invoking @command{guix archive}

@cindex @command{guix archive}
@cindex archive
The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.

@quotation Note
If you're looking for a way to produce archives in a format suitable for
tools other than Guix, @pxref{Invoking guix pack}.
@end quotation

@cindex exporting store items
To export store files as an archive to standard output, run:

@example
guix archive --export @var{options} @var{specifications}...
@end example

@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}).  For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:

@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example

If the specified packages are not built yet, @command{guix archive}
automatically builds them.  The build process may be controlled with the
common build options (@pxref{Common Build Options}).

To transfer the @code{emacs} package to a machine connected over SSH,
one would run:

@example
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example

@noindent
Similarly, a complete user profile may be transferred from one machine
to another like this:

@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh the-machine guix-archive --import
@end example

@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the store on the
target machine.  The @code{--missing} option can help figure out which
items are missing from the target store.  The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).

@cindex nar, archive format
@cindex normalized archive (nar)
Archives are stored in the ``normalized archive'' or ``nar'' format, which is
comparable in spirit to `tar', but with differences
that make it more appropriate for our purposes.  First, rather than
recording all Unix metadata for each file, the nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed.  Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order.  This makes archive production fully
deterministic.

When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended.  When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.

The main options are:

@table @code
@item --export
Export the specified store files or packages (see below.)  Write the
resulting archive to the standard output.

Dependencies are @emph{not} included in the output, unless
@code{--recursive} is passed.

@item -r
@itemx --recursive
When combined with @code{--export}, this instructs @command{guix
archive} to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.

@item --import
Read an archive from the standard input, and import the files listed
therein into the store.  Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
keys (see @code{--authorize} below.)

@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.

@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemon.  This is a prerequisite before
archives can be exported with @code{--export}.  Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.

The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret.)  When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).

@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.

The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}.  The file contains
@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.

@item --extract=@var{directory}
@itemx -x @var{directory}
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
low-level operation needed in only very narrow use cases; see below.

For example, the following command extracts the substitute for Emacs
served by @code{hydra.gnu.org} to @file{/tmp/emacs}:

@example
$ wget -O - \
  https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
  | bunzip2 | guix archive -x /tmp/emacs
@end example

Single-item archives are different from multiple-item archives produced
by @command{guix archive --export}; they contain a single store item,
and they do @emph{not} embed a signature.  Thus this operation does
@emph{no} signature verification and its output should be considered
unsafe.

The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers.

@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 a 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
* Defining Packages::           Defining new packages.
* Build Systems::               Specifying how packages are built.
* 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::          Fiddling with Guix interactively.
@end menu

@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:

@example
(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 "http://www.gnu.org/software/hello/")
    (license gpl3+)))
@end example

@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, @var{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, @var{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.

@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}).  Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
@code{--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 @var{gawk}
variable; @var{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, @var{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 @code{.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{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn

@cindex package transformations
@cindex input rewriting
@cindex dependency tree rewriting
Packages can be manipulated in arbitrary ways.  An example of a useful
transformation is @dfn{input rewriting}, whereby the dependency tree of
a package is rewritten by replacing specific inputs by others:

@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
           [@var{rewrite-name}]
Return a procedure that, when passed a package, replaces its direct and
indirect dependencies (but not its implicit inputs) according to
@var{replacements}.  @var{replacements} is a list of package pairs; the
first element of each pair is the package to replace, and the second one
is the replacement.

Optionally, @var{rewrite-name} is a one-argument procedure that takes
the name of a package and returns its new name after rewrite.
@end deffn

@noindent
Consider this example:

@example
(define libressl-instead-of-openssl
  ;; This is a procedure to replace OPENSSL by LIBRESSL,
  ;; recursively.
  (package-input-rewriting `((,openssl . ,libressl))))

(define git-with-libressl
  (libressl-instead-of-openssl git))
@end example

@noindent
Here we first define a rewriting procedure that replaces @var{openssl}
with @var{libressl}.  Then we use it to define a @dfn{variant} of the
@var{git} package that uses @var{libressl} instead of @var{openssl}.
This is exactly what the @option{--with-input} command-line option does
(@pxref{Package Transformation Options, @option{--with-input}}).

A more generic procedure to rewrite a package dependency graph is
@code{package-mapping}: it supports arbitrary changes to nodes in the
graph.

@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
Return a procedure that, given a package, applies @var{proc} to all the packages
depended on and returns the resulting package.  The procedure stops recursion
when @var{cut?} returns true for a given package.
@end deffn

@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:

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

@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 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 a C/C++ library 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.  To ensure that libraries written in those languages can find
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.

@item @code{self-native-input?} (default: @code{#f})
This is a Boolean field telling whether the package should use itself as
a native input when cross-compiling.

@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: @var{%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{maintainers} (default: @code{'()})
The list of maintainers of the package, as @code{maintainer} objects.

@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


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

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

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

@item @code{method}
A procedure that handles the URI.

Examples include:

@table @asis
@item @var{url-fetch} from @code{(guix download)}
download a file from the HTTP, HTTPS, or FTP URL specified in the
@code{uri} field;

@vindex git-fetch
@item @var{git-fetch} from @code{(guix git-download)}
clone the Git version control repository, and check out the revision
specified in the @code{uri} field as a @code{git-reference} object; a
@code{git-reference} looks like this:

@example
(git-reference
  (url "git://git.debian.org/git/pkg-shadow/shadow")
  (commit "v4.1.5.1"))
@end example
@end table

@item @code{sha256}
A bytevector containing the SHA-256 hash of the source.  Typically the
@code{base32} form is used here to generate the bytevector from a
base-32 string.

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")})