Test Trac #9036
[ghc.git] / 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>