X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fwin32-dlls.xml;h=44f589adf2a032a39687c7fef4265b8dd38e2904;hb=b2524b3960999fffdb3767900f58825903f6560f;hp=be56591abaaa21c48b28caca5a6a324390dff042;hpb=c61001a6d252f2f260c271de30d76e64e4626c4f;p=ghc-hetmet.git

diff --git a/docs/users_guide/win32-dlls.xml b/docs/users_guide/win32-dlls.xml
index be56591..44f589a 100644
--- a/docs/users_guide/win32-dlls.xml
+++ b/docs/users_guide/win32-dlls.xml
@@ -2,7 +2,7 @@
 <chapter id="win32">
 <title>Running GHC on Win32 systems</title>
 
-<sect1>
+<sect1 id="ghc-windows">
 <title>
 Starting GHC on Windows platforms</title>
 
@@ -71,11 +71,11 @@ Notice how the "%1" argument is quoted (or not).
   <para>This problem doesn't just affect GHCi, it affects any
   GHC-compiled program that wants to catch console events.  See the
   <ulink
-  url="../libraries/base/GHC-ConsoleHandler.html">GHC.ConsoleHandler</ulink>
+  url="&libraryBaseLocation;/GHC-ConsoleHandler.html">GHC.ConsoleHandler</ulink>
   module.</para>
 </sect1>
 
-<sect1>
+<sect1 id="terminal-interaction">
 <title>
 Interacting with the terminal</title>
 
@@ -102,7 +102,7 @@ You can get a close simulation by using an emacs shell buffer!
 
 </sect1>
 
-<sect1>
+<sect1 id="library-differences">
 <title>
 Differences in library behaviour </title>
 
@@ -125,7 +125,7 @@ binary mode using <literal>IOExts.hSetBinaryMode</literal>. The
 </para>
 </sect1>
 
-<sect1>
+<sect1 id="ghci-cygwin">
 <title>
 Using GHC (and other GHC-compiled executables) with cygwin</title>
 
@@ -209,15 +209,6 @@ make-sessions running under cygwin.
 </title>
 
 <para>
-<emphasis>Making Haskell libraries into DLLs doesn't work on Windows at the
-moment; however, all the machinery is
-still there. If you're interested, contact the GHC team. Note that
-building an entire Haskell application as a single DLL is still supported: it's
-	just multi-DLL Haskell programs that don't work.  The Windows
-	distribution of GHC contains static libraries only.</emphasis></para>
-
-<!--
-<para>
 <indexterm><primary>Dynamic link libraries, Win32</primary></indexterm>
 <indexterm><primary>DLLs, Win32</primary></indexterm>
 On Win32 platforms, the compiler is capable of both producing and using
@@ -226,6 +217,33 @@ section shows you how to make use of this facility.
 </para>
 
 <para>
+There are two distinct ways in which DLLs can be used:
+<itemizedlist>
+  <listitem>
+    <para>
+      You can turn each Haskell package into a DLL, so that multiple
+      Haskell executables using the same packages can share the DLL files.
+      (As opposed to linking the libraries statically, which in effect
+      creates a new copy of the RTS and all libraries for each executable
+      produced.)
+    </para>
+    <para>
+      That is the same as the dynamic linking on other platforms, and it
+      is described in <xref linkend="using-shared-libs"/>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      You can package up a complete Haskell program as a DLL, to be called
+      by some external (usually non-Haskell) program. This is usually used
+      to implement plugins and the like, and is described below.
+    </para>
+  </listitem>
+</itemizedlist>
+</para>
+
+<!--
+<para>
 Until recently, <command>strip</command> didn't work reliably on DLLs, so you
 should test your version with care, or make sure you have the latest
 binutils. Unfortunately, we don't know exactly which version of binutils
@@ -295,7 +313,7 @@ option on all the Haskell modules that make up your application.
 
 <para>
 <indexterm><primary>Creating a Win32 DLL</primary></indexterm>
-<indexterm><primary>&ndash;&ndash;mk-dll</primary></indexterm>
+<indexterm><primary>&ndash;shared</primary></indexterm>
 Sealing up your Haskell library inside a DLL is straightforward;
 compile up the object files that make up the library, and then build
 the DLL by issuing a command of the form:
@@ -303,12 +321,12 @@ the DLL by issuing a command of the form:
 
 <para>
 <screen>
-ghc &ndash;&ndash;mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble
+ghc &ndash;shared -o foo.dll bar.o baz.o wibble.a -lfooble
 </screen>
 </para>
 
 <para>
-By feeding the ghc compiler driver the option <option>&ndash;&ndash;mk-dll</option>, it
+By feeding the ghc compiler driver the option <option>&ndash;shared</option>, it
 will build a DLL rather than produce an executable. The DLL will
 consist of all the object files and archives given on the command
 line.
@@ -348,12 +366,12 @@ you compile into a DLL must have a common root.
 <listitem>
 <para>
 By default, the entry points of all the object files will be exported from
-the DLL when using <option>&ndash;&ndash;mk-dll</option>. Should you want to constrain
+the DLL when using <option>&ndash;shared</option>. Should you want to constrain
 this, you can specify the <emphasis>module definition file</emphasis> to use
 on the command line as follows:
 
 <screen>
-ghc &ndash;&ndash;mk-dll -o .... -optdll&ndash;&ndash;def -optdllMyDef.def
+ghc &ndash;shared -o .... MyDef.def
 </screen>
 
 See Microsoft documentation for details, but a module definition file
@@ -372,22 +390,22 @@ EXPORTS
 
 <listitem>
 <para>
-In addition to creating a DLL, the <option>&ndash;&ndash;mk-dll</option> option also
+In addition to creating a DLL, the <option>&ndash;shared</option> option also
 creates an import library. The import library name is derived from the
 name of the DLL, as follows:
 
 <programlisting>
-DLL: HScool.dll  ==&#62; import lib: libHScool_imp.a
+DLL: HScool.dll  ==&#62; import lib: libHScool.dll.a
 </programlisting>
 
 The naming scheme may look a bit weird, but it has the purpose of allowing
 the co-existence of import libraries with ordinary static libraries (e.g.,
 <filename>libHSfoo.a</filename> and
-<filename>libHSfoo&lowbar;imp.a</filename>.
+<filename>libHSfoo.dll.a</filename>.
 
 Additionally, when the compiler driver is linking in non-static mode, it
 will rewrite occurrence of <option>-lHSfoo</option> on the command line to
-<option>-lHSfoo&lowbar;imp</option>. By doing this for you, switching from
+<option>-lHSfoo.dll</option>. By doing this for you, switching from
 non-static to static linking is simply a question of adding
 <option>-static</option> to your command line.
 
@@ -403,121 +421,146 @@ non-static to static linking is simply a question of adding
 <title>Making DLLs to be called from other languages</title>
 
 <para>
-
-If you want to package up Haskell code to be called from other languages,
-such as Visual Basic or C++, there are some extra things it is useful to
-know. The dirty details are in the <emphasis>Foreign Function
-Interface</emphasis> definition, but it can be tricky to work out how to
-combine this with DLL building, so here's an example:
-
+  This section describes how to create DLLs to be called from other languages,
+  such as Visual Basic or C++. This is a special case of
+  <xref linkend="ffi-library" />; we'll deal with the DLL-specific issues that
+  arise below. Here's an example:
 </para>
-
-<itemizedlist>
-
-<listitem>
 <para>
-Use <literal>foreign export</literal> declarations to export the Haskell
-functions you want to call from the outside. For example,
-
+  Use foreign export declarations to export the Haskell functions you want to
+  call from the outside. For example:
+</para>
 <programlisting>
+-- Adder.hs
+{-# LANGUAGE ForeignFunctionInterface #-}
 module Adder where
 
-adder :: Int -> Int -> IO Int  &ndash;&ndash; gratuitous use of IO
+adder :: Int -> Int -> IO Int  -- gratuitous use of IO
 adder x y = return (x+y)
 
 foreign export stdcall adder :: Int -> Int -> IO Int
 </programlisting>
-</para>
-</listitem>
-
-<listitem>
 <para>
-Compile it up:
-
-<screen>
-ghc -c adder.hs -fglasgow-exts
-</screen>
-  
-This will produce two files, adder.o and adder_stub.o
+  Add some helper code that starts up and shuts down the Haskell RTS:
 </para>
-</listitem>
-
-<listitem>
-<para>
-compile up a <function>DllMain()</function> that starts up the Haskell
-RTS-&ndash;&ndash;a possible implementation is:
-
 <programlisting>
-#include &lt;windows.h&gt;
+// StartEnd.c
 #include &lt;Rts.h&gt;
 
-extern void__stginit_Adder(void);
-
-static char* args[] = { "ghcDll", NULL };
-                       /* N.B. argv arrays must end with NULL */
-BOOL
-STDCALL
-DllMain
-   ( HANDLE hModule
-   , DWORD reason
-   , void* reserved
-   )
+void HsStart()
 {
-  if (reason == DLL_PROCESS_ATTACH) {
-      /* By now, the RTS DLL should have been hoisted in, but we need to start it up. */
-      startupHaskell(1, args, __stginit_Adder);
-      return TRUE;
-  }
-  return TRUE;
-}
-</programlisting>
+   int argc = 1;
+   char* argv[] = {"ghcDll", NULL}; // argv must end with NULL
 
-Here, <literal>Adder</literal> is the name of the root module in the module
-tree (as mentioned above, there must be a single root module, and hence a
-single module tree in the DLL).
-
-Compile this up:
+   // Initialize Haskell runtime
+   char** args = argv;
+   hs_init(&amp;argc, &amp;args);
+}
 
+void HsEnd()
+{
+   hs_exit();
+}
+</programlisting>
+<para>
+  Here, <literal>Adder</literal> is the name of the root module in the module
+  tree (as mentioned above, there must be a single root module, and hence a
+  single module tree in the DLL). Compile everything up:
+</para>
 <screen>
-ghc -c dllMain.c
+ghc -c Adder.hs
+ghc -c StartEnd.c
+ghc -shared -o Adder.dll Adder.o Adder_stub.o StartEnd.o
 </screen>
+<para>
+  Now the file <filename>Adder.dll</filename> can be used from other
+  programming languages. Before calling any functions in Adder it is necessary
+  to call <literal>HsStart</literal>, and at the very end call
+  <literal>HsEnd</literal>.
 </para>
-</listitem>
-
-<listitem>
 <para>
-Construct the DLL:
-
-<screen>
-ghc &ndash;&ndash;mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
-</screen>
-
+  <emphasis>Warning:</emphasis> It may appear tempting to use
+  <literal>DllMain</literal> to call
+  <literal>hs_init</literal>/<literal>hs_exit</literal>, but this won't work
+  (particularly if you compile with <literal>-threaded</literal>). There are
+  severe restrictions on which actions can be performed during
+  <literal>DllMain</literal>, and <literal>hs_init</literal> violates these
+  restrictions, which can lead to your dll freezing during startup (see
+  <ulink url="http://hackage.haskell.org/trac/ghc/ticket/3605">bug
+  #3605</ulink>).
 </para>
-</listitem>
 
-<listitem>
-<para>
-Start using <function>adder</function> from VBA-&ndash;&ndash;here's how I would
-<constant>Declare</constant> it:
+<sect3 id="win32-dlls-vba">
+<title>Using from VBA</title>
 
+<para>
+  An example of using <filename>Adder.dll</filename> from VBA is:
+</para>
 <programlisting>
-Private Declare Function adder Lib "adder.dll" Alias "adder@8"
+Private Declare Function Adder Lib "Adder.dll" Alias "adder@8" _
       (ByVal x As Long, ByVal y As Long) As Long
-</programlisting>
 
-Since this Haskell DLL depends on a couple of the DLLs that come with GHC,
-make sure that they are in scope/visible.
+Private Declare Sub HsStart Lib "Adder.dll" ()
+Private Declare Sub HsEnd Lib "Adder.dll" ()
+
+Private Sub Document_Close()
+HsEnd
+End Sub
+
+Private Sub Document_Open()
+HsStart
+End Sub
+
+Public Sub Test()
+MsgBox "12 + 5 = " &amp; Adder(12, 5)
+End Sub
+</programlisting>
+<para>
+  This example uses the
+  <literal>Document_Open</literal>/<literal>Close</literal> functions of
+  Microsoft Word, but provided <literal>HsStart</literal> is called before the
+  first function, and <literal>HsEnd</literal> after the last, then it will
+  work fine.
 </para>
+</sect3>
+
+<sect3 id="win32-dlls-c++">
+<title>Using from C++</title>
 
 <para>
-Building statically linked DLLs is the same as in the previous section: it
-suffices to add <option>-static</option> to the commands used to compile up
-the Haskell source and build the DLL.
+  An example of using <filename>Adder.dll</filename> from C++ is:
 </para>
 
-</listitem>
+<programlisting>
+// Tester.cpp
+#include "HsFFI.h"
+#include "Adder_stub.h"
+#include &lt;stdio.h&gt;
+
+extern "C" {
+    void HsStart();
+    void HsEnd();
+}
 
-</itemizedlist>
+int main()
+{
+    HsStart();
+    // can now safely call functions from the DLL
+    printf("12 + 5 = %i\n", adder(12,5))    ;
+    HsEnd();
+    return 0;
+}
+</programlisting>
+<para>
+  This can be compiled and run with:
+</para>
+<screen>
+$ ghc -o tester Tester.cpp Adder.dll.a
+$ tester
+12 + 5 = 17
+</screen>
+
+</sect3>
 
 </sect2>
 
@@ -526,7 +569,6 @@ the Haskell source and build the DLL.
 
 <!-- Emacs stuff:
      ;;; Local Variables: ***
-     ;;; mode: xml ***
      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
      ;;; End: ***
  -->