From 5c2220aa9aac0fefcba5abbfa3059a6ef138655f Mon Sep 17 00:00:00 2001
From: Stephen Blackheath <oversensitive.pastors.stephen@blacksapphire.com>
Date: Thu, 1 Oct 2009 05:16:37 +0000
Subject: [PATCH] Document the new -dylib-install-name option in the user's
 guide.

---
 docs/users_guide/flags.xml       |    9 +++++++++
 docs/users_guide/phases.xml      |   18 ++++++++++++++++++
 docs/users_guide/shared_libs.xml |   13 +++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index cd6b5b3..5724850 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1866,6 +1866,15 @@ phase <replaceable>n</replaceable></entry>
 	      <entry>dynamic</entry>
 	      <entry>-</entry>
 	    </row>
+	    <row>
+	      <entry><option>-dylib-install-name</option> <replaceable>path</replaceable></entry>
+	      <entry>Set the install name (via <literal>-install_name</literal> passed to Apple's
+              linker), specifying the full install path of the library file. Any libraries
+              or executables that link with it later will pick up that path as their
+              runtime search location for it. (Darwin/MacOS X only)</entry>
+	      <entry>dynamic</entry>
+	      <entry>-</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 22416c7..2b88718 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -1072,6 +1072,24 @@ $ cat foo.hspp</screen>
             library entirely.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-dylib-install-name <replaceable>path</replaceable></option>
+          <indexterm><primary><option>-dylib-install-name</option></primary>
+          </indexterm>
+        </term>
+        <listitem>
+          <para>On Darwin/MacOS X, dynamic libraries are stamped at build time with an
+              "install name", which is the ultimate install path of the library file.
+              Any libraries or executables that subsequently link against it will pick
+              up that path as their runtime search location for it. By default, ghc sets
+              the install name to the location where the library is built. This option
+              allows you to override it with the specified file path. (It passes
+              <literal>-install_name</literal> to Apple's linker.) Ignored on other
+              platforms.</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </sect2>
 
diff --git a/docs/users_guide/shared_libs.xml b/docs/users_guide/shared_libs.xml
index 00f6f67..ea5500b 100644
--- a/docs/users_guide/shared_libs.xml
+++ b/docs/users_guide/shared_libs.xml
@@ -242,6 +242,19 @@ ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
       Similarly it would be possible to use a subdirectory relative to the
       executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>.
     </para>
+    <para>
+      The standard assumption on Darwin/MacOS X is that dynamic libraries will
+      be stamped at build time with an "install name", which is the full
+      ultimate install path of the library file. Any libraries or executables
+      that subsequently link against it (even if it hasn't been installed yet)
+      will pick up that path as their runtime search location for it. When
+      compiling with ghc directly, the install name is set by default to the
+      location where it is built. You can override this with the
+      <literal>-dylib-install-name</literal> option (which passes
+      <literal>-install_name</literal> to the Apple linker). Cabal does this
+      for you. It automatically sets the install name for dynamic libraries to
+      the absolute path of the ultimate install location.
+    </para>
   </sect2>
 
 </sect1>
-- 
1.7.10.4