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>
-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>
-
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 don't, Haskell code that calls entry points in that
-DLL will do so incorrectly, and a crash will result.
-
+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>
-<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:
+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
DllRegisterServer = DllRegisterServer@0
DllUnregisterServer = DllUnregisterServer@0
</ProgramListing>
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+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>
+
+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>
+</ItemizedList>
+</Para>
+
+</Sect1>
+
+
+<Sect1 id="win32-dlls-foreign">
+<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:
+
+</Para>
+
+<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
+
+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>
-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:
+Compile it up:
+
+<Screen>
+ghc -c adder.hs -fglasgow-exts
+</Screen>
+
+This will produce two files, adder.o and adder_stub.o
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+compile up a <Function>DllMain()</Function> that starts up the Haskell
+RTS---a possible implementation is:
<ProgramListing>
-DLL: HScool.dll ==> import lib: libHScool_imp.a
+#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>
-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>.
+<ListItem>
+<Para>
+Construct the DLL:
-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.
+<Screen>
+ghc --mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
+</Screen>
</Para>
</ListItem>
-</ItemizedList>
+<ListItem>
+<Para>
+Start using <Function>adder</Function> from VBA---here's how I would
+<Constant>Declare</Constant> it:
+<ProgramListing>
+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>
+
+<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>
+
</Sect1>
</Chapter>
projects / ghc-hetmet.git / blobdiff