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 <Para>
  14 Until recently, <Command>strip</Command> didn't work reliably on DLLs, so you
  15 should test your version with care, or make sure you have the latest
  16 binutils. Unfortunately, we don't know exactly which version of binutils
  17 cured the problem (it was supposedly fixed some years ago).
  18 </Para>
  19
  20
  21 <Sect1 id="win32-dlls-link">
  22 <Title>Linking with DLLs
  23 </Title>
  24
  25 <Para>
  26 The default on Win32 platforms is to link applications in such a way
  27 that the executables will use the Prelude and system libraries DLLs,
  28 rather than contain (large chunks of) them. This is transparent at the
  29 command-line, so
  30 </Para>
  31
  32 <Para>
  33 <Screen>
  34 sh$ cat main.hs
  35 module Main where
  36 main = putStrLn "hello, world!"
  37 sh$ ghc -o main main.hs
  38 ghc: module version changed to 1; reason: no old .hi file
  39 sh$ strip main.exe
  40 sh$ ls -l main.exe
  41 -rwxr-xr-x   1 544      everyone     4608 May  3 17:11 main.exe*
  42 sh$ ./main
  43 hello, world!
  44 sh$
  45 </Screen>
  46 </Para>
  47
  48 <Para>
  49 will give you a binary as before, but the <Filename>main.exe</Filename>
  50 generated will use the Prelude and RTS DLLs instead of linking them in
  51 statically.
  52 </Para>
  53
  54 <Para>
  55 4K for a <Literal>"hello, world"</Literal> application---not bad, huh? :-)
  56 </Para>
  57
  58 </Sect1>
  59
  60 <Sect1 id="win32-dlls-linking-static">
  61 <Title>Not linking with DLLs
  62 <IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
  63
  64 <Para>
  65 If you want to build an executable that doesn't depend on any
  66 ghc-compiled DLLs, use the <Option>-static</Option> option to link in
  67 the code statically.
  68 </Para>
  69
  70 <Para>
  71 Notice that you cannot mix code that has been compiled with
  72 <Option>-static</Option> and not, so you have to use the <Option>-static</Option>
  73 option on all the Haskell modules that make up your application.
  74 </Para>
  75
  76 </Sect1>
  77
  78 <Sect1 id="win32-dlls-create">
  79 <Title>Creating a DLL
  80 </Title>
  81
  82 <Para>
  83 <IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
  84 <IndexTerm><Primary>--mk-dll</Primary></IndexTerm>
  85 Sealing up your Haskell library inside a DLL is straightforward;
  86 compile up the object files that make up the library, and then build
  87 the DLL by issuing a command of the form:
  88 </Para>
  89
  90 <Para>
  91 <Screen>
  92 ghc --mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble
  93 </Screen>
  94 </Para>
  95
  96 <Para>
  97 By feeding the ghc compiler driver the option <Option>--mk-dll</Option>, it
  98 will build a DLL rather than produce an executable. The DLL will
  99 consist of all the object files and archives given on the command
 100 line.
 101 </Para>
 102
 103 <Para>
 104 To create a `static' DLL, i.e. one that does not depend on the GHC DLLs,
 105 use the <Option>-static</Option> when compiling up your Haskell code and
 106 building the DLL.
 107 </Para>
 108
 109 <Para>
 110 A couple of things to notice:
 111 </Para>
 112
 113 <Para>
 114
 115 <ItemizedList>
 116 <ListItem>
 117 <Para>
 118 Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need
 119 to use <Option>-package-name dll-name</Option> when compiling modules that
 120 belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell
 121 code that calls entry points in that DLL will do so incorrectly, and crash.
 122 For similar reasons, you can only compile a single module tree into a DLL,
 123 as <Function>startupHaskell</Function> needs to be able to call its
 124 initialisation function, and only takes one such argument (see <XRef
 125 LinkEnd="win32-dlls-foreign">). Hence the modules
 126 you compile into a DLL must have a common root.
 127 </Para>
 128 </ListItem>
 129
 130 <ListItem>
 131 <Para>
 132 By default, the entry points of all the object files will be exported from
 133 the DLL when using <Option>--mk-dll</Option>. Should you want to constrain
 134 this, you can specify the <Emphasis>module definition file</Emphasis> to use
 135 on the command line as follows:
 136
 137 <Screen>
 138 ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
 139 </Screen>
 140
 141 See Microsoft documentation for details, but a module definition file
 142 simply lists what entry points you want to export. Here's one that's
 143 suitable when building a Haskell COM server DLL:
 144
 145 <ProgramListing>
 146 EXPORTS
 147  DllCanUnloadNow     = DllCanUnloadNow@0
 148  DllGetClassObject   = DllGetClassObject@12
 149  DllRegisterServer   = DllRegisterServer@0
 150  DllUnregisterServer = DllUnregisterServer@0
 151 </ProgramListing>
 152 </Para>
 153 </ListItem>
 154
 155 <ListItem>
 156 <Para>
 157 In addition to creating a DLL, the <Option>--mk-dll</Option> option also
 158 creates an import library. The import library name is derived from the
 159 name of the DLL, as follows:
 160
 161 <ProgramListing>
 162 DLL: HScool.dll  ==&#62; import lib: libHScool_imp.a
 163 </ProgramListing>
 164
 165 The naming scheme may look a bit weird, but it has the purpose of allowing
 166 the co-existence of import libraries with ordinary static libraries (e.g.,
 167 <Filename>libHSfoo.a</Filename> and
 168 <Filename>libHSfoo&lowbar;imp.a</Filename>.
 169
 170 Additionally, when the compiler driver is linking in non-static mode, it
 171 will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
 172 <Option>-lHSfoo&lowbar;imp</Option>. By doing this for you, switching from
 173 non-static to static linking is simply a question of adding
 174 <Option>-static</Option> to your command line.
 175
 176 </Para>
 177 </ListItem>
 178 </ItemizedList>
 179 </Para>
 180
 181 </Sect1>
 182
 183
 184 <Sect1 id="win32-dlls-foreign">
 185 <Title>Making DLLs to be called from other languages</Title>
 186
 187 <Para>
 188
 189 If you want to package up Haskell code to be called from other languages,
 190 such as Visual Basic or C++, there are some extra things it is useful to
 191 know. The dirty details are in the <Emphasis>Foreign Function
 192 Interface</Emphasis> definition, but it can be tricky to work out how to
 193 combine this with DLL building, so here's an example:
 194
 195 </Para>
 196
 197 <ItemizedList>
 198
 199 <ListItem>
 200 <Para>
 201 Use <Literal>foreign export</Literal> declarations to export the Haskell
 202 functions you want to call from the outside. For example,
 203
 204 <ProgramListing>
 205 module Adder where
 206
 207 adder :: Int -> Int -> IO Int  -- gratuitous use of IO
 208 adder x y = return (x+y)
 209
 210 foreign export stdcall adder :: Int -> Int -> IO Int
 211 </ProgramListing>
 212 </Para>
 213 </ListItem>
 214
 215 <ListItem>
 216 <Para>
 217 Compile it up:
 218
 219 <Screen>
 220 ghc -c adder.hs -fglasgow-exts
 221 </Screen>
 222
 223 This will produce two files, adder.o and adder_stub.o
 224 </Para>
 225 </ListItem>
 226
 227 <ListItem>
 228 <Para>
 229 compile up a <Function>DllMain()</Function> that starts up the Haskell
 230 RTS---a possible implementation is:
 231
 232 <ProgramListing>
 233 #include &lt;windows.h&gt;
 234 #include &lt;Rts.h&gt;
 235
 236 EXTFUN(__init_Adder);
 237
 238 static char* args[] = { "ghcDll", NULL };
 239                        /* N.B. argv arrays must end with NULL */
 240 BOOL
 241 STDCALL
 242 DllMain
 243    ( HANDLE hModule
 244    , DWORD reason
 245    , void* reserved
 246    )
 247 {
 248   if (reason == DLL_PROCESS_ATTACH) {
 249       /* By now, the RTS DLL should have been hoisted in, but we need to start it up. */
 250       startupHaskell(1, args, __init_Adder);
 251       return TRUE;
 252   }
 253   return TRUE;
 254 }
 255 </ProgramListing>
 256
 257 Here, <Literal>Adder</Literal> is the name of the root module in the module
 258 tree (as mentioned above, there must be a single root module, and hence a
 259 single module tree in the DLL).
 260
 261 Compile this up:
 262
 263 <Screen>
 264 gcc -c dllMain.c
 265 </Screen>
 266 </Para>
 267 </ListItem>
 268
 269 <ListItem>
 270 <Para>
 271 Construct the DLL:
 272
 273 <Screen>
 274 ghc --mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
 275 </Screen>
 276
 277 </Para>
 278 </ListItem>
 279
 280 <ListItem>
 281 <Para>
 282 Start using <Function>adder</Function> from VBA---here's how I would
 283 <Constant>Declare</Constant> it:
 284
 285 <ProgramListing>
 286 Private Declare Function adder Lib "adder.dll" Alias "adder@8"
 287       (ByVal x As Long, ByVal y As Long) As Long
 288 </ProgramListing>
 289
 290 Since this Haskell DLL depends on a couple of the DLLs that come with GHC,
 291 make sure that they are in scope/visible.
 292 </Para>
 293
 294 <Para>
 295 Building statically linked DLLs is the same as in the previous section: it
 296 suffices to add <Option>-static</Option> to the commands used to compile up
 297 the Haskell source and build the DLL.
 298 </Para>
 299
 300 </ListItem>
 301
 302 </ItemizedList>
 303
 304 </Sect1>
 305
 306 </Chapter>
 307
 308 <!-- Emacs stuff:
 309      ;;; Local Variables: ***
 310      ;;; mode: sgml ***
 311      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 312      ;;; End: ***
 313  -->