From cdd45bc0aef8b6cb60d351a8fded18700804e8db Mon Sep 17 00:00:00 2001
From: Maxime Devos <maximedevos@telenet.be>
Date: Mon, 19 Apr 2021 19:54:53 +0200
Subject: [PATCH 7/7] doc: Document 'wrap-program'.

* doc/guix.texi (Wrapping Code)[wrap-program]: Copy docstring from
  guix/build/utils.scm and use Texinfo markup.
---
 doc/guix.texi | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index a2ff13fe0f..6235ae9bf7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8703,7 +8703,42 @@ Here is an example using the @code{which} procedure in a build phase:
 This section documents procedures that create ‘wrappers’ around existing
 binaries, that e.g. set environment variables required during execution.
 
-@c TODO document wrap-program
+@deffn {Scheme Procedure} wrap-program @var{prog} @var{inputs} @var{vars}
+Make a wrapper for @var{prog}.  @var{vars} should look like this:
+
+@lisp
+  '(VARIABLE DELIMITER POSITION LIST-OF-DIRECTORIES)
+@end lisp
+
+where @var{delimiter} is optional.  @samp{:} will be used if @var{delimiter}
+is not given.
+
+For example, this command:
+
+@lisp
+  (wrap-program "foo"
+                '("PATH" ":" = ("/gnu/.../bar/bin"))
+                '("CERT_PATH" suffix ("/gnu/.../baz/certs"
+                                        "/qux/certs")))
+@end lisp
+
+will copy @file{foo} to @file{.foo-real} and create the file @file{foo} with
+the following contents:
+
+@example
+  #!location/of/bin/bash
+  export PATH="/gnu/.../bar/bin"
+  export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
+  exec -a $0 location/of/.foo-real "$@@"
+@end example
+
+This is useful for scripts that expect particular programs to be in @env{PATH},
+for programs that expect particular shared libraries to be in
+@env{LD_LIBRARY_PATH}, or modules in @env{GUILE_LOAD_PATH}, etc.
+
+If @var{prog} has previously been wrapped by @code{wrap-program} the wrapper is
+extended with definitions for @var{vars}.
+@end deffn
 
 @deffn {Scheme Procedure} wrap-script @var{prog} @var{inputs} @var{vars}
 Wrap the script @var{prog} such that @var{vars} are set first.  The format
-- 
2.31.1