[project @ 2003-05-30 09:04:28 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / separate_compilation.sgml

diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml
index 5e0ce6c..42abfee 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.sgml
+++ b/ghc/docs/users_guide/separate_compilation.sgml
@@ -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>
@@ -260,7 +297,7 @@ OBJS = Main.o   Foo.o   Bar.o
 .SUFFIXES : .o .hs .hi .lhs .hc .s
 
 cool_pgm : $(OBJS)
-        rm $@
+        rm -f $@
         $(HC) -o $@ $(HC_OPTS) $(OBJS)
 
 # Standard suffix rules
@@ -581,12 +618,22 @@ newtype TA = MkTA GHC.Base.Int
          particular, most <literal>Prelude</literal> entities aren't
          actually defined in the <literal>Prelude</literal> (see for
          example <literal>GHC.Base.Int</literal> in the above
-         example).</para>
+         example).  HINT: to find out the fully-qualified name for
+         entities in the <literal>Prelude</literal> (or anywhere for
+         that matter), try using GHCi's
+         <literal>:info</literal> command, eg.</para>
+<programlisting>Prelude> :m -Prelude
+> :i IO.IO
+-- GHC.IOBase.IO is a type constructor
+newtype GHC.IOBase.IO a
+...</programlisting>
        </listitem>
        <listitem>
          <para>Only <literal>data</literal>, <literal>type</literal>,
          <literal>newtype</literal>, <literal>class</literal>, and
-         type signature declarations may be included.</para>
+         type signature declarations may be included. You cannot declare
+         <literal>instances</literal> or derive them automatically.
+</para>
        </listitem>
       </itemizedlist>
 
@@ -670,9 +717,12 @@ every orphan module below the module being compiled.  This is usually
 wasted work, but there is no avoiding it.  You should therefore do
 your best to have as few orphan modules as possible.
 
-</para><para>
-You can identify an orphan module by looking in its interface file, M.hi.  If there is a ``!'' on
-the first line, GHC considers it an orphan module. 
+</para>
+
+<para> You can identify an orphan module by looking in its interface
+file, <filename>M.hi</filename>, using the
+<option>--show-iface</option>.  If there is a ``!'' on the first line,
+GHC considers it an orphan module.
 </para>
 </sect2>