04/10: doc: Add subsections to 'Invoking guix build'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit ccd7158d2ab182713891701e08970dbd6b68f4e5
Author: Ludovic Courtès <address@hidden>
Date:   Sun Jan 31 21:04:39 2016 +0100

    doc: Add subsections to 'Invoking guix build'.
    
    * doc/guix.texi (Invoking guix build): Add example.  Shuffle options in
    the new subsections below.
    (Common Build Options, Additional Build Options): New nodes.
    (Invoking guix archive): Refer to "Common Build Options".
    (Invoking guix environment): Likewise.
    (Invoking guix system): Likewise.
    
    fixlet
---
 doc/guix.texi |  294 +++++++++++++++++++++++++++++++--------------------------
 1 files changed, 161 insertions(+), 133 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 63f5d32..cae55c1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1642,8 +1642,8 @@ Consequently, this command must be used with care.
 @end table
 
 Finally, since @command{guix package} may actually start build
-processes, it supports all the common build options that @command{guix
-build} supports (@pxref{Invoking guix build, common build options}).
+processes, it supports all the common build options (@pxref{Common Build
+Options}).
 
 @node Substitutes
 @section Substitutes
@@ -2139,8 +2139,7 @@ guix archive --export git:gui /gnu/store/...-emacs-24.3 > 
great.nar
 
 If the specified packages are not built yet, @command{guix archive}
 automatically builds them.  The build process may be controlled with the
-same options that can be passed to the @command{guix build} command
-(@pxref{Invoking guix build, common build options}).
+common build options (@pxref{Common Build Options}).
 
 @c *********************************************************************
 @include emacs.texi
@@ -3779,6 +3778,21 @@ The general syntax is:
 guix build @var{options} @address@hidden
 @end example
 
+As an example, the following command builds the latest version of Emacs
+and of Guile, displays their build logs, and finally displays the
+resulting directories:
+
address@hidden
+guix build emacs guile
address@hidden example
+
+Similarly, the following command builds all the available packages:
+
address@hidden
+guix build --keep-going \
+  `guix package -A | cut -f1,2 --output-delimiter=@@`
address@hidden 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
@@ -3791,7 +3805,145 @@ 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:
+There may be zero or more @var{options}.  The available options are
+described in the subsections below.
+
address@hidden
+* Common Build Options::        Build options for most commands.
+* Additional Build Options::    Options specific to 'guix build'.
address@hidden menu
+
address@hidden Common Build Options
address@hidden Common Build Options
+
+A number of options that control the build process are common to
address@hidden build} and other commands that can spawn builds, such as
address@hidden package} or @command{guix archive}.  These are the
+following:
+
address@hidden @code
+
address@hidden address@hidden
address@hidden -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.
+
address@hidden --keep-failed
address@hidden -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.
+
address@hidden --keep-going
address@hidden -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.
+
address@hidden --dry-run
address@hidden -n
+Do not build the derivations.
+
address@hidden --fallback
+When substituting a pre-built binary fails, fall back to building
+packages locally.
+
address@hidden address@hidden
address@hidden
+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}).
+
address@hidden --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}).
+
address@hidden address@hidden
+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},
+then rebuilding, and finally comparing the two results.
+
address@hidden --no-build-hook
+Do not attempt to offload builds @i{via} the daemon's ``build hook''
+(@pxref{Daemon Offload Setup}).  That is, always build things locally
+instead of offloading builds to remote machines.
+
address@hidden address@hidden
+When the build or substitution process remains silent for more than
address@hidden, terminate it and report a build failure.
+
address@hidden address@hidden
+Likewise, when the build or substitution process lasts for more than
address@hidden, terminate it and report a build failure.
+
+By default there is no timeout.  This behavior can be restored with
address@hidden
+
address@hidden address@hidden
+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.
+
address@hidden address@hidden
address@hidden -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.
+
address@hidden address@hidden
address@hidden -M @var{n}
+Allow at most @var{n} build jobs in parallel.  @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
+
address@hidden 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,
address@hidden build} and other @command{guix} commands that support
+building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+
address@hidden {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
address@hidden commands that can perform builds, as in the example
+below:
+
address@hidden
+$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
address@hidden example
+
+These options are parsed independently, and the result is appended to
+the parsed command-line options.
address@hidden defvr
+
address@hidden Additional Build Options
address@hidden Additional Build Options
+
+The command-line options presented below are specific to @command{guix
+build}.
 
 @table @code
 
@@ -3987,130 +4139,6 @@ http://hydra.gnu.org/log/@dots{}-gdb-7.10
 You can freely access a huge library of build logs!
 @end table
 
address@hidden common build options
-In addition, 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:
-
address@hidden @code
-
address@hidden address@hidden
address@hidden -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.
-
address@hidden --keep-failed
address@hidden -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.
-
address@hidden --keep-going
address@hidden -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.
-
address@hidden --dry-run
address@hidden -n
-Do not build the derivations.
-
address@hidden --fallback
-When substituting a pre-built binary fails, fall back to building
-packages locally.
-
address@hidden address@hidden
address@hidden
-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}).
-
address@hidden --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}).
-
address@hidden address@hidden
-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},
-then rebuilding, and finally comparing the two results.
-
address@hidden --no-build-hook
-Do not attempt to offload builds @i{via} the daemon's ``build hook''
-(@pxref{Daemon Offload Setup}).  That is, always build things locally
-instead of offloading builds to remote machines.
-
address@hidden address@hidden
-When the build or substitution process remains silent for more than
address@hidden, terminate it and report a build failure.
-
address@hidden address@hidden
-Likewise, when the build or substitution process lasts for more than
address@hidden, terminate it and report a build failure.
-
-By default there is no timeout.  This behavior can be restored with
address@hidden
-
address@hidden address@hidden
-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.
-
address@hidden address@hidden
address@hidden -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.
-
address@hidden address@hidden
address@hidden -M @var{n}
-Allow at most @var{n} build jobs in parallel.  @xref{Invoking
-guix-daemon, @code{--max-jobs}}, for details about this option and the
-equivalent @command{guix-daemon} option.
-
address@hidden 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,
address@hidden build} and other @command{guix} commands that support
-building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
-
address@hidden {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
address@hidden commands that can perform builds, as in the example
-below:
-
address@hidden
-$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
address@hidden example
-
-These options are parsed independently, and the result is appended to
-the parsed command-line options.
address@hidden defvr
-
 
 @node Invoking guix edit
 @section Invoking @command{guix edit}
@@ -5118,7 +5146,7 @@ guix environment --container --share=$HOME=/exchange 
guile -- guile
 @end table
 
 It also supports all of the common build options that @command{guix
-build} supports (@pxref{Invoking guix build, common build options}).
+build} supports (@pxref{Common Build Options}).
 
 @node Invoking guix publish
 @section Invoking @command{guix publish}
@@ -9255,9 +9283,9 @@ This option requires Linux-libre 3.19 or newer.
 
 @end table
 
address@hidden can contain any of the common build options provided by
address@hidden build} (@pxref{Invoking guix build}).  In addition,
address@hidden can contain one of the following:
address@hidden can contain any of the common build options (@pxref{Common
+Build Options}).  In addition, @var{options} can contain one of the
+following:
 
 @table @option
 @item address@hidden