From 6ec7f45fd25a978c9f955f0c07790e1e42949d4b Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Thu, 31 May 2001 09:37:23 +0000
Subject: [PATCH] [project @ 2001-05-31 09:37:23 by simonmar] Clarify the
 situation with GHCi object files, and add instructions for
 building one from a .a file.

---
 ghc/docs/users_guide/packages.sgml |   49 ++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index 9ba677d..1ef87cb 100644
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -80,6 +80,19 @@
 	  tell the compiler when it should make an inter-DLL call
 	  rather than an intra-DLL call (inter-DLL calls require an
 	  extra indirection).</para>
+
+	  <para>Versions of the Haskell libraries for use with GHCi
+	  may also be included: GHCi cannot load <literal>.a</literal>
+	  files directly, instead it will look for an object file
+	  called <filename>HSfoo.o</filename> (the object suffix
+	  varies between platforms, as usual) and load that.  An
+	  object file can be built from a <literal>.a</literal>
+	  archive as follows (using GNU <command>ld</command> on
+	  Unix):</para>
+
+<screen>
+ld -r --whole-archive -o HSfoo.o libHSfoo.a
+</screen>
 	</listitem>
 
 	<listitem>
@@ -266,6 +279,42 @@
 	    package, with the <literal>.a</literal> or
 	    <literal>.dll</literal> suffix omitted.  On Unix, the
 	    <literal>lib</literal> prefix is also omitted.</para>
+
+	    <para>For use with GHCi, each library should have an
+	    object file too.  The name of the object file does
+	    <emphasis>not</emphasis> have a <literal>lib</literal>
+	    prefix, and has the normal object suffix for your
+	    platform.</para>
+
+	    <para>For example, if we specify a Haskell library as
+	    <filename>HSfoo</filename> in the package spec, then the
+	    various flavours of library that GHC actually uses will be
+	    called:</para>
+	    <variablelist>
+	      <varlistentry>
+		<term><filename>libHSfoo.a</filename></term>
+		<listitem>
+		  <para>The name of the library on Unix
+		  systems.</para>
+		</listitem>
+	      </varlistentry>
+	      <varlistentry>
+		<term><filename>HSfoo.dll</filename></term>
+		<listitem>
+		  <para>The name of the dynamic library on Windows
+		  systems.</para>
+		</listitem>
+	      </varlistentry>
+	      <varlistentry>
+		<term><filename>HSfoo.o</filename></term>
+		<term><filename>HSfoo.obj</filename></term>
+		<listitem>
+		  <para>The object version of the library used by
+		  GHCi.</para>
+		</listitem>
+	      </varlistentry>
+	    </variablelist>
+
 	  </listitem>
 	</varlistentry>
 
-- 
1.7.10.4