1 files changed, 80 insertions, 0 deletions
diff --git a/docs/comm/the-beast/modules.html b/docs/comm/the-beast/modules.html
new file mode 100644
index 0000000000..a6655a68a7
--- /dev/null
+++ b/docs/comm/the-beast/modules.html
@@ -0,0 +1,80 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+    <title>The GHC Commentary - Modules, ModuleNames and Packages</title>
+  </head>
+
+  <body BGCOLOR="FFFFFF">
+    <h1>Modules, ModuleNames and Packages</h1>
+
+    <p>This section describes the datatypes <code>ModuleName</code>
+    <code>Module</code> and <code>PackageName</code> all available
+    from the module <a
+    href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/basicTypes/Module.lhs"><code>Module</code></a>.<p>
+
+    <h2>Packages</h2>
+
+    <p>A package is a collection of (zero or more) Haskell modules,
+    together with some information about external libraries, extra C
+    compiler options, and other things that this collection of modules
+    requires.  When using DLLs on windows (or shared libraries on a
+    Unix system; currently unsupported), a package can consist of only
+    a single shared library of Haskell code; the reason for this is
+    described below.
+
+    <p>Packages are further described in the User's Guide <a
+    href="http://www.haskell.org/ghc/docs/latest/packages.html">here</a>.
+
+    <h2>The ModuleName type</h2>
+
+    <p>At the bottom of the hierarchy is a <code>ModuleName</code>,
+    which, as its name suggests, is simply the name of a module.  It
+    is represented as a Z-encoded FastString, and is an instance of
+    <code>Uniquable</code> so we can build <code>FiniteMap</code>s
+    with <code>ModuleName</code>s as the keys.
+
+    <p>A <code>ModuleName</code> can be built from a
+    <code>String</code>, using the <code>mkModuleName</code> function.
+
+    <h2>The Module type</h2>
+
+    <p>For a given module, the compiler also needs to know whether the
+    module is in the <em>home package</em>, or in another package.
+    This distinction is important for two reasons:
+
+    <ul>
+    <li><p>When generating code to call a function in another package,
+    the compiler might have to generate a cross-DLL call, which is
+    different from an intra-DLL call (hence the restriction that the
+    code in a package can only reside in a single DLL).
+
+    <li><p>We avoid putting version information in an interface file
+    for entities defined in another package, on the grounds that other
+    packages are generally "stable".  This also helps keep the size of
+    interface files down.
+    </ul>
+
+    <p>The <code>Module</code> type contains a <code>ModuleName</code>
+    and a <code>PackageInfo</code> field.  The
+    <code>PackageInfo</code> indicates whether the given
+    <code>Module</code> comes from the current package or from another
+    package.
+
+    <p>To get the actual package in which a given module resides, you
+    have to read the interface file for that module, which contains
+    the package name (actually the value of the
+    <code>-package-name</code> flag when that module was built).  This
+    information is currently unused inside the compiler, but we might
+    make use of it in the future, especially with the advent of
+    hierarchical modules, to allow the compiler to automatically
+    figure out which packages a program should be linked with, and
+    thus avoid the need to specify <code>-package</code> options on
+    the command line.
+
+    <p><code>Module</code>s are also instances of
+    <code>Uniquable</code>, and indeed the unique of a
+    <code>Module</code> is the same as the unique of the underlying
+    <code>ModuleName</code>.
+  </body>
+</html>