[project @ 2001-04-04 13:56:09 by simonpj]

Document orphan modules

diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml
index b49a109..008e942 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.sgml
+++ b/ghc/docs/users_guide/separate_compilation.sgml
@@ -603,6 +603,74 @@ __export A TA;
       recursive modules properly without the manual construction of
       interface files, is (allegedly) in the works.</para>
     </sect2>
+
+
+    <sect2 id="orphan-modules">
+      <title>Orphan modules and instance declarations</title>
+
+<para> Haskell specifies that when compiling module M, any instance
+declaration in any module "below" M is visible.  (Module A is "below"
+M if A is imported directly by M, or if A is below a module that M imports directly.)
+In principle, GHC must therefore read the interface files of every module below M,
+just in case they contain an instance declaration that matters to M.  This would
+be a disaster in practice, so GHC tries to be clever. </para>
+
+<para>In particular, if an instance declaration is in the same module as the definition
+of any type or class mentioned in the head of the instance declaration, then
+GHC has to visit that interface file anyway.  Example:</para>
+<ProgramListing>
+  module A where
+    instance C a = D (T a) where ...
+    data T a = ...
+</ProgramListing>
+<para> The instance declaration is only relevant if the type T is in use, and if
+so, GHC will have visited A's interface file to find T's definition. </para>
+
+<para> The only problem comes when a module contains an instance declaration
+and GHC has no other reason for visiting the module.  Example:
+<ProgramListing>
+  module Orphan where
+    instance C a = D (T a) where ...
+    class C a where ...
+</ProgramListing>
+Here, neither D nor T is declared in module Orphan.
+We call such modules ``orphan modules'',
+defined thus:</para>
+<itemizedlist>
+  <listitem> <para> An <emphasis>orphan module</emphasis> 
+  <indexterm><primary>orphan module</primary></indexterm>
+  contains at least one <emphasis>orphan instance</emphasis> or at 
+  least one <emphasis>orphan rule</emphasis>.</para> </listitem>
+
+  <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
+  <indexterm><primary>orphan instance</primary></indexterm>
+  none of the type constructors
+  or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
+  in M.</para> 
+
+  <para> Only the instance head counts.  In the example above, it is not good enough for C's declaration 
+  to be in module A; it must be the declaration of D or T.</para>
+  </listitem>
+
+  <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
+  <indexterm><primary>orphan rule</primary></indexterm>
+  if none of the variables, type constructors,
+  or classes that are free in the left hand side of the rule are declared in M.
+  </para> </listitem>
+ </itemizedlist>
+
+
+<para> GHC identifies orphan modules, and visits the interface file of
+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>
+</sect2>
+
   </sect1>
 
 <!-- Emacs stuff: