section shows you how to make use of this facility.
</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
+cured the problem (it was supposedly fixed some years ago).
+</Para>
+
+
<Sect1 id="win32-dlls-link">
<Title>Linking with DLLs
</Title>
</Para>
<Para>
-
<Screen>
sh$ cat main.hs
module Main where
ghc: module version changed to 1; reason: no old .hi file
sh$ strip main.exe
sh$ ls -l main.exe
--rwxr-xr-x 1 544 everyone 6144 May 3 17:11 main.exe*
+-rwxr-xr-x 1 544 everyone 4608 May 3 17:11 main.exe*
sh$ ./main
hello, world!
sh$
</Screen>
-
</Para>
<Para>
-will give you a binary as before, but the <Filename>main.exe</Filename> generated
-will use the Prelude and RTS DLLs instead.
+will give you a binary as before, but the <Filename>main.exe</Filename>
+generated will use the Prelude and RTS DLLs instead of linking them in
+statically.
</Para>
<Para>
-6K for a <Literal>"hello, world"</Literal> application - not bad, huh? :-)
+4K for a <Literal>"hello, world"</Literal> application---not bad, huh? :-)
</Para>
</Sect1>
</Title>
<Para>
+<emphasis>Making libraries into DLLs doesn't work on Windows at the
+moment (and is no longer supported); however, all the machinery is
+still there. If you're interested, contact the GHC team. Note that
+building an entire Haskell application as a DLL is still supported
+(it's just inter-DLL Haskell calls that don't work).</emphasis>
<IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
<IndexTerm><Primary>--mk-dll</Primary></IndexTerm>
-Sealing up your Haskell library inside a DLL is quite straightforward;
+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 the following command:
+the DLL by issuing a command of the form:
</Para>
<Para>
<Screen>
-sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32
+ghc --mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble
</Screen>
</Para>
</Para>
<Para>
+To create a `static' DLL, i.e. one that does not depend on the GHC DLLs,
+use the <Option>-static</Option> when compiling up your Haskell code and
+building the DLL.
+</Para>
+
+<Para>
A couple of things to notice:
</Para>
<ItemizedList>
<ListItem>
-
<Para>
-When compiling the module <Literal>A</Literal>, the code emitted by the compiler
-differs depending on whether or not the functions and data it is
-importing from other Haskell modules correspond to symbols that are
-packaged up in a ghc-compiled DLL. To resolve whether such imports are
-'DLL imports' or not, the following rules are used:
-
+Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need
+to use <Option>-package-name dll-name</Option> when compiling modules that
+belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell
+code that calls entry points in that DLL will do so incorrectly, and crash.
+For similar reasons, you can only compile a single module tree into a DLL,
+as <Function>startupHaskell</Function> needs to be able to call its
+initialisation function, and only takes one such argument (see <XRef
+LinkEnd="win32-dlls-foreign">). Hence the modules
+you compile into a DLL must have a common root.
+</Para>
+</ListItem>
-<ItemizedList>
<ListItem>
-
<Para>
-If the compiler imports from a module that's in the same directory as
-the one being compiled, it is assumed to not belong to a different DLL
-(or executable) than the module being processed, so none of the
-same-directory imports are considered 'DLL imports'.
+By default, the entry points of all the object files will be exported from
+the DLL when using <Option>--mk-dll</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 --mk-dll -o .... -optdll--def -optdllMyDef.def
+</Screen>
+See Microsoft documentation for details, but a module definition file
+simply lists what entry points you want to export. Here's one that's
+suitable when building a Haskell COM server DLL:
+
+<ProgramListing>
+EXPORTS
+ DllCanUnloadNow = DllCanUnloadNow@0
+ DllGetClassObject = DllGetClassObject@12
+ DllRegisterServer = DllRegisterServer@0
+ DllUnregisterServer = DllUnregisterServer@0
+</ProgramListing>
</Para>
</ListItem>
-<ListItem>
+<ListItem>
<Para>
-If a directory contains the (probably empty) file
-<Filename>dLL_ifs.hi</Filename>, the code corresponding to the interface
-files found in that directory are assumed to live in a DLL
-separate from the one being compiled.
+In addition to creating a DLL, the <Option>--mk-dll</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 ==> import lib: libHScool_imp.a
+</ProgramListing>
-Notice that the first rule takes precedence over this one, so if
-you're compiling a module that imports from a Haskell module whose
-interface file live in the same directory, <Emphasis>and</Emphasis> that directory
-also contains the file <Filename>dLL_ifs.hi</Filename>, the import is still not
-being considered to be a 'DLL import'.
+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_imp.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_imp</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.
</Para>
</ListItem>
-<ListItem>
+</ItemizedList>
+</Para>
+
+</Sect1>
+
+
+<Sect1 id="win32-dlls-foreign">
+<Title>Making DLLs to be called from other languages</Title>
<Para>
-If compiling with the option <Option>-static</Option>, the previous rule
-is disabled.
+
+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:
+
</Para>
-</ListItem>
-</ItemizedList>
+<ItemizedList>
+
+<ListItem>
+<Para>
+Use <Literal>foreign export</Literal> declarations to export the Haskell
+functions you want to call from the outside. For example,
+<ProgramListing>
+module Adder where
-So, in short, after having built your Haskell DLL, make sure you
-create the file <Filename>dLL_ifs.hi</Filename> in the directory that contains
-its interface files. If you don't, Haskell code that calls upon entry
-points in that DLL, will do so incorrectly, and a crash will result.
-(it is unfortunate that this isn't currently caught at compile-time).
+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>
+<ListItem>
<Para>
-By default, the entry points of all the object files will
-be exported from the DLL when using <Option>--mk-dll</Option>. Should you want
-to constrain this, you can specify the <Emphasis>module definition file</Emphasis>
-to use on the command line as follows:
-
+Compile it up:
<Screen>
-sh$ ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
+ghc -c adder.hs -fglasgow-exts
</Screen>
+
+This will produce two files, adder.o and adder_stub.o
+</Para>
+</ListItem>
-
-See Microsoft documentation for details, but a module definition file
-simply lists what entry points you want to export. Here's one that's
-suitable when building a Haskell COM server DLL:
-
+<ListItem>
+<Para>
+compile up a <Function>DllMain()</Function> that starts up the Haskell
+RTS---a possible implementation is:
<ProgramListing>
-EXPORTS
- DllCanUnloadNow = DllCanUnloadNow@0
- DllGetClassObject = DllGetClassObject@12
- DllRegisterServer = DllRegisterServer@0
- DllUnregisterServer = DllUnregisterServer@0
+#include <windows.h>
+#include <Rts.h>
+
+EXTFUN(__stginit_Adder);
+
+static char* args[] = { "ghcDll", NULL };
+ /* N.B. argv arrays must end with NULL */
+BOOL
+STDCALL
+DllMain
+ ( HANDLE hModule
+ , DWORD reason
+ , void* reserved
+ )
+{
+ 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>
+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:
+<Screen>
+gcc -c dllMain.c
+</Screen>
</Para>
</ListItem>
+
<ListItem>
+<Para>
+Construct the DLL:
+
+<Screen>
+ghc --mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
+</Screen>
+
+</Para>
+</ListItem>
+<ListItem>
<Para>
-In addition to creating a DLL, the <Option>--mk-dll</Option> option will also
-create an import library. The import library name is derived from the
-name of the DLL, as follows:
+Start using <Function>adder</Function> from VBA---here's how I would
+<Constant>Declare</Constant> it:
<ProgramListing>
-DLL: HScool.dll ==> import lib: libHScool_imp.a
+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.
+</Para>
-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_imp.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_imp</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.
-
+<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.
</Para>
+
</ListItem>
</ItemizedList>
-</Para>
-
</Sect1>
</Chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff