stdenv: document makeWrapper

Add function documentation to `makeWrapper`.
Also add user documentation to the nixpkgs manual.

2 files changed, 64 insertions, 0 deletions

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 2e88d6b4154..b05b7cd2b3b 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -1091,7 +1091,35 @@ functions.</para>
 
 <variablelist>
 
+
+  <varlistentry xml:id='fun-makeWrapper'>
+    <term><function>makeWrapper</function>
+    <replaceable>executable</replaceable>
+    <replaceable>wrapperfile</replaceable>
+    <replaceable>args</replaceable></term>
+    <listitem><para>Constructs a wrapper for a program with various
+    possible arguments. For example:
+
+<programlisting>
+# adds `FOOBAR=baz` to `$out/bin/foo`’s environment
+makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz
+
+# prefixes the binary paths of `hello` and `git`
+# Be advised that paths often should be patched in directly
+# (via string replacements or in `configurePhase`).
+makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]}
+</programlisting>
+
+    There’s many more kinds of arguments, they are documented in
+    <literal>nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh</literal>.</para>
+
+    <para><literal>wrapProgram</literal> is a convenience function you probably
+    want to use most of the time.</para>
+
+    </listitem>
+  </varlistentry>
   
+
   <varlistentry xml:id='fun-substitute'>
     <term><function>substitute</function>
     <replaceable>infile</replaceable>
@@ -1250,6 +1278,22 @@ someVar=$(stripHash $name; echo $strippedName)
 
     </para></listitem>
   </varlistentry>
+  
+
+  <varlistentry xml:id='fun-wrapProgram'>
+    <term><function>wrapProgram</function>
+    <replaceable>executable</replaceable>
+    <replaceable>makeWrapperArgs</replaceable></term>
+    <listitem><para>Convenience function for <literal>makeWrapper</literal>
+    that automatically creates a sane wrapper file
+
+    It takes all the same arguments as <literal>makeWrapper</literal>,
+    except for <literal>--argv0</literal>.</para>
+
+    <para>It cannot be applied multiple times, since it will overwrite the wrapper
+    file.</para>
+    </listitem>
+  </varlistentry>
 
   
 </variablelist>
diff --git a/pkgs/build-support/setup-hooks/make-wrapper.sh b/pkgs/build-support/setup-hooks/make-wrapper.sh
index d922db5ccf5..086875976d3 100644
--- a/pkgs/build-support/setup-hooks/make-wrapper.sh
+++ b/pkgs/build-support/setup-hooks/make-wrapper.sh
@@ -1,3 +1,23 @@
+# construct an executable file that wraps the actual executable
+# makeWrapper EXECUTABLE ARGS
+
+# ARGS:
+# --argv0 NAME      : set name of executed process to NAME
+#                     (otherwise it’s called …-wrapped)
+# --set   VAR VAL   : add VAR with value VAL to the executable’s environment
+# --unset VAR       : remove VAR from the environment
+# --run   COMMAND   : run command before the executable
+#                     The command can push extra flags to a magic list variable
+#                     extraFlagsArray, which are then added to the invocation
+#                     of the executable
+# --add-flags FLAGS : add FLAGS to invocation of executable
+
+# --prefix          ENV SEP VAL   : suffix/prefix ENV with VAL, separated by SEP
+# --suffix
+# --suffix-each     ENV SEP VALS  : like --suffix, but VALS is a list
+# --prefix-contents ENV SEP FILES : like --suffix-each, but contents of FILES
+#                                   are read first and used as VALS
+# --suffix-contents
 makeWrapper() {
     local original=$1
     local wrapper=$2