doc: Factorize documentation of common build options.

* doc/guix.texi (Invoking guix package): Remove documentation for
  --dry-run, --fallback, --no-substitutes, and --max-silent-time.  Add a
  cross-ref to "Invoking guix build".
  (Invoking guix archive): Add "common build options" as the cross-ref
  topic for "Invoking guix build".
  (Invoking guix build): Move common build options separately.  Add a
  paragraph to explain.
This commit is contained in:
Ludovic Courtès 2014-03-02 23:15:31 +01:00
parent ebb7aeff80
commit 70ee564299
1 changed files with 40 additions and 41 deletions

View File

@ -789,21 +789,6 @@ suggest setting these variables to @code{@var{profile}/include} and
@itemx -p @var{profile} @itemx -p @var{profile}
Use @var{profile} instead of the user's default profile. Use @var{profile} instead of the user's default profile.
@item --dry-run
@itemx -n
Show what would be done without actually doing it.
@item --fallback
When substituting a pre-built binary fails, fall back to building
packages locally.
@item --no-substitutes
Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries.
@item --max-silent-time=@var{seconds}
Same as for @command{guix build} (@pxref{Invoking guix build}).
@item --verbose @item --verbose
Produce verbose output. In particular, emit the environment's build log Produce verbose output. In particular, emit the environment's build log
on the standard error port. on the standard error port.
@ -918,6 +903,10 @@ Consequently, this command must be used with care.
@end table @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}).
@node Packages with Multiple Outputs @node Packages with Multiple Outputs
@section Packages with Multiple Outputs @section Packages with Multiple Outputs
@ -1176,7 +1165,7 @@ guix archive --export git:gui /nix/store/...-emacs-24.3 > great.nar
If the specified packages are not built yet, @command{guix archive} If the specified packages are not built yet, @command{guix archive}
automatically builds them. The build process may be controlled with the automatically builds them. The build process may be controlled with the
same options that can be passed to the @command{guix build} command same options that can be passed to the @command{guix build} command
(@pxref{Invoking guix build}). (@pxref{Invoking guix build, common build options}).
@c ********************************************************************* @c *********************************************************************
@ -1843,6 +1832,37 @@ configuration triplets,, configure, GNU Configure and Build System}).
Return the derivation paths, not the output paths, of the given Return the derivation paths, not the output paths, of the given
packages. packages.
@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 --log-file
Return the build log file names for the given
@var{package-or-derivation}s, 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
@end table
@cindex 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:
@table @code
@item --keep-failed @item --keep-failed
@itemx -K @itemx -K
Keep the build tree of failed builds. Thus, if a build fail, its build Keep the build tree of failed builds. Thus, if a build fail, its build
@ -1870,36 +1890,15 @@ instead of offloading builds to remote machines.
When the build or substitution process remains silent for more than When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure. @var{seconds}, terminate it and report a build failure.
@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} @item --verbosity=@var{level}
Use the given verbosity level. @var{level} must be an integer between 0 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 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. may be helpful when debugging setup issues with the build daemon.
@item --log-file @item --cores=@var{n}
Return the build log file names for the given @itemx -c @var{n}
@var{package-or-derivation}s, or raise an error if build logs are Allow the use of up to @var{n} CPU cores for the build. The special
missing. value @code{0} means to use as many CPU cores as available.
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
@end table @end table