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