compiler/DLL-NOTES

   1                               The DLL story
   2                               -------------
   3
   4 ***
   5
   6 This file is intended to be a focal point for notes on how DLLs work. Please
   7 add cross-references to source and other docs, especially when you don't
   8 find something here that you need.
   9
  10 ***
  11
  12
  13 Introduction
  14 ------------
  15
  16 On Windows, DLLs are synonymous with packages (since 4.07; this change
  17 simplified a rather horrible mess). Hence whenever a module is to be
  18 compiled to go in a DLL, it must be compiled with -package-name dll-name.
  19 Typically, failing to do this gives Windows error message boxes of the form
  20 "The instruction at address <x> tried to read memory at address <x>".
  21
  22
  23 Dependencies
  24 ------------
  25
  26 Because references in DLLs must be fully resolved when the DLL is compiled
  27 (except for references to other DLLs), it is not possible for DLLs to call
  28 the main program. This means that the parts of the RTS and standard package
  29 which call the main program cannot be compiled into the relevant DLLs, and
  30 must instead be compiled as standalone object files and linked in to each
  31 executable. This gives the following picture of dependencies within a program:
  32
  33             ___________         ___________
  34            |           |------>|           |   GHC-land  |  Application-land
  35 DLL-land   | HSrts.dll |       | HSstd.dll |             |
  36            |___________|<------|___________|             |
  37                  |                   ^                   |
  38 -----------------|-------------------|-------------------|
  39             _____v_____         _____|______             |
  40 .o-land    |           |       |            |            |
  41            |  Main.o   |       | PrelMain.o |-----------------------
  42            |___________|       |____________|            |          |
  43                  |                                       |    ______v______
  44                  |                                       |   |             |
  45                   ------------------------------------------>|   Main.o    |
  46                                                          |   |_____________|
  47
  48 (The application's dependencies are not shown.)
  49
  50
  51 Bits of the compiler that deal with DLLs
  52 ----------------------------------------
  53
  54 basicTypes/Module.lhs is the most important place, as it deals with which
  55 modules identifiers are in.
  56
  57 basicTypes/name.lhs, other bits of basicTypes/, nativeGen/, codeGen/,
  58 abcCSyn/, and even profiling/ have other references.