01/01: Revert "doc: Drop documentation of deprecated procedures."

[Andreas Enge]

andreas pushed a commit to branch master
in repository guix.

commit f2fadbc1ff1d8484589d22e0ef0d3b7a19ab6e67
Author: Andreas Enge <address@hidden>
Date:   Sun Feb 21 20:01:56 2016 +0100

    Revert "doc: Drop documentation of deprecated procedures."
    
    This reverts commit f5c6e77a7f42e133df8c97d3b4798a11e6d58d06.
---
 doc/guix.texi |   53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 53 insertions(+), 0 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index b991cc1..51b0652 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3022,6 +3022,59 @@ best course of action for that is to write the build 
code as a
 ``G-expression'', and to pass it to @code{gexp->derivation}.  For more
 information, @pxref{G-Expressions}.
 
+Once upon a time, @code{gexp->derivation} did not exist and constructing
+derivations with build code written in Scheme was achieved with
address@hidden>derivation}, documented below.  This procedure
+is now deprecated in favor of the much nicer @code{gexp->derivation}.
+
address@hidden {Scheme Procedure} build-expression->derivation @var{store} @
+       @var{name} @var{exp} @
+       [#:system (%current-system)] [#:inputs '()] @
+       [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+       [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+       [#:references-graphs #f] [#:allowed-references #f] @
+       [#:local-build? #f] [#:substitutable? #t] [#: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
address@hidden(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
address@hidden"out"} is assumed.  @var{modules} is a list of names of Guile
+modules from the current search path to be copied in the store,
+compiled, and made available in the load path during the execution of
address@hidden, @code{((guix build utils) (guix build
+gnu-build-system))}.
+
address@hidden is evaluated in an environment where @code{%outputs} is bound
+to a list of output/path pairs, and where @code{%build-inputs} is bound
+to a list of string/output-path pairs made from @var{inputs}.
+Optionally, @var{env-vars} is a list of string pairs specifying the name
+and value of environment variables visible to the builder.  The builder
+terminates by passing the result of @var{exp} to @code{exit}; thus, when
address@hidden returns @code{#f}, the build is considered to have failed.
+
address@hidden is built using @var{guile-for-build} (a derivation).  When
address@hidden is omitted or is @code{#f}, the value of the
address@hidden fluid is used instead.
+
+See the @code{derivation} procedure for the meaning of
address@hidden, @var{allowed-references}, @var{local-build?},
+and @var{substitutable?}.
address@hidden deffn
+
address@hidden
+Here's an example of a single-output derivation that creates a directory
+containing one file:
+
address@hidden
+(let ((builder '(let ((out (assoc-ref %outputs "out")))
+                  (mkdir out)    ; create /gnu/store/@dots{}-goo
+                  (call-with-output-file (string-append out "/test")
+                    (lambda (p)
+                      (display '(hello guix) p))))))
+  (build-expression->derivation store "goo" builder))
+
address@hidden #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
address@hidden lisp
+
 
 @node The Store Monad
 @section The Store Monad