docs/comm/the-beast/modules.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
   5     <title>The GHC Commentary - Modules, ModuleNames and Packages</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>Modules, ModuleNames and Packages</h1>
  10
  11     <p>This section describes the datatypes <code>ModuleName</code>
  12     <code>Module</code> and <code>PackageName</code> all available
  13     from the module <a
  14     href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/basicTypes/Module.lhs"><code>Module</code></a>.<p>
  15
  16     <h2>Packages</h2>
  17
  18     <p>A package is a collection of (zero or more) Haskell modules,
  19     together with some information about external libraries, extra C
  20     compiler options, and other things that this collection of modules
  21     requires.  When using DLLs on windows (or shared libraries on a
  22     Unix system; currently unsupported), a package can consist of only
  23     a single shared library of Haskell code; the reason for this is
  24     described below.
  25
  26     <p>Packages are further described in the User's Guide <a
  27     href="http://www.haskell.org/ghc/docs/latest/packages.html">here</a>.
  28
  29     <h2>The ModuleName type</h2>
  30
  31     <p>At the bottom of the hierarchy is a <code>ModuleName</code>,
  32     which, as its name suggests, is simply the name of a module.  It
  33     is represented as a Z-encoded FastString, and is an instance of
  34     <code>Uniquable</code> so we can build <code>FiniteMap</code>s
  35     with <code>ModuleName</code>s as the keys.
  36
  37     <p>A <code>ModuleName</code> can be built from a
  38     <code>String</code>, using the <code>mkModuleName</code> function.
  39
  40     <h2>The Module type</h2>
  41
  42     <p>For a given module, the compiler also needs to know whether the
  43     module is in the <em>home package</em>, or in another package.
  44     This distinction is important for two reasons:
  45
  46     <ul>
  47     <li><p>When generating code to call a function in another package,
  48     the compiler might have to generate a cross-DLL call, which is
  49     different from an intra-DLL call (hence the restriction that the
  50     code in a package can only reside in a single DLL).
  51
  52     <li><p>We avoid putting version information in an interface file
  53     for entities defined in another package, on the grounds that other
  54     packages are generally "stable".  This also helps keep the size of
  55     interface files down.
  56     </ul>
  57
  58     <p>The <code>Module</code> type contains a <code>ModuleName</code>
  59     and a <code>PackageInfo</code> field.  The
  60     <code>PackageInfo</code> indicates whether the given
  61     <code>Module</code> comes from the current package or from another
  62     package.
  63
  64     <p>To get the actual package in which a given module resides, you
  65     have to read the interface file for that module, which contains
  66     the package name (actually the value of the
  67     <code>-package-name</code> flag when that module was built).  This
  68     information is currently unused inside the compiler, but we might
  69     make use of it in the future, especially with the advent of
  70     hierarchical modules, to allow the compiler to automatically
  71     figure out which packages a program should be linked with, and
  72     thus avoid the need to specify <code>-package</code> options on
  73     the command line.
  74
  75     <p><code>Module</code>s are also instances of
  76     <code>Uniquable</code>, and indeed the unique of a
  77     <code>Module</code> is the same as the unique of the underlying
  78     <code>ModuleName</code>.
  79   </body>
  80 </html>