ghc/docs/users_guide/win32-dlls.sgml

   1 <Chapter id="win32-dlls">
   2 <Title>Building and using Win32 DLLs
   3 </Title>
   4
   5 <Para>
   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.
  11 </Para>
  12
  13 <Sect1 id="win32-dlls-link">
  14 <Title>Linking with DLLs
  15 </Title>
  16
  17 <Para>
  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
  21 command-line, so
  22 </Para>
  23
  24 <Para>
  25
  26 <Screen>
  27 sh$ cat main.hs
  28 module Main where
  29 main = putStrLn "hello, world!"
  30 sh$ ghc -o main main.hs
  31 ghc: module version changed to 1; reason: no old .hi file
  32 sh$ strip main.exe
  33 sh$ ls -l main.exe
  34 -rwxr-xr-x   1 544      everyone     6144 May  3 17:11 main.exe*
  35 sh$ ./main
  36 hello, world!
  37 sh$
  38 </Screen>
  39
  40 </Para>
  41
  42 <Para>
  43 will give you a binary as before, but the <Filename>main.exe</Filename> generated
  44 will use the Prelude and RTS DLLs instead.
  45 </Para>
  46
  47 <Para>
  48 6K for a <Literal>"hello, world"</Literal> application - not bad, huh? :-)
  49 </Para>
  50
  51 </Sect1>
  52
  53 <Sect1 id="win32-dlls-linking-static">
  54 <Title>Not linking with DLLs
  55 <IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
  56
  57 <Para>
  58 If you want to build an executable that doesn't depend on any
  59 ghc-compiled DLLs, use the <Option>-static</Option> option to link in
  60 the code statically.
  61 </Para>
  62
  63 <Para>
  64 Notice that you cannot mix code that has been compiled with
  65 <Option>-static</Option> and not, so you have to use the <Option>-static</Option>
  66 option on all the Haskell modules that make up your application.
  67 </Para>
  68
  69 </Sect1>
  70
  71 <Sect1 id="win32-dlls-create">
  72 <Title>Creating a DLL
  73 </Title>
  74
  75 <Para>
  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:
  81 </Para>
  82
  83 <Para>
  84 <Screen>
  85 sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32
  86 </Screen>
  87 </Para>
  88
  89 <Para>
  90 By feeding the ghc compiler driver the option <Option>--mk-dll</Option>, 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
  93 line.
  94 </Para>
  95
  96 <Para>
  97 A couple of things to notice:
  98 </Para>
  99
 100 <Para>
 101
 102 <ItemizedList>
 103 <ListItem>
 104
 105 <Para>
 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:
 111
 112
 113 <ItemizedList>
 114 <ListItem>
 115
 116 <Para>
 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'.
 121
 122 </Para>
 123 </ListItem>
 124 <ListItem>
 125
 126 <Para>
 127 If a directory contains the (probably empty) file
 128 <Filename>dLL&lowbar;ifs.hi</Filename>, 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.
 131
 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 <Filename>dLL&lowbar;ifs.hi</Filename>, the import is still not
 136 being considered to be a 'DLL import'.
 137
 138 </Para>
 139 </ListItem>
 140 <ListItem>
 141
 142 <Para>
 143 If compiling with the option <Option>-static</Option>, the previous rule
 144 is disabled.
 145 </Para>
 146 </ListItem>
 147
 148 </ItemizedList>
 149
 150
 151 So, in short, after having built your Haskell DLL, make sure you
 152 create the file <Filename>dLL&lowbar;ifs.hi</Filename> 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).
 156
 157 </Para>
 158 </ListItem>
 159 <ListItem>
 160
 161 <Para>
 162 By default, the entry points of all the object files will
 163 be exported from the DLL when using <Option>--mk-dll</Option>. 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:
 166
 167
 168 <Screen>
 169 sh$ ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
 170 </Screen>
 171
 172
 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:
 176
 177
 178 <ProgramListing>
 179 EXPORTS
 180  DllCanUnloadNow     = DllCanUnloadNow@0
 181  DllGetClassObject   = DllGetClassObject@12
 182  DllRegisterServer   = DllRegisterServer@0
 183  DllUnregisterServer = DllUnregisterServer@0
 184 </ProgramListing>
 185
 186
 187 </Para>
 188 </ListItem>
 189 <ListItem>
 190
 191 <Para>
 192 In addition to creating a DLL, the <Option>--mk-dll</Option> option will also
 193 create an import library. The import library name is derived from the
 194 name of the DLL, as follows:
 195
 196 <ProgramListing>
 197 DLL: HScool.dll  ==&#62; import lib: libHScool_imp.a
 198 </ProgramListing>
 199
 200
 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., <Filename>libHSfoo.a</Filename> and <Filename>libHSfoo&lowbar;imp.a</Filename>.
 204
 205 Additionally, when the compiler driver is linking in non-static mode,
 206 it will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
 207 <Option>-lHSfoo&lowbar;imp</Option>. By doing this for you, switching from non-static
 208 to static linking is simply a question of adding <Option>-static</Option> to
 209 your command line.
 210
 211 </Para>
 212 </ListItem>
 213
 214 </ItemizedList>
 215
 216 </Para>
 217
 218 </Sect1>
 219
 220 </Chapter>