guix.texi

than the one that calls @code{build-expression->derivation}: it is run
by a Guile process launched by the daemon, typically in a chroot.  So,
while there is a single language for both the @dfn{host} and the build
side, there are really two @dfn{strata} of code: the host-side, and the
build-side code@footnote{The term @dfn{stratum} in this context was
coined by Manuel Serrano et al. in the context of their work on Hop.}.
This distinction is important to keep in mind, notably when using
higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
Packages}).  For this reason, Guix modules that are meant to be used in
the build stratum are kept in the @code{(guix build @dots{})} name
space.

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

@menu
* Invoking guix build:: Building packages from the command line.
@end menu

@node Invoking guix build
@section Invoking @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

@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{/nix/store/@dots{}-coreutils-8.19.drv}.  Alternatively, the
@code{--expression} option may be used to specify a Scheme expression
that evaluates to a package; this is useful when disambiguation among
several same-named packages or package variants is needed.

The @var{options} may be zero or more of the following:

@table @code

@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package @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.

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

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

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

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

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

@item --keep-failed
@itemx -K
Keep the build tree of failed builds.  Thus, if a build fail, 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.

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

@item --no-substitutes
Build instead of resorting to pre-built substitutes.

@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 --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

@item --verbosity=@var{level}
Use the given verbosity level.  @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
store)} module.

@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution

Guix comes with a distribution of free software@footnote{The term
``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}  that form the basis of the GNU system.  This
includes core GNU packages such as GNU libc, GCC, and Binutils, as well
as many GNU and non-GNU applications.  The complete list of available
packages can be seen by running @command{guix package} (@pxref{Invoking
guix package}):

@example
guix package --list-available
@end example

The package definitions of the distribution may are provided by Guile
modules in the @code{(gnu packages ...)} name space---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)} module provides
facilities for searching for packages.

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.  These are statically-linked binaries of the core
tools without which building anything at all would be impossible.


Our goal is to build a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.

Building this distribution is a cooperative effort, and you are invited
to join!  Please get in touch with us on @email{bug-guix@@gnu.org}.  We
welcome ideas, bug reports, patches, and anything that may be helpful to
the project.


@c *********************************************************************
@node Acknowledgments
@chapter Acknowledgments

Guix is based on the Nix package manager, which was designed and
implemented by Eelco Dolstra.  Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes.  Without this work, Guix would not exist.

The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.

@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@c *********************************************************************
@node Concept Index
@unnumbered Concept Index
@printindex cp

@node Function Index
@unnumbered Function Index
@printindex fn

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End: