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 will use the Prelude and RTS DLLs instead.
  44 </Para>
  45
  46 <Para>
  47 6K for a <Literal>"hello, world"</Literal> application---not bad, huh? :-)
  48 </Para>
  49
  50 </Sect1>
  51
  52 <Sect1 id="win32-dlls-linking-static">
  53 <Title>Not linking with DLLs
  54 <IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
  55
  56 <Para>
  57 If you want to build an executable that doesn't depend on any
  58 ghc-compiled DLLs, use the <Option>-static</Option> option to link in
  59 the code statically.
  60 </Para>
  61
  62 <Para>
  63 Notice that you cannot mix code that has been compiled with
  64 <Option>-static</Option> and not, so you have to use the <Option>-static</Option>
  65 option on all the Haskell modules that make up your application.
  66 </Para>
  67
  68 </Sect1>
  69
  70 <Sect1 id="win32-dlls-create">
  71 <Title>Creating a DLL
  72 </Title>
  73
  74 <Para>
  75 <IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
  76 <IndexTerm><Primary>--mk-dll</Primary></IndexTerm>
  77 Sealing up your Haskell library inside a DLL is quite straightforward;
  78 compile up the object files that make up the library, and then build
  79 the DLL by issuing the following command:
  80 </Para>
  81
  82 <Para>
  83 <Screen>
  84 ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32
  85 </Screen>
  86 </Para>
  87
  88 <Para>
  89 By feeding the ghc compiler driver the option <Option>--mk-dll</Option>, it
  90 will build a DLL rather than produce an executable. The DLL will
  91 consist of all the object files and archives given on the command
  92 line.
  93 </Para>
  94
  95 <Para>
  96 A couple of things to notice:
  97 </Para>
  98
  99 <Para>
 100
 101 <ItemizedList>
 102 <ListItem>
 103
 104 <Para>
 105
 106 Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need
 107 to use <Option>-package-name dll-name</Option> when compiling modules that
 108 belong to a DLL. If you don't, Haskell code that calls entry points in that
 109 DLL will do so incorrectly, and a crash will result.
 110
 111 </Para>
 112 </ListItem>
 113 <ListItem>
 114
 115 <Para>
 116 By default, the entry points of all the object files will
 117 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:
 118
 119 <Screen>
 120 ghc --mk-dll -o .... -optdll--def -optdllMyDef.def
 121 </Screen>
 122
 123 See Microsoft documentation for details, but a module definition file
 124 simply lists what entry points you want to export. Here's one that's
 125 suitable when building a Haskell COM server DLL:
 126
 127 <ProgramListing>
 128 EXPORTS
 129  DllCanUnloadNow     = DllCanUnloadNow@0
 130  DllGetClassObject   = DllGetClassObject@12
 131  DllRegisterServer   = DllRegisterServer@0
 132  DllUnregisterServer = DllUnregisterServer@0
 133 </ProgramListing>
 134
 135
 136 </Para>
 137 </ListItem>
 138 <ListItem>
 139
 140 <Para>
 141 In addition to creating a DLL, the <Option>--mk-dll</Option> option will also
 142 create an import library. The import library name is derived from the
 143 name of the DLL, as follows:
 144
 145 <ProgramListing>
 146 DLL: HScool.dll  ==&#62; import lib: libHScool_imp.a
 147 </ProgramListing>
 148
 149
 150 The naming scheme may look a bit weird, but it has the purpose of
 151 allowing the co-existence of import libraries with ordinary static
 152 libraries (e.g., <Filename>libHSfoo.a</Filename> and <Filename>libHSfoo&lowbar;imp.a</Filename>.
 153
 154 Additionally, when the compiler driver is linking in non-static mode,
 155 it will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
 156 <Option>-lHSfoo&lowbar;imp</Option>. By doing this for you, switching from non-static
 157 to static linking is simply a question of adding <Option>-static</Option> to
 158 your command line.
 159
 160 </Para>
 161 </ListItem>
 162
 163 </ItemizedList>
 164
 165 </Para>
 166
 167 </Sect1>
 168
 169 </Chapter>
 170
 171 <!-- Emacs stuff:
 172      ;;; Local Variables: ***
 173      ;;; mode: sgml ***
 174      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 175      ;;; End: ***
 176  -->