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.

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

guix/derivations.scm

@@ -972,13 +972,16 @@ recursively."
 ;;; Store compatibility layer.
 ;;;
 
-(define (build-derivations store derivations)
+(define* (build-derivations store derivations
-  "Build DERIVATIONS, a list of <derivation> objects or .drv file names."
+                            #:optional (mode (build-mode normal)))
+  "Build DERIVATIONS, a list of <derivation> objects or .drv file names, using
+the specified MODE."
   (build-things store (map (match-lambda
                             ((? string? file) file)
                             ((and drv ($ <derivation>))
                              (derivation-file-name drv)))
-                           derivations)))
+                           derivations)
+                mode))
 
 
 ;;;

guix/scripts/build.scm

@@ -285,6 +285,7 @@ options handled by 'set-build-options-from-command-line', and listed in
 (define %default-options
   ;; Alist of default option values.
   `((system . ,(%current-system))
+    (build-mode . ,(build-mode normal))
     (graft? . #t)
     (substitutes? . #t)
     (build-hook? . #t)
@@ -316,6 +317,8 @@ Build the given PACKAGE-OR-DERIVATION and return their output paths.\n"))
       --no-grafts        do not graft packages"))
   (display (_ "
   -d, --derivations      return the derivation paths of the given packages"))
+  (display (_ "
+      --check            rebuild items to check for non-determinism issues"))
   (display (_ "
   -r, --root=FILE        make FILE a symlink to the result, and register it
                          as a garbage collector root"))
@@ -356,6 +359,12 @@ Build the given PACKAGE-OR-DERIVATION and return their output paths.\n"))
                       (leave (_ "invalid argument: '~a' option argument: ~a, ~
 must be one of 'package', 'all', or 'transitive'~%")
                              name arg)))))
+        (option '("check") #f #f
+                (lambda (opt name arg result . rest)
+                  (apply values
+                         (alist-cons 'build-mode (build-mode check)
+                                     result)
+                         rest)))
          (option '(#\s "system") #t #f
                  (lambda (opt name arg result)
                    (alist-cons 'system arg
@@ -540,6 +549,7 @@ needed."
       (let* ((opts  (parse-command-line args %options
                                         (list %default-options)))
              (store (open-connection))
+             (mode  (assoc-ref opts 'build-mode))
              (drv   (options->derivations store opts))
              (urls  (map (cut string-append <> "/log")
                          (if (assoc-ref opts 'substitutes?)
@@ -562,7 +572,8 @@ needed."
         (unless (assoc-ref opts 'log-file?)
           (show-what-to-build store drv
                               #:use-substitutes? (assoc-ref opts 'substitutes?)
-                              #:dry-run? (assoc-ref opts 'dry-run?)))
+                              #:dry-run? (assoc-ref opts 'dry-run?)
+                              #:mode mode))
 
         (cond ((assoc-ref opts 'log-file?)
                (for-each (cut show-build-log store <> urls)
@@ -575,7 +586,7 @@ needed."
                          (map (compose list derivation-file-name) drv)
                          roots))
               ((not (assoc-ref opts 'dry-run?))
-               (and (build-derivations store drv)
+               (and (build-derivations store drv mode)
                     (for-each show-derivation-outputs drv)
                     (for-each (cut register-root store <> <>)
                               (map (lambda (drv)