aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2012-11-07 17:07:15 +0100
committerLudovic Courtès <ludo@gnu.org>2012-11-07 17:07:15 +0100
commitc78bd12b44c1890a1daffe5dc9d91ce050251f77 (patch)
tree6f4693f5d322c1776fd1122a4a5811ef17da580e /doc
parentd3c9a1dae8fc0f78104a8a312faf71af84ba79ad (diff)
downloadguix-c78bd12b44c1890a1daffe5dc9d91ce050251f77.tar
guix-c78bd12b44c1890a1daffe5dc9d91ce050251f77.tar.gz
doc: Document `guix-build'.
* doc/guix.texi (Invoking guix-build): Populate.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi80
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