guix.texi

compiling modules.  It can be @code{#f}, @code{#t}, or @code{'detailed}.

The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn

@cindex file-like objects
The @code{local-file}, @code{plain-file}, @code{computed-file},
@code{program-file}, and @code{scheme-file} procedures below return
@dfn{file-like objects}.  That is, when unquoted in a G-expression,
these objects lead to a file in the store.  Consider this G-expression:

@lisp
#~(system* #$(file-append glibc "/sbin/nscd") "-f"
           #$(local-file "/tmp/my-nscd.conf"))
@end lisp

The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
to the store.  Once expanded, for instance @i{via}
@code{gexp->derivation}, the G-expression refers to that copy under
@file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
does not have any effect on what the G-expression does.
@code{plain-file} can be used similarly; it differs in that the file
content is directly passed as a string.

@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
   [#:recursive? #f] [#:select? (const #t)]
Return an object representing local file @var{file} to add to the store;
this object can be used in a gexp.  If @var{file} is a literal string
denoting a relative file name, it is looked up relative to the source
file where it appears; if @var{file} is not a literal string, it is
looked up relative to the current working directory at run time.
@var{file} will be added to the store under @var{name}--by default the
base name of @var{file}.

When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
designates a flat file and @var{recursive?} is true, its contents are added, and its
permission bits are kept.

When @var{recursive?} is true, call @code{(@var{select?} @var{file}
@var{stat})} for each directory entry, where @var{file} is the entry's
absolute file name and @var{stat} is the result of @code{lstat}; exclude
entries for which @var{select?} does not return true.

This is the declarative counterpart of the @code{interned-file} monadic
procedure (@pxref{The Store Monad, @code{interned-file}}).
@end deffn

@deffn {Scheme Procedure} plain-file @var{name} @var{content}
Return an object representing a text file called @var{name} with the given
@var{content} (a string or a bytevector) to be added to the store.

This is the declarative counterpart of @code{text-file}.
@end deffn

@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
          [#:options '(#:local-build? #t)]
Return an object representing the store item @var{name}, a file or
directory computed by @var{gexp}.  @var{options}
is a list of additional arguments to pass to @code{gexp->derivation}.

This is the declarative counterpart of @code{gexp->derivation}.
@end deffn

@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
  [#:guile (default-guile)] [#:module-path %load-path] @
  [#:system (%current-system)] [#:target #f]
Return an executable script @var{name} that runs @var{exp} using
@var{guile}, with @var{exp}'s imported modules in its search path.
Look up @var{exp}'s modules in @var{module-path}.

The example below builds a script that simply invokes the @command{ls}
command:

@lisp
(use-modules (guix gexp) (gnu packages base))

(gexp->script "list-files"
              #~(execl #$(file-append coreutils "/bin/ls")
                       "ls"))
@end lisp

When ``running'' it through the store (@pxref{The Store Monad,
@code{run-with-store}}), we obtain a derivation that produces an
executable file @file{/gnu/store/@dots{}-list-files} along these lines:

@example
#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
!#
(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
@end example
@end deffn

@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
          [#:guile #f] [#:module-path %load-path]
Return an object representing the executable store item @var{name} that
runs @var{gexp}.  @var{guile} is the Guile package used to execute that
script.  Imported modules of @var{gexp} are looked up in @var{module-path}.

This is the declarative counterpart of @code{gexp->script}.
@end deffn

@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
            [#:set-load-path? #t] [#:module-path %load-path] @
            [#:splice? #f] @
            [#:guile (default-guile)]
Return a derivation that builds a file @var{name} containing @var{exp}.
When @var{splice?}  is true, @var{exp} is considered to be a list of
expressions that will be spliced in the resulting file.

When @var{set-load-path?} is true, emit code in the resulting file to
set @code{%load-path} and @code{%load-compiled-path} to honor
@var{exp}'s imported modules.  Look up @var{exp}'s modules in
@var{module-path}.

The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn

@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
          [#:splice? #f] [#:set-load-path? #t]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.

This is the declarative counterpart of @code{gexp->file}.
@end deffn

@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file
containing all of @var{text}.  @var{text} may list, in addition to
strings, objects of any type that can be used in a gexp: packages,
derivations, local file objects, etc.  The resulting store file holds
references to all these.

This variant should be preferred over @code{text-file} anytime the file
to create will reference items from the store.  This is typically the
case when building a configuration file that embeds store file names,
like this:

@lisp
(define (profile.sh)
  ;; Return the name of a shell script in the store that
  ;; initializes the 'PATH' environment variable.
  (text-file* "profile.sh"
              "export PATH=" coreutils "/bin:"
              grep "/bin:" sed "/bin\n"))
@end lisp

In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
preventing them from being garbage-collected during its lifetime.
@end deffn

@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
Return an object representing store file @var{name} containing
@var{text}.  @var{text} is a sequence of strings and file-like objects,
as in:

@lisp
(mixed-text-file "profile"
                 "export PATH=" coreutils "/bin:" grep "/bin")
@end lisp

This is the declarative counterpart of @code{text-file*}.
@end deffn

@deffn {Scheme Procedure} file-union @var{name} @var{files}
Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
Each item in @var{files} must be a two-element list where the first element is the
file name to use in the new directory, and the second element is a gexp
denoting the target file.  Here's an example:

@lisp
(file-union "etc"
            `(("hosts" ,(plain-file "hosts"
                                    "127.0.0.1 localhost"))
              ("bashrc" ,(plain-file "bashrc"
                                     "alias ls='ls --color=auto'"))))
@end lisp

This yields an @code{etc} directory containing these two files.
@end deffn

@deffn {Scheme Procedure} directory-union @var{name} @var{things}
Return a directory that is the union of @var{things}, where @var{things} is a list of
file-like objects denoting directories.  For example:

@lisp
(directory-union "guile+emacs" (list guile emacs))
@end lisp

yields a directory that is the union of the @code{guile} and @code{emacs} packages.
@end deffn

@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
Return a file-like object that expands to the concatenation of @var{obj}
and @var{suffix}, where @var{obj} is a lowerable object and each
@var{suffix} is a string.

As an example, consider this gexp:

@lisp
(gexp->script "run-uname"
              #~(system* #$(file-append coreutils
                                        "/bin/uname")))
@end lisp

The same effect could be achieved with:

@lisp
(gexp->script "run-uname"
              #~(system* (string-append #$coreutils
                                        "/bin/uname")))
@end lisp

There is one difference though: in the @code{file-append} case, the
resulting script contains the absolute file name as a string, whereas in
the second case, the resulting script contains a @code{(string-append
@dots{})} expression to construct the file name @emph{at run time}.
@end deffn

@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
Bind @var{system} to the currently targeted system---e.g.,
@code{"x86_64-linux"}---within @var{body}.

In the second case, additionally bind @var{target} to the current
cross-compilation target---a GNU triplet such as
@code{"arm-linux-gnueabihf"}---or @code{#f} if we are not
cross-compiling.

@code{let-system} is useful in the occasional case where the object
spliced into the gexp depends on the target system, as in this example:

@example
#~(system*
   #+(let-system system
       (cond ((string-prefix? "armhf-" system)
              (file-append qemu "/bin/qemu-system-arm"))
             ((string-prefix? "x86_64-" system)
              (file-append qemu "/bin/qemu-system-x86_64"))
             (else
              (error "dunno!"))))
   "-net" "user" #$image)
@end example
@end deffn

@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
This macro is similar to the @code{parameterize} form for
dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
Guile Reference Manual}).  The key difference is that it takes effect
when the file-like object returned by @var{exp} is lowered to a
derivation or store item.

A typical use of @code{with-parameters} is to force the system in effect
for a given object:

@lisp
(with-parameters ((%current-system "i686-linux"))
  coreutils)
@end lisp

The example above returns an object that corresponds to the i686 build
of Coreutils, regardless of the current value of @code{%current-system}.
@end deffn


Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools.  To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
@code{(guix build @dots{})} name space.

@cindex lowering, of high-level objects in gexps
Internally, high-level objects are @dfn{lowered}, using their compiler,
to either derivations or store items.  For instance, lowering a package
yields a derivation, and lowering a @code{plain-file} yields a store
item.  This is achieved using the @code{lower-object} monadic procedure.

@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
           [#:target #f]
Return as a value in @code{%store-monad} the derivation or store item
corresponding to @var{obj} for @var{system}, cross-compiling for
@var{target} if @var{target} is true.  @var{obj} must be an object that
has an associated gexp compiler, such as a @code{<package>}.
@end deffn

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

@cindex REPL, read-eval-print loop, script
The @command{guix repl} command makes it easier to program Guix in Guile
by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
programming (@pxref{Using Guile Interactively,,, guile,
GNU Guile Reference Manual}), or by running Guile scripts
(@pxref{Running Guile Scripts,,, guile,
GNU Guile Reference Manual}).
Compared to just launching the @command{guile}
command, @command{guix repl} guarantees that all the Guix modules and all its
dependencies are available in the search path.

The general syntax is:

@example
guix repl @var{options} [@var{file} @var{args}]
@end example

When a @var{file} argument is provided, @var{file} is
executed as a Guile scripts:

@example
guix repl my-script.scm
@end example

To pass arguments to the script, use @code{--} to prevent them from
being interpreted as arguments to @command{guix repl} itself:

@example
guix repl -- my-script.scm --input=foo.txt
@end example

To make a script executable directly from the shell, using the guix
executable that is on the user's search path, add the following two
lines at the top of the script:

@example
@code{#!/usr/bin/env -S guix repl --}
@code{!#}
@end example

Without a file name argument, a Guile REPL is started:

@example
$ guix repl
scheme@@(guile-user)> ,use (gnu packages base)
scheme@@(guile-user)> coreutils
$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
@end example

@cindex inferiors
In addition, @command{guix repl} implements a simple machine-readable REPL
protocol for use by @code{(guix inferior)}, a facility to interact with
@dfn{inferiors}, separate processes running a potentially different revision
of Guix.

The available options are as follows:

@table @code
@item --type=@var{type}
@itemx -t @var{type}
Start a REPL of the given @var{TYPE}, which can be one of the following:

@table @code
@item guile
This is default, and it spawns a standard full-featured Guile REPL.
@item machine
Spawn a REPL that uses the machine-readable protocol.  This is the protocol
that the @code{(guix inferior)} module speaks.
@end table

@item --listen=@var{endpoint}
By default, @command{guix repl} reads from standard input and writes to
standard output.  When this option is passed, it will instead listen for
connections on @var{endpoint}.  Here are examples of valid options:

@table @code
@item --listen=tcp:37146
Accept connections on localhost on port 37146.

@item --listen=unix:/tmp/socket
Accept connections on the Unix-domain socket @file{/tmp/socket}.
@end table

@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).

This allows users to define their own packages and make them visible to
the script or REPL.

@item -q
Inhibit loading of the @file{~/.guile} file.  By default, that
configuration file is loaded when spawning a @code{guile} REPL.
@end table

@c *********************************************************************
@node Utilities
@chapter Utilities

This section describes Guix command-line utilities.  Some of them are
primarily targeted at developers and users who write new package
definitions, while others are more generally useful.  They complement
the Scheme programming interface of Guix in a convenient way.

@menu
* Invoking guix build::         Building packages from the command line.
* Invoking guix edit::          Editing package definitions.
* Invoking guix download::      Downloading a file and printing its hash.
* Invoking guix hash::          Computing the cryptographic hash of a file.
* Invoking guix import::        Importing package definitions.
* Invoking guix refresh::       Updating package definitions.
* Invoking guix lint::          Finding errors in package definitions.
* Invoking guix size::          Profiling disk usage.
* Invoking guix graph::         Visualizing the graph of packages.
* Invoking guix publish::       Sharing substitutes.
* Invoking guix challenge::     Challenging substitute servers.
* Invoking guix copy::          Copying to and from a remote store.
* Invoking guix container::     Process isolation.
* Invoking guix weather::       Assessing substitute availability.
* Invoking guix processes::     Listing client processes.
@end menu

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

@cindex package building
@cindex @command{guix build}
The @command{guix build} command builds packages or derivations and
their dependencies, and prints the resulting store paths.  Note that it
does not modify the user's profile---this is the job of the
@command{guix package} command (@pxref{Invoking guix package}).  Thus,
it is mainly useful for distribution developers.

The general syntax is:

@example
guix build @var{options} @var{package-or-derivation}@dots{}
@end example

As an example, the following command builds the latest versions of Emacs
and of Guile, displays their build logs, and finally displays the
resulting directories:

@example
guix build emacs guile
@end example

Similarly, the following command builds all the available packages:

@example
guix build --quiet --keep-going \
  `guix package -A | cut -f1,2 --output-delimiter=@@`
@end example

@var{package-or-derivation} may be either the name of a package found in
the software distribution such as @code{coreutils} or
@code{coreutils@@8.20}, or a derivation such as
@file{/gnu/store/@dots{}-coreutils-8.19.drv}.  In the former case, a
package with the corresponding name (and optionally version) is searched
for among the GNU distribution modules (@pxref{Package Modules}).

Alternatively, the @option{--expression} option may be used to specify a
Scheme expression that evaluates to a package; this is useful when
disambiguating among several same-named packages or package variants is
needed.

There may be zero or more @var{options}.  The available options are
described in the subsections below.

@menu
* Common Build Options::        Build options for most commands.
* Package Transformation Options::  Creating variants of packages.
* Additional Build Options::    Options specific to 'guix build'.
* Debugging Build Failures::    Real life packaging experience.
@end menu

@node Common Build Options
@subsection Common Build Options

A number of options that control the build process are common to
@command{guix build} and other commands that can spawn builds, such as
@command{guix package} or @command{guix archive}.  These are the
following:

@table @code

@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).

This allows users to define their own packages and make them visible to
the command-line tools.

@item --keep-failed
@itemx -K
Keep the build tree of failed builds.  Thus, if a build fails, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at
the end of the build log.  This is useful when debugging build issues.
@xref{Debugging Build Failures}, for tips and tricks on how to debug
build issues.

This option implies @option{--no-offload}, and it has no effect when
connecting to a remote daemon with a @code{guix://} URI (@pxref{The
Store, the @env{GUIX_DAEMON_SOCKET} variable}).

@item --keep-going
@itemx -k
Keep going when some of the derivations fail to build; return only once
all the builds have either completed or failed.

The default behavior is to stop as soon as one of the specified
derivations has failed.

@item --dry-run
@itemx -n
Do not build the derivations.

@anchor{fallback-option}
@item --fallback
When substituting a pre-built binary fails, fall back to building
packages locally (@pxref{Substitution Failure}).

@item --substitute-urls=@var{urls}
@anchor{client-substitute-urls}
Consider @var{urls} the whitespace-separated list of substitute source
URLs, overriding the default list of URLs of @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).

This means that substitutes may be downloaded from @var{urls}, provided
they are signed by a key authorized by the system administrator
(@pxref{Substitutes}).

When @var{urls} is the empty string, substitutes are effectively
disabled.

@item --no-substitutes
Do not use substitutes for build products.  That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).

@item --no-grafts
Do not ``graft'' packages.  In practice, this means that package updates
available as grafts are not applied.  @xref{Security Updates}, for more
information on grafts.

@item --rounds=@var{n}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical.

This is a useful way to detect non-deterministic builds processes.
Non-deterministic build processes are a problem because they make it
practically impossible for users to @emph{verify} whether third-party
binaries are genuine.  @xref{Invoking guix challenge}, for more.

Note that, currently, the differing build results are not kept around,
so you will have to manually investigate in case of an error---e.g., by
stashing one of the build results with @code{guix archive --export}
(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
the two results.

@item --no-offload
Do not use offload builds to other machines (@pxref{Daemon Offload
Setup}).  That is, always build things locally instead of offloading
builds to remote machines.

@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure.

By default, the daemon's setting is honored (@pxref{Invoking
guix-daemon, @option{--max-silent-time}}).

@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.

By default, the daemon's setting is honored (@pxref{Invoking
guix-daemon, @option{--timeout}}).

@c Note: This option is actually not part of %standard-build-options but
@c most programs honor it.
@cindex verbosity, of the command-line tools
@cindex build logs, verbosity
@item -v @var{level}
@itemx --verbosity=@var{level}
Use the given verbosity @var{level}, an integer.  Choosing 0 means that no
output is produced, 1 is for quiet output, and 2 shows all the build log
output on standard error.

@item --cores=@var{n}
@itemx -c @var{n}
Allow the use of up to @var{n} CPU cores for the build.  The special
value @code{0} means to use as many CPU cores as available.

@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel.  @xref{Invoking
guix-daemon, @option{--max-jobs}}, for details about this option and the
equivalent @command{guix-daemon} option.

@item --debug=@var{level}
Produce debugging output coming from the build daemon.  @var{level} must be an
integer between 0 and 5; higher means more verbose output.  Setting a level of
4 or more may be helpful when debugging setup issues with the build daemon.

@end table

Behind the scenes, @command{guix build} is essentially an interface to
the @code{package-derivation} procedure of the @code{(guix packages)}
module, and to the @code{build-derivations} procedure of the @code{(guix
derivations)} module.

In addition to options explicitly passed on the command line,
@command{guix build} and other @command{guix} commands that support
building honor the @env{GUIX_BUILD_OPTIONS} environment variable.

@defvr {Environment Variable} GUIX_BUILD_OPTIONS
Users can define this variable to a list of command line options that
will automatically be used by @command{guix build} and other
@command{guix} commands that can perform builds, as in the example
below:

@example
$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example

These options are parsed independently, and the result is appended to
the parsed command-line options.
@end defvr


@node Package Transformation Options
@subsection Package Transformation Options

@cindex package variants
Another set of command-line options supported by @command{guix build}
and also @command{guix package} are @dfn{package transformation
options}.  These are options that make it possible to define @dfn{package
variants}---for instance, packages built from different source code.
This is a convenient way to create customized packages on the fly
without having to type in the definitions of package variants
(@pxref{Defining Packages}).

@table @code

@item --with-source=@var{source}
@itemx --with-source=@var{package}=@var{source}
@itemx --with-source=@var{package}@@@var{version}=@var{source}
Use @var{source} as the source of @var{package}, and @var{version} as
its version number.
@var{source} must be a file name or a URL, as for @command{guix
download} (@pxref{Invoking guix download}).

When @var{package} is omitted,
it is taken to be the package name specified on the
command line that matches the base of @var{source}---e.g.,
if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
package is @code{guile}.

Likewise, when @var{version} is omitted, the version string is inferred from
@var{source}; in the previous example, it is @code{2.0.10}.

This option allows users to try out versions of packages other than the
one provided by the distribution.  The example below downloads
@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
the @code{ed} package:

@example
guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
@end example

As a developer, @option{--with-source} makes it easy to test release
candidates:

@example
guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
@end example

@dots{} or to build from a checkout in a pristine environment:

@example
$ git clone git://git.sv.gnu.org/guix.git
$ guix build guix --with-source=guix@@1.0=./guix
@end example

@item --with-input=@var{package}=@var{replacement}
Replace dependency on @var{package} by a dependency on
@var{replacement}.  @var{package} must be a package name, and
@var{replacement} must be a package specification such as @code{guile}
or @code{guile@@1.8}.

For instance, the following command builds Guix, but replaces its
dependency on the current stable version of Guile with a dependency on
the legacy version of Guile, @code{guile@@2.0}:

@example
guix build --with-input=guile=guile@@2.0 guix
@end example

This is a recursive, deep replacement.  So in this example, both
@code{guix} and its dependency @code{guile-json} (which also depends on
@code{guile}) get rebuilt against @code{guile@@2.0}.

This is implemented using the @code{package-input-rewriting} Scheme
procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).

@item --with-graft=@var{package}=@var{replacement}
This is similar to @option{--with-input} but with an important difference:
instead of rebuilding the whole dependency chain, @var{replacement} is
built and then @dfn{grafted} onto the binaries that were initially
referring to @var{package}.  @xref{Security Updates}, for more
information on grafts.

For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
and all its dependencies, replacing references to the version of GnuTLS
they currently refer to:

@example
guix build --with-graft=gnutls=gnutls@@3.5.4 wget
@end example

This has the advantage of being much faster than rebuilding everything.
But there is a caveat: it works if and only if @var{package} and
@var{replacement} are strictly compatible---for example, if they provide
a library, the application binary interface (ABI) of those libraries
must be compatible.  If @var{replacement} is somehow incompatible with
@var{package}, then the resulting package may be unusable.  Use with
care!

@item --with-git-url=@var{package}=@var{url}
@cindex Git, using the latest commit
@cindex latest commit, building
Build @var{package} from the latest commit of the @code{master} branch of the
Git repository at @var{url}.  Git sub-modules of the repository are fetched,
recursively.

For example, the following command builds the NumPy Python library against the
latest commit of the master branch of Python itself:

@example
guix build python-numpy \
  --with-git-url=python=https://github.com/python/cpython
@end example

This option can also be combined with @option{--with-branch} or
@option{--with-commit} (see below).

@cindex continuous integration
Obviously, since it uses the latest commit of the given branch, the result of
such a command varies over time.  Nevertheless it is a convenient way to
rebuild entire software stacks against the latest commit of one or more
packages.  This is particularly useful in the context of continuous
integration (CI).

Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
consecutive accesses to the same repository.  You may want to clean it up once
in a while to save disk space.

@item --with-branch=@var{package}=@var{branch}
Build @var{package} from the latest commit of @var{branch}.  If the
@code{source} field of @var{package} is an origin with the @code{git-fetch}
method (@pxref{origin Reference}) or a @code{git-checkout} object, the
repository URL is taken from that @code{source}.  Otherwise you have to use
@option{--with-git-url} to specify the URL of the Git repository.

For instance, the following command builds @code{guile-sqlite3} from the
latest commit of its @code{master} branch, and then builds @code{guix} (which
depends on it) and @code{cuirass} (which depends on @code{guix}) against this
specific @code{guile-sqlite3} build:

@example
guix build --with-branch=guile-sqlite3=master cuirass
@end example

@item --with-commit=@var{package}=@var{commit}
This is similar to @option{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch.  @var{commit} must be a valid
Git commit SHA1 identifier or a tag.
@end table

@node Additional Build Options
@subsection Additional Build Options

The command-line options presented below are specific to @command{guix
build}.

@table @code

@item --quiet
@itemx -q
Build quietly, without displaying the build log; this is equivalent to
@option{--verbosity=0}.  Upon completion, the build log is kept in @file{/var}
(or similar) and can always be retrieved using the @option{--log-file} option.

@item --file=@var{file}
@itemx -f @var{file}
Build the package, derivation, or other file-like object that the code within
@var{file} evaluates to (@pxref{G-Expressions, file-like objects}).

As an example, @var{file} might contain a package definition like this
(@pxref{Defining Packages}):

@lisp
@include package-hello.scm
@end lisp

The @var{file} may also contain a JSON representation of one or more
package definitions.  Running @code{guix build -f} on @file{hello.json}
with the following contents would result in building the packages
@code{myhello} and @code{greeter}:

@example
@verbatiminclude package-hello.json
@end example

@item --manifest=@var{manifest}
@itemx -m @var{manifest}
Build all packages listed in the given @var{manifest}
(@pxref{profile-manifest, @option{--manifest}}).

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

For example, @var{expr} may be @code{(@@ (gnu packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.

Alternatively, @var{expr} may be a G-expression, in which case it is used
as a build program passed to @code{gexp->derivation}
(@pxref{G-Expressions}).

Lastly, @var{expr} may refer to a zero-argument monadic procedure
(@pxref{The Store Monad}).  The procedure must return a derivation as a
monadic value, which is then passed through @code{run-with-store}.

@item --source
@itemx -S
Build the source derivations of the packages, rather than the packages
themselves.

For instance, @code{guix build -S gcc} returns something like
@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
source tarball.

The returned source tarball is the result of applying any patches and
code snippets specified in the package @code{origin} (@pxref{Defining
Packages}).

Note that @command{guix build -S} compiles the sources only of the
specified packages.  They do not include the sources of statically
linked dependencies and by themselves are insufficient for reproducing
the packages.

@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively.  This is a handy way to obtain a local copy
of all the source code needed to build @var{packages}, allowing you to
eventually build them even without network access.  It is an extension
of the @option{--source} option and can accept one of the following
optional argument values:

@table @code
@item package
This value causes the @option{--sources} option to behave in the same way
as the @option{--source} option.

@item all
Build the source derivations of all packages, including any source that
might be listed as @code{inputs}.  This is the default value.

@example
$ guix build --sources tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
@end example

@item transitive
Build the source derivations of all packages, as well of all transitive
inputs to the packages.  This can be used e.g.@: to
prefetch package source for later offline building.

@example
$ guix build --sources=transitive tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
   /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
   /gnu/store/@dots{}-grep-2.21.tar.xz.drv
   /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
   /gnu/store/@dots{}-make-4.1.tar.xz.drv
   /gnu/store/@dots{}-bash-4.3.tar.xz.drv
@dots{}
@end example

@end table

@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.  The @command{guix build} command allows
you to repeat this option several times, in which case it builds for all the
specified systems; other commands ignore extraneous @option{-s} options.

@quotation Note
The @option{--system} flag is for @emph{native} compilation and must not
be confused with cross-compilation.  See @option{--target} below for
information on cross-compilation.
@end quotation

An example use of this is on Linux-based systems, which can emulate
different personalities.  For instance, passing
@option{--system=i686-linux} on an @code{x86_64-linux} system or
@option{--system=armhf-linux} on an @code{aarch64-linux} system allows
you to build packages in a complete 32-bit environment.

@quotation Note
Building for an @code{armhf-linux} system is unconditionally enabled on
@code{aarch64-linux} machines, although certain aarch64 chipsets do not
allow for this functionality, notably the ThunderX.
@end quotation

Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
is enabled (@pxref{Virtualization Services,
@code{qemu-binfmt-service-type}}), you can build for any system for
which a QEMU @code{binfmt_misc} handler is installed.

Builds for a system other than that of the machine you are using can
also be offloaded to a remote machine of the right architecture.
@xref{Daemon Offload Setup}, for more information on offloading.

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

@anchor{build-check}
@item --check
@cindex determinism, checking
@cindex reproducibility, checking
Rebuild @var{package-or-derivation}, which are already available in the
store, and raise an error if the build results are not bit-for-bit
identical.

This mechanism allows you to check whether previously installed
substitutes are genuine (@pxref{Substitutes}), or whether the build result
of a package is deterministic.  @xref{Invoking guix challenge}, for more
background information and tools.

When used in conjunction with @option{--keep-failed}, the differing
output is kept in the store, under @file{/gnu/store/@dots{}-check}.
This makes it easy to look for differences between the two results.

@item --repair
@cindex repairing store items
@cindex corruption, recovering from
Attempt to repair the specified store items, if they are corrupt, by
re-downloading or rebuilding them.

This operation is not atomic and thus restricted to @code{root}.

@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.

@item --root=@var{file}
@itemx -r @var{file}
@cindex GC roots, adding
@cindex garbage collector roots, adding
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

Consequently, the results of this @command{guix build} invocation are
protected from garbage collection until @var{file} is removed.  When
that option is omitted, build results are eligible for garbage
collection as soon as the build completes.  @xref{Invoking guix gc}, for
more on GC roots.

@item --log-file
@cindex build logs, access
Return the build log file names or URLs for the given
@var{package-or-derivation}, or raise an error if build logs are
missing.

This works regardless of how packages or derivations are specified.  For
instance, the following invocations are equivalent:

@example
guix build --log-file `guix build -d guile`
guix build --log-file `guix build guile`
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example

If a log is unavailable locally, and unless @option{--no-substitutes} is
passed, the command looks for a corresponding log on one of the
substitute servers (as specified with @option{--substitute-urls}).

So for instance, imagine you want to see the build log of GDB on MIPS,
but you are actually on an @code{x86_64} machine:

@example
$ guix build --log-file gdb -s aarch64-linux
https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
@end example

You can freely access a huge library of build logs!
@end table