doc: Document `guix-build'.

* doc/guix.texi (Invoking guix-build): Populate.

1 files changed, 80 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 6ae6ff89ee..8cfaa2a300 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -148,6 +148,86 @@ The remainder of this manual describes them.
 @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.  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 a derivation such
+as @file{/nix/store/xxx-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{(@@ (distro 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/xxx-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.
+@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 Acknowledgments
 @chapter Acknowledgments