guix build: Add '--check'.

* guix/derivations.scm (build-derivations): Add optional 'mode'
parameter.
* guix/scripts/build.scm (%default-options): Add 'build-mode'.
(show-help, %options): Add '--check'.
(guix-build): Honor 'build-mode' key of OPTS.  Pass it to
'show-what-to-build' and 'build-derivations'.
* doc/guix.texi (Invoking guix build): Document it.
(Substitutes): Mention it.

1 files changed, 17 insertions, 1 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 390e7949c0..97fddd025e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1638,7 +1638,10 @@ a diverse set of independent package builds, we can strengthen the
 integrity of our systems.  The @command{guix challenge} command aims to
 help users assess substitute servers, and to assist developers in
 finding out about non-deterministic package builds (@pxref{Invoking guix
-challenge}).
+challenge}).  Similarly, the @option{--check} option of @command{guix
+build} allows users to check whether previously-installed substitutes
+are genuine by rebuilding them locally (@pxref{build-check,
+@command{guix build --check}}).
 
 In the future, we want Guix to have support to publish and retrieve
 binaries to/from other users, in a peer-to-peer fashion.  If you would
@@ -3786,6 +3789,19 @@ $ git clone git://git.sv.gnu.org/guix.git
 $ guix build guix --with-source=./guix
 @end example
 
+@anchor{build-check}
+@item --check
+@cindex determinism, checking
+@cindex reproducibility, checking
+Rebuild @var{package-or-derivation}, which are already available in the
+store, and raise an error if the build results are not bit-for-bit
+identical.
+
+This mechanism allows you to check whether previously-installed
+substitutes are genuine (@pxref{Substitutes}), or whether a package's
+build result is deterministic.  @xref{Invoking guix challenge}, for more
+background information and tools.
+
 @item --no-grafts
 Do not ``graft'' packages.  In practice, this means that package updates
 available as grafts are not applied.  @xref{Security Updates}, for more