Commit 7c85c014 authored by simonmar's avatar simonmar
Browse files

[project @ 2002-06-27 12:17:47 by simonmar]

Improve the documentation for hierarchical libraries.
parent d74f18bb
......@@ -2385,38 +2385,38 @@ Assertion failures can be caught, see the documentation for the
it extends the normally flat Haskell module namespace into a
more flexible hierarchy of modules.</para>
<para>A module name in the extended syntax consists of a
sequence of components, each separated by a dot. When searching
for an interface file (or a source file, in the case of GHCi or
when using <option>--make</option>) for an imported module, GHC
interprets the dot as a path separator. So for example, if a
module <literal>A.B.C</literal> is imported, then for each
directory <literal>D</literal> on the search path (see the
<option>-i</option> option, <xref
linkend="options-finding-imports">), GHC will look in the
directory <literal>D/A/B</literal><footnote><para>On Windows,
this would be <literal>D\A\B</literal>.</para></footnote> for an
interface file called <filename>C.hi</filename> or a source file
<filename>C.hs</filename> or <filename>C.lhs</filename>.</para>
<para>Note that as far as the compiler is concerned, module
names are always fully qualified; the hierarchy only has a
special meaning when searching for interface files and source
files in the filesystem. In particular, this means that the
full module name must be given after the
<para>This extension has very little impact on the language
itself; modules names are <emphasis>always</emphasis> fully
qualified, so you can just think of the fully qualified module
name as <quote>the module name</quote>. In particular, this
means that the full module name must be given after the
<literal>module</literal> keyword at the beginning of the
module; for example, the module <literal>A.B.C</literal> must
begin</para>
<programlisting>module A.B.C</programlisting>
<para>It is a common strategy to use the <literal>as</literal>
keyword to save some typing when using qualified names with
hierarchical modules. For example:</para>
<programlisting>
import qualified Control.Monad.ST.Strict as ST
</programlisting>
<para>Hierarchical modules have an impact on the way that GHC
searches for files. For a description, see <xref
linkend="finding-hierarchical-modules">.</para>
<para>GHC comes with a large collection of libraries arranged
hierarchically; see the accompanying library documentation.
There is an ongoing project to create and maintain a stable set
of <quote>core</quote> libraries used by several Haskell
compilers, and the libraries that GHC comes with represent the
current status of that project. For more details, see <ulink
url="http://www.haskell.org/~simonmar/libraries/libraries.html">.</ulink></para>
url="http://www.haskell.org/~simonmar/libraries/libraries.html">Haskell
Libraries</ulink>.</para>
</sect2>
......
......@@ -120,6 +120,43 @@
</sect2>
<sect2 id="finding-hierarchical-modules">
<title>Finding interfaces for hierarchical modules</title>
<para>GHC supports a hierarchical module namespace as an
extension to Haskell 98 (see <xref
linkend="hierarchical-modules">).</para>
<para>A module name in general consists of a sequence of
components separated by dots
(&lsquo;<literal>.</literal>&rsquo;). When looking for
interface files for a hierarchical module, the compiler turns
the dots into path separators, so for example a module
<literal>A.B.C</literal> becomes <literal>A/B/C</literal> (or
<literal>A\B\C</literal> under Windows). Then each component of
the import directories list is tested in turn; so for example if
the list contains directories
<literal>D<subscript>1</subscript></literal> to
<literal>D<subscript>n</subscript></literal>, then the compiler
will look for the interface in
<literal>D<subscript>1</subscript>/A/B/C.hi</literal> first,
then <literal>D<subscript>2</subscript>/A/B/C.hi</literal> and
so on.</para>
<para>Note that it's perfectly reasonable to have a module which
is both a leaf and a branch of the tree. For example, if we
have modules <literal>A.B</literal> and
<literal>A.B.C</literal>, then <literal>A.B</literal>'s
interface file will be in <literal>A/B.hi</literal> and
<literal>A.B.C</literal>'s interface file will be in
<literal>A/B/C.hi</literal>.</para>
<para>For GHCi and <option>--make</option>, the search strategy
for source files is exactly the same, just replace the
<literal>.hi</literal> suffix in the above description with
<literal>.hs</literal> or <literal>.lhs</literal>.</para>
</sect2>
<Sect2 id="hi-options">
<title>Other options related to interface files</title>
<indexterm><primary>interface files, options</primary></indexterm>
......
......@@ -443,6 +443,12 @@ ghc &ndash;&ndash;make Main.hs
interface file for the module, then GHC will complain. The
exception to this rule is for package modules, which may or may
not have source files.</para>
<para>The source files for the program don't all need to be in the
same directory; the <option>-i</option> option can be used to add
directories to the search path (see <xref
linkend="options-finding-imports">).</para>
</sect1>
<Sect1 id="options-order">
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment