1 <Chapter id="win32-dlls">
2 <Title>Building and using Win32 DLLs
6 <IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm>
7 <IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm>
8 On Win32 platforms, the compiler is capable of both producing and using
9 dynamic link libraries (DLLs) containing ghc-compiled code. This
10 section shows you how to make use of this facility.
13 <Sect1 id="win32-dlls-link">
14 <Title>Linking with DLLs
18 The default on Win32 platforms is to link applications in such a way
19 that the executables will use the Prelude and system libraries DLLs,
20 rather than contain (large chunks of) them. This is transparent at the
29 main = putStrLn "hello, world!"
30 sh$ ghc -o main main.hs
31 ghc: module version changed to 1; reason: no old .hi file
34 -rwxr-xr-x 1 544 everyone 6144 May 3 17:11 main.exe*
43 will give you a binary as before, but the <Literal>main.exe</Literal> generated
44 will use the Prelude and RTS DLLs instead.
48 6K for a <Literal>"hello, world"</Literal> application - not bad, huh? :-)
53 <Sect1 id="win32-dlls-linking-static">
54 <Title>Not linking with DLLs
55 <IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
58 If you want to build an executable that doesn't depend on any
59 ghc-compiled DLLs, use the <Literal>-static</Literal> option to link in
64 Notice that you cannot mix code that has been compiled with
65 <Literal>-static</Literal> and not, so you have to use the <Literal>-static</Literal>
66 option on all the Haskell modules that make up your application.
71 <Sect1 id="win32-dlls-create">
76 <IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
77 <IndexTerm><Primary>--mk-dll</Primary></IndexTerm>
78 Sealing up your Haskell library inside a DLL is quite straightforward;
79 compile up the object files that make up the library, and then build
80 the DLL by issuing the following command:
85 sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32
90 By feeding the ghc compiler driver the option <Literal>--mk-dll</Literal>, it
91 will build a DLL rather than produce an executable. The DLL will
92 consist of all the object files and archives given on the command
97 A couple of things to notice:
106 When compiling the module <Literal>A</Literal>, the code emitted by the compiler
107 differs depending on whether or not the functions and data it is
108 importing from other Haskell modules correspond to symbols that are
109 packaged up in a ghc-compiled DLL. To resolve whether such imports are
110 'DLL imports' or not, the following rules are used:
117 If the compiler imports from a module that's in the same directory as
118 the one being compiled, it is assumed to not belong to a different DLL
119 (or executable) than the module being processed, so none of the
120 same-directory imports are considered 'DLL imports'.
127 If a directory contains the (probably empty) file
128 <Literal>dLL_ifs.hi</Literal>, the code corresponding to the interface
129 files found in that directory are assumed to live in a DLL
130 separate from the one being compiled.
132 Notice that the first rule takes precedence over this one, so if
133 you're compiling a module that imports from a Haskell module whose
134 interface file live in the same directory, <Emphasis>and</Emphasis> that directory
135 also contains the file <Literal>dLL_ifs.hi</Literal>, the import is still not
136 being considered to be a 'DLL import'.
143 If compiling with the option <Literal>-static</Literal>, the previous rule
151 So, in short, after having built your Haskell DLL, make sure you
152 create the file <Literal>dLL_ifs.hi</Literal> in the directory that contains
153 its interface files. If you don't, Haskell code that calls upon entry
154 points in that DLL, will do so incorrectly, and a crash will result.
155 (it is unfortunate that this isn't currently caught at compile-time).
162 By default, the entry points of all the object files will
163 be exported from the DLL when using <Literal>--mk-dll</Literal>. Should you want
164 to constrain this, you can specify the <Emphasis>module definition file</Emphasis>
165 to use on the command line as follows:
169 sh$ ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
173 See Microsoft documentation for details, but a module definition file
174 simply lists what entry points you want to export. Here's one that's
175 suitable when building a Haskell COM server DLL:
180 DllCanUnloadNow = DllCanUnloadNow@0
181 DllGetClassObject = DllGetClassObject@12
182 DllRegisterServer = DllRegisterServer@0
183 DllUnregisterServer = DllUnregisterServer@0
192 In addition to creating a DLL, the <Literal>--mk-dll</Literal> option will also
193 create an import library. The import library name is derived from the
194 name of the DLL, as follows:
197 DLL: HScool.dll ==> import lib: libHScool_imp.a
201 The naming scheme may look a bit weird, but it has the purpose of
202 allowing the co-existence of import libraries with ordinary static
203 libraries (e.g., <Literal>libHSfoo.a</Literal> and <Literal>libHSfoo_imp.a</Literal>.
205 Additionally, when the compiler driver is linking in non-static mode,
206 it will rewrite occurrence of <Literal>-lHSfoo</Literal> on the command line to
207 <Literal>-lHSfoo_imp</Literal>. By doing this for you, switching from non-static
208 to static linking is simply a question of adding <Literal>-static</Literal> to