derivations: Add support for recursive fixed-output derivations.

* guix/derivations.scm (<derivation-output>): Add 'recursive?' field.
  Adjust 'make-derivation-output' callers.
  (%read-derivation) <fixed-output>: When HASH-ALGO starts with 'r:',
  set the 'recursive?' field and drop 'r:' from the hash algo name.
  (write-derivation)[write-output]: Write the algo as 'r:HASH-ALGO' when
  the RECURSIVE? field is set.
  (derivation-hash) <fixed-output>: Prepend "r:" when RECURSIVE? is set.
  (fixed-output-path): New procedure.
  (derivation): Add #:recursive? parameter.  Use 'fixed-output-path' to
  compute the output file name of a fixed output derivation.
  (build-expression->derivation): Add #:recursive? parameter.  Pass it
  to 'derivation'.
* tests/derivations.scm ("fixed-output derivation, recursive",
  "build-expression->derivation produces recursive fixed-output",
  "build-expression->derivation uses recursive fixed-output"): New
  tests.
* doc/guix.texi (Derivations): Document #:recursive? for 'derivation'.
  Add #:recursive? for 'build-expression->derivation'.

1 files changed, 6 insertions, 3 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index ce011959ad..b2733fbec9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1478,7 +1478,7 @@ a derivation is the @code{derivation} procedure:
 
 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
   @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
-  [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] @
+  [#:recursive? #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] @
   [#:system (%current-system)] [#:references-graphs #f] @
   [#:local-build? #f]
 Build a derivation with the given arguments, and return the resulting
@@ -1486,7 +1486,10 @@ Build a derivation with the given arguments, and return the resulting
 
 When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
 @dfn{fixed-output derivation} is created---i.e., one whose result is
-known in advance, such as a file download.
+known in advance, such as a file download.  If, in addition,
+@var{recursive?} is true, then that fixed output may be an executable
+file or a directory and @var{hash} must be the hash of an archive
+containing this output.
 
 When @var{references-graphs} is true, it must be a list of file
 name/store path pairs.  In that case, the reference graph of each store
@@ -1526,7 +1529,7 @@ the caller to directly pass a Guile expression as the build script:
        @var{name} @var{exp} @
        [#:system (%current-system)] [#:inputs '()] @
        [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
-       [#:env-vars '()] [#:modules '()] @
+       [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
        [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
 Return a derivation that executes Scheme expression @var{exp} as a
 builder for derivation @var{name}.  @var{inputs} must be a list of