ghc/docs/users_guide/separate_compilation.sgml

   1   <sect1 id="separate-compilation">
   2     <title>Separate compilation</title>
   3
   4     <indexterm><primary>separate compilation</primary></indexterm>
   5     <indexterm><primary>recompilation checker</primary></indexterm>
   6     <indexterm><primary>make and recompilation</primary></indexterm>
   7
   8     <para>This section describes how GHC supports separate
   9     compilation.</para>
  10
  11     <sect2 id="hi-files">
  12       <title>Interface files</title>
  13
  14       <indexterm><primary>interface files</primary></indexterm>
  15       <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
  16
  17       <para>When GHC compiles a source file <filename>A.hs</filename>
  18       which contains a module <literal>A</literal>, say, it generates
  19       an object <filename>A.o</filename>, <emphasis>and</emphasis> a
  20       companion <emphasis>interface file</emphasis>
  21       <filename>A.hi</filename>.  The interface file is merely there
  22       to help the compiler compile other modules in the same program.
  23       Interfaces are in a binary format, so don't try to look at one;
  24       however you <emphasis>can</emphasis> see the contents of an
  25       interface file by using GHC with the
  26       <option>--show-iface</option> option (see <xref
  27       linkend="hi-options">, below).</para>
  28
  29       <para>NOTE: In general, the name of a file containing module
  30       <literal>M</literal> should be named <filename>M.hs</filename>
  31       or <literal>M.lhs</literal>.  The only exception to this rule is
  32       module <literal>Main</literal>, which can be placed in any
  33       file.<indexterm><primary>filenames</primary><secondary>for
  34       modules</secondary> </indexterm></para>
  35
  36       <para>The interface file for <literal>A</literal> contains
  37       information needed by the compiler when it compiles any module
  38       <literal>B</literal> that imports <literal>A</literal>, whether
  39       directly or indirectly.  When compiling <literal>B</literal>,
  40       GHC will read <filename>A.hi</filename> to find the details that
  41       it needs to know about things defined in
  42       <literal>A</literal>.</para>
  43
  44       <para>The interface file may contain all sorts of things that
  45       aren't explicitly exported from <literal>A</literal> by the
  46       programmer.  For example, even though a data type is exported
  47       abstractly, <filename>A.hi</filename> will contain the full data
  48       type definition.  For small function definitions,
  49       <filename>A.hi</filename> will contain the complete definition
  50       of the function.  For bigger functions,
  51       <filename>A.hi</filename> will contain strictness information
  52       about the function.  And so on.  GHC puts much more information
  53       into <filename>.hi</filename> files when optimisation is turned
  54       on with the <option>-O</option> flag (see <xref
  55       linkend="options-optimise">).  Without <option>-O</option> it
  56       puts in just the minimum; with <option>-O</option> it lobs in a
  57       whole pile of stuff.  <indexterm><primary>optimsation, effect on
  58       .hi files</primary></indexterm></para>
  59
  60       <para><filename>A.hi</filename> should really be thought of as a
  61       compiler-readable version of <filename>A.o</filename>.  If you
  62       use a <filename>.hi</filename> file that wasn't generated by the
  63       same compilation run that generates the <filename>.o</filename>
  64       file the compiler may assume all sorts of incorrect things about
  65       <literal>A</literal>, resulting in core dumps and other
  66       unpleasant happenings.</para>
  67
  68     </sect2>
  69
  70     <sect2 id="options-finding-imports">
  71       <title>Finding interface files</title>
  72
  73       <indexterm><primary>interface files, finding them</primary></indexterm>
  74       <indexterm><primary>finding interface files</primary></indexterm>
  75
  76       <para>In your program, you import a module
  77       <literal>Foo</literal> by saying <literal>import Foo</literal>.
  78       GHC goes looking for an interface file,
  79       <filename>Foo.hi</filename>.  It has a builtin list of
  80       directories (notably including <filename>.</filename>) where it
  81       looks.</para>
  82
  83       <variablelist>
  84
  85         <varlistentry>
  86           <term><option>-i&lt;dirs&gt;</option></term>
  87           <listitem>
  88             <para><indexterm><primary><option>-i&lt;dirs&gt;</option>
  89             </primary></indexterm>This flag appends a colon-separated
  90             list of <filename>dirs</filename> to the &ldquo;import
  91             directories&rdquo; list, which initially contains a single
  92             entry: <quote>.</quote>.</para>
  93
  94             <para>This list is scanned before any package directories
  95             (see <xref linkend="packages">) when looking for imports,
  96             but note that if you have a home module with the same name
  97             as a package module then this is likely to cause trouble
  98             in other ways, with link errors being the least nasty
  99             thing that can go wrong...</para>
 100
 101             <para>See also <XRef LinkEnd="recomp"> for the
 102             significance of using relative and absolute pathnames in
 103             the <option>-i</option> list.</para>
 104           </listitem>
 105         </varlistentry>
 106
 107         <varlistentry>
 108           <term><option>-i</option></term>
 109           <listitem>
 110             <para>resets the &ldquo;import directories&rdquo; list
 111             back to nothing.</para>
 112           </listitem>
 113         </varlistentry>
 114
 115       </variablelist>
 116
 117       <para>See also the section on packages (<xref
 118       linkend="packages">), which describes how to use installed
 119       libraries.</para>
 120
 121     </sect2>
 122
 123     <Sect2 id="hi-options">
 124       <title>Other options related to interface files</title>
 125       <indexterm><primary>interface files, options</primary></indexterm>
 126
 127       <variablelist>
 128         <varlistentry>
 129           <term><option>-ddump-hi</option></term>
 130           <indexterm><primary><option>-ddump-hi</option></primary>
 131           </indexterm>
 132           <listitem>
 133             <para>Dumps the new interface to standard output.</para>
 134           </listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term><option>-ddump-hi-diffs</option></term>
 139           <indexterm><primary><option>-ddump-hi-diffs</option></primary>
 140           </indexterm>
 141           <listitem>
 142             <para>The compiler does not overwrite an existing
 143             <filename>.hi</filename> interface file if the new one is
 144             the same as the old one; this is friendly to
 145             <command>make</command>.  When an interface does change,
 146             it is often enlightening to be informed.  The
 147             <option>-ddump-hi-diffs</option> option will make GHC run
 148             <command>diff</command> on the old and new
 149             <filename>.hi</filename> files.</para>
 150           </listitem>
 151         </varlistentry>
 152
 153         <varlistentry>
 154           <term><option>-ddump-minimal-imports</option></term>
 155           <indexterm><primary><option>-ddump-minimal-imports</option></primary>
 156           </indexterm>
 157           <listitem>
 158             <para>Dump to the file "M.imports" (where M is the module
 159             being compiled) a "minimal" set of import declarations.
 160             You can safely replace all the import declarations in
 161             "M.hs" with those found in "M.imports".  Why would you
 162             want to do that?  Because the "minimal" imports (a) import
 163             everything explicitly, by name, and (b) import nothing
 164             that is not required.  It can be quite painful to maintain
 165             this property by hand, so this flag is intended to reduce
 166             the labour.</para>
 167           </listitem>
 168         </varlistentry>
 169
 170         <varlistentry>
 171           <term><option>--show-iface</option>
 172           <replaceable>file</replaceable></term>
 173           <indexterm><primary><option>--show-iface</option></primary>
 174           </indexterm>
 175           <listitem>
 176             <para>Where <replaceable>file</replaceable> is the name of
 177             an interface file, dumps the contents of that interface in
 178             a human-readable (ish) format.</para>
 179           </listitem>
 180         </varlistentry>
 181       </variablelist>
 182
 183     </sect2>
 184
 185     <sect2 id="recomp">
 186       <title>The recompilation checker</title>
 187
 188       <indexterm><primary>recompilation checker</primary></indexterm>
 189
 190       <variablelist>
 191         <varlistentry>
 192           <term><option>-no-recomp</option></term>
 193           <indexterm><primary><option>-recomp</option></primary></indexterm>
 194           <indexterm><primary><option>-no-recomp</option></primary></indexterm>
 195           <listitem>
 196             <para>Turn off recompilation checking (which is on by
 197             default).  Recompilation checking normally stops
 198             compilation early, leaving an existing
 199             <filename>.o</filename> file in place, if it can be
 200             determined that the module does not need to be
 201             recompiled.</para>
 202           </listitem>
 203         </varlistentry>
 204       </variablelist>
 205
 206       <para>In the olden days, GHC compared the newly-generated
 207       <filename>.hi</filename> file with the previous version; if they
 208       were identical, it left the old one alone and didn't change its
 209       modification date.  In consequence, importers of a module with
 210       an unchanged output <filename>.hi</filename> file were not
 211       recompiled.</para>
 212
 213       <para>This doesn't work any more.  Suppose module
 214       <literal>C</literal> imports module <literal>B</literal>, and
 215       <literal>B</literal> imports module <literal>A</literal>.  So
 216       changes to <filename>A.hi</filename> should force a
 217       recompilation of <literal>C</literal>.  And some changes to
 218       <literal>A</literal> (changing the definition of a function that
 219       appears in an inlining of a function exported by
 220       <literal>B</literal>, say) may conceivably not change
 221       <filename>B.hi</filename> one jot.  So now&hellip;</para>
 222
 223       <para>GHC keeps a version number on each interface file, and on
 224       each type signature within the interface file.  It also keeps in
 225       every interface file a list of the version numbers of everything
 226       it used when it last compiled the file.  If the source file's
 227       modification date is earlier than the <filename>.o</filename>
 228       file's date (i.e. the source hasn't changed since the file was
 229       last compiled), and the reompilation checking is on, GHC will be
 230       clever.  It compares the version numbers on the things it needs
 231       this time with the version numbers on the things it needed last
 232       time (gleaned from the interface file of the module being
 233       compiled); if they are all the same it stops compiling rather
 234       early in the process saying &ldquo;Compilation IS NOT
 235       required&rdquo;.  What a beautiful sight!</para>
 236
 237       <para>Patrick Sansom had a workshop paper about how all this is
 238       done (though the details have changed quite a bit). <ULink
 239       URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
 240       copy.</para>
 241
 242     </sect2>
 243
 244     <sect2 id="using-make">
 245       <title>Using <command>make</command></title>
 246
 247       <indexterm><primary><literal>make</literal></primary></indexterm>
 248
 249       <para>It is reasonably straightforward to set up a
 250       <filename>Makefile</filename> to use with GHC, assuming you name
 251       your source files the same as your modules.  Thus:</para>
 252
 253 <ProgramListing>
 254 HC      = ghc
 255 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
 256
 257 SRCS = Main.lhs Foo.lhs Bar.lhs
 258 OBJS = Main.o   Foo.o   Bar.o
 259
 260 .SUFFIXES : .o .hs .hi .lhs .hc .s
 261
 262 cool_pgm : $(OBJS)
 263         rm $@
 264         $(HC) -o $@ $(HC_OPTS) $(OBJS)
 265
 266 # Standard suffix rules
 267 .o.hi:
 268         @:
 269
 270 .lhs.o:
 271         $(HC) -c $&#60; $(HC_OPTS)
 272
 273 .hs.o:
 274         $(HC) -c $&#60; $(HC_OPTS)
 275
 276 # Inter-module dependencies
 277 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 278 Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
 279 </ProgramListing>
 280
 281       <para>(Sophisticated <command>make</command> variants may
 282       achieve some of the above more elegantly.  Notably,
 283       <command>gmake</command>'s pattern rules let you write the more
 284       comprehensible:</para>
 285
 286 <ProgramListing>
 287 %.o : %.lhs
 288         $(HC) -c $&#60; $(HC_OPTS)
 289 </ProgramListing>
 290
 291       <para>What we've shown should work with any
 292       <command>make</command>.)</para>
 293
 294       <para>Note the cheesy <literal>.o.hi</literal> rule: It records
 295       the dependency of the interface (<filename>.hi</filename>) file
 296       on the source.  The rule says a <filename>.hi</filename> file
 297       can be made from a <filename>.o</filename> file by
 298       doing&hellip;nothing.  Which is true.</para>
 299
 300       <para>Note the inter-module dependencies at the end of the
 301       Makefile, which take the form</para>
 302
 303 <ProgramListing>
 304 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 305 </ProgramListing>
 306
 307       <para>They tell <command>make</command> that if any of
 308       <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
 309       <literal>Foo.s</literal> have an earlier modification date than
 310       <literal>Baz.hi</literal>, then the out-of-date file must be
 311       brought up to date.  To bring it up to date,
 312       <literal>make</literal> looks for a rule to do so; one of the
 313       preceding suffix rules does the job nicely.</para>
 314
 315       <sect3 id="sec-makefile-dependencies">
 316         <title>Dependency generation</title>
 317         <indexterm><primary>dependencies in Makefiles</primary></indexterm>
 318         <indexterm><primary>Makefile dependencies</primary></indexterm>
 319
 320         <para>Putting inter-dependencies of the form <literal>Foo.o :
 321         Bar.hi</literal> into your <filename>Makefile</filename> by
 322         hand is rather error-prone.  Don't worry, GHC has support for
 323         automatically generating the required dependencies.  Add the
 324         following to your <filename>Makefile</filename>:</para>
 325
 326 <ProgramListing>
 327 depend :
 328         ghc -M $(HC_OPTS) $(SRCS)
 329 </ProgramListing>
 330
 331         <para>Now, before you start compiling, and any time you change
 332         the <literal>imports</literal> in your program, do
 333         <command>make depend</command> before you do <command>make
 334         cool&lowbar;pgm</command>.  <command>ghc -M</command> will
 335         append the needed dependencies to your
 336         <filename>Makefile</filename>.</para>
 337
 338         <para>In general, if module <literal>A</literal> contains the
 339         line
 340
 341 <programlisting>
 342 import B ...blah...
 343 </programlisting>
 344
 345         then <command>ghc -M</command> will generate a dependency line
 346         of the form:
 347
 348 <programlisting>
 349 A.o : B.hi
 350 </programlisting>
 351
 352         If module <literal>A</literal> contains the line
 353
 354 <programlisting>
 355 import {-# SOURCE #-} B ...blah...
 356 </programlisting>
 357
 358         then <command>ghc -M</command> will generate a dependency
 359         line of the form:
 360
 361 <programlisting>
 362 A.o : B.hi-boot
 363 </programlisting>
 364
 365        (See <xref linkend="mutual-recursion"> for details of
 366        <literal>hi-boot</literal> style interface files.)  If
 367        <literal>A</literal> imports multiple modules, then there will
 368        be multiple lines with <filename>A.o</filename> as the
 369        target.</para>
 370
 371         <para>By default, <command>ghc -M</command> generates all the
 372         dependencies, and then concatenates them onto the end of
 373         <filename>makefile</filename> (or
 374         <filename>Makefile</filename> if <filename>makefile</filename>
 375         doesn't exist) bracketed by the lines "<literal>&num; DO NOT
 376         DELETE: Beginning of Haskell dependencies</literal>" and
 377         "<literal>&num; DO NOT DELETE: End of Haskell
 378         dependencies</literal>".  If these lines already exist in the
 379         <filename>makefile</filename>, then the old dependencies are
 380         deleted first.</para>
 381
 382         <para>Don't forget to use the same <option>-package</option>
 383         options on the <literal>ghc -M</literal> command line as you
 384         would when compiling; this enables the dependency generator to
 385         locate any imported modules that come from packages.  The
 386         package modules won't be included in the dependencies
 387         generated, though (but see the
 388         <option>&ndash;&ndash;include-prelude</option> option below).</para>
 389
 390         <para>The dependency generation phase of GHC can take some
 391         additional options, which you may find useful.  For historical
 392         reasons, each option passed to the dependency generator from
 393         the GHC command line must be preceded by
 394         <literal>-optdep</literal>.  For example, to pass <literal>-f
 395         .depend</literal> to the dependency generator, you say
 396
 397 <screen>
 398 ghc -M -optdep-f -optdep.depend ...
 399 </screen>
 400
 401         The options which affect dependency generation are:</para>
 402
 403         <variablelist>
 404           <varlistentry>
 405             <term><option>-w</option></term>
 406             <listitem>
 407               <para>Turn off warnings about interface file shadowing.</para>
 408             </listitem>
 409           </varlistentry>
 410
 411           <varlistentry>
 412             <term><option>-f</option> <replaceable>file</replaceable></term>
 413             <listitem>
 414               <para>Use <replaceable>file</replaceable> as the makefile,
 415               rather than <filename>makefile</filename> or
 416               <filename>Makefile</filename>.  If
 417               <replaceable>file</replaceable> doesn't exist,
 418               <command>mkdependHS</command> creates it.  We often use
 419               <option>-f .depend</option> to put the dependencies in
 420               <filename>.depend</filename> and then
 421               <command>include</command> the file
 422               <filename>.depend</filename> into
 423               <filename>Makefile</filename>.</para>
 424             </listitem>
 425           </varlistentry>
 426
 427           <varlistentry>
 428             <term><option>-o &lt;osuf&gt;</option></term>
 429             <listitem>
 430               <para>Use <filename>.&lt;osuf&gt;</filename> as the
 431               "target file" suffix ( default: <literal>o</literal>).
 432               Multiple <option>-o</option> flags are permitted
 433               (GHC2.05 onwards).  Thus "<option>-o hc -o o</option>"
 434               will generate dependencies for <filename>.hc</filename>
 435               and <filename>.o</filename> files.</para>
 436             </listitem>
 437           </varlistentry>
 438
 439           <varlistentry>
 440             <term><option>-s &lt;suf&gt;</option></term>
 441             <listitem>
 442               <para>Make extra dependencies that declare that files
 443               with suffix
 444               <filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</filename>
 445               depend on interface files with suffix
 446               <filename>.&lt;suf&gt;&lowbar;hi</filename>, or (for
 447               <literal>&lcub;-&num; SOURCE &num;-&rcub;</literal>
 448               imports) on <filename>.hi-boot</filename>.  Multiple
 449               <option>-s</option> flags are permitted.  For example,
 450               <option>-o hc -s a -s b</option> will make dependencies
 451               for <filename>.hc</filename> on
 452               <filename>.hi</filename>,
 453               <filename>.a&lowbar;hc</filename> on
 454               <filename>.a&lowbar;hi</filename>, and
 455               <filename>.b&lowbar;hc</filename> on
 456               <filename>.b&lowbar;hi</filename>.  (Useful in
 457               conjunction with NoFib "ways".)</para>
 458             </listitem>
 459           </varlistentry>
 460
 461           <varlistentry>
 462             <term><option>&ndash;&ndash;exclude-module=&lt;file&gt;</option></term>
 463             <listitem>
 464               <para>Regard <filename>&lt;file&gt;</filename> as
 465               "stable"; i.e., exclude it from having dependencies on
 466               it.</para>
 467             </listitem>
 468           </varlistentry>
 469
 470           <varlistentry>
 471             <term><option>-x</option></term>
 472             <listitem>
 473               <para>same as <option>&ndash;&ndash;exclude-module</option></para>
 474             </listitem>
 475           </varlistentry>
 476
 477           <varlistentry>
 478             <term><option>&ndash;&ndash;exclude-directory=&lt;dirs&gt;</option></term>
 479             <listitem>
 480               <para>Regard the colon-separated list of directories
 481               <filename>&lt;dirs&gt;</filename> as containing stable,
 482               don't generate any dependencies on modules
 483               therein.</para>
 484             </listitem>
 485           </varlistentry>
 486
 487           <varlistentry>
 488             <term><option>&ndash;&ndash;include-module=&lt;file&gt;</option></term>
 489             <listitem>
 490               <para>Regard <filename>&lt;file&gt;</filename> as not
 491               "stable"; i.e., generate dependencies on it (if
 492               any). This option is normally used in conjunction with
 493               the <option>&ndash;&ndash;exclude-directory</option> option.</para>
 494             </listitem>
 495           </varlistentry>
 496
 497           <varlistentry>
 498             <term><option>&ndash;&ndash;include-prelude</option></term>
 499             <listitem>
 500               <para>Regard modules imported from packages as unstable,
 501               i.e., generate dependencies on the package modules used
 502               (including <literal>Prelude</literal>, and all other
 503               standard Haskell libraries).  This option is normally
 504               only used by the various system libraries.</para>
 505             </listitem>
 506           </varlistentry>
 507         </variablelist>
 508
 509       </sect3>
 510     </sect2>
 511
 512     <sect2 id="mutual-recursion">
 513       <title>How to compile mutually recursive modules</title>
 514
 515       <indexterm><primary>module system, recursion</primary></indexterm>
 516       <indexterm><primary>recursion, between modules</primary></indexterm>
 517
 518       <para>Currently, the compiler does not have proper support for
 519       dealing with mutually recursive modules:</para>
 520
 521 <ProgramListing>
 522 module A where
 523
 524 import B
 525
 526 newtype TA = MkTA Int
 527
 528 f :: TB -&#62; TA
 529 f (MkTB x) = MkTA x
 530 --------
 531 module B where
 532
 533 import A
 534
 535 data TB = MkTB !Int
 536
 537 g :: TA -&#62; TB
 538 g (MkTA x) = MkTB x
 539 </ProgramListing>
 540
 541       <para>When compiling either module A and B, the compiler will
 542       try (in vain) to look for the interface file of the other. So,
 543       to get mutually recursive modules off the ground, you need to
 544       hand write an interface file for A or B, so as to break the
 545       loop.  These hand-written interface files are called
 546       <literal>hi-boot</literal> files, and are placed in a file
 547       called <filename>&lt;module&gt;.hi-boot</filename>.  To import
 548       from an <literal>hi-boot</literal> file instead of the standard
 549       <filename>.hi</filename> file, use the following syntax in the
 550       importing module: <indexterm><primary><literal>hi-boot</literal>
 551       files</primary></indexterm> <indexterm><primary>importing,
 552       <literal>hi-boot</literal> files</primary></indexterm></para>
 553
 554 <ProgramListing>
 555 import {-# SOURCE #-} A
 556 </ProgramListing>
 557
 558       <para>The hand-written interface need only contain the bare
 559       minimum of information needed to get the bootstrapping process
 560       started.  For example, it doesn't need to contain declarations
 561       for <emphasis>everything</emphasis> that module
 562       <literal>A</literal> exports, only the things required by the
 563       module that imports <literal>A</literal> recursively.</para>
 564
 565       <para>For the example at hand, the boot interface file for A
 566       would look like the following:</para>
 567
 568 <ProgramListing>
 569 module A where
 570 newtype TA = MkTA GHC.Base.Int
 571 </ProgramListing>
 572
 573       <para>The syntax is similar to a normal Haskell source file, but
 574       with some important differences:</para>
 575
 576       <itemizedlist>
 577         <listitem>
 578           <para>Non-local entities must be qualified with their
 579           <emphasis>original</emphasis> defining module.  Qualifying
 580           by a module which just re-exports the entity won't do.  In
 581           particular, most <literal>Prelude</literal> entities aren't
 582           actually defined in the <literal>Prelude</literal> (see for
 583           example <literal>GHC.Base.Int</literal> in the above
 584           example).</para>
 585         </listitem>
 586         <listitem>
 587           <para>Only <literal>data</literal>, <literal>type</literal>,
 588           <literal>newtype</literal>, <literal>class</literal>, and
 589           type signature declarations may be included.</para>
 590         </listitem>
 591       </itemizedlist>
 592
 593       <para>Notice that we only put the declaration for the newtype
 594       <literal>TA</literal> in the <literal>hi-boot</literal> file,
 595       not the signature for <Function>f</Function>, since
 596       <Function>f</Function> isn't used by <literal>B</literal>.</para>
 597
 598       <para>If you want an <literal>hi-boot</literal> file to export a
 599       data type, but you don't want to give its constructors (because
 600       the constructors aren't used by the SOURCE-importing module),
 601       you can write simply:</para>
 602
 603 <ProgramListing>
 604 module A where
 605 data TA
 606 </ProgramListing>
 607
 608       <para>(You must write all the type parameters, but leave out the
 609       '=' and everything that follows it.)</para>
 610     </sect2>
 611
 612
 613     <sect2 id="orphan-modules">
 614       <title>Orphan modules and instance declarations</title>
 615
 616 <para> Haskell specifies that when compiling module M, any instance
 617 declaration in any module "below" M is visible.  (Module A is "below"
 618 M if A is imported directly by M, or if A is below a module that M imports directly.)
 619 In principle, GHC must therefore read the interface files of every module below M,
 620 just in case they contain an instance declaration that matters to M.  This would
 621 be a disaster in practice, so GHC tries to be clever. </para>
 622
 623 <para>In particular, if an instance declaration is in the same module as the definition
 624 of any type or class mentioned in the head of the instance declaration, then
 625 GHC has to visit that interface file anyway.  Example:</para>
 626 <ProgramListing>
 627   module A where
 628     instance C a =&gt; D (T a) where ...
 629     data T a = ...
 630 </ProgramListing>
 631 <para> The instance declaration is only relevant if the type T is in use, and if
 632 so, GHC will have visited A's interface file to find T's definition. </para>
 633
 634 <para> The only problem comes when a module contains an instance declaration
 635 and GHC has no other reason for visiting the module.  Example:
 636 <ProgramListing>
 637   module Orphan where
 638     instance C a =&gt; D (T a) where ...
 639     class C a where ...
 640 </ProgramListing>
 641 Here, neither D nor T is declared in module Orphan.
 642 We call such modules ``orphan modules'',
 643 defined thus:</para>
 644 <itemizedlist>
 645   <listitem> <para> An <emphasis>orphan module</emphasis>
 646   <indexterm><primary>orphan module</primary></indexterm>
 647   contains at least one <emphasis>orphan instance</emphasis> or at
 648   least one <emphasis>orphan rule</emphasis>.</para> </listitem>
 649
 650   <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
 651   <indexterm><primary>orphan instance</primary></indexterm>
 652   none of the type constructors
 653   or classes mentioned in the instance head (the part after the ``<literal>=&gt;</literal>'') are declared
 654   in M.</para>
 655
 656   <para> Only the instance head counts.  In the example above, it is not good enough for C's declaration
 657   to be in module A; it must be the declaration of D or T.</para>
 658   </listitem>
 659
 660   <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
 661   <indexterm><primary>orphan rule</primary></indexterm>
 662   if none of the variables, type constructors,
 663   or classes that are free in the left hand side of the rule are declared in M.
 664   </para> </listitem>
 665  </itemizedlist>
 666
 667
 668 <para> GHC identifies orphan modules, and visits the interface file of
 669 every orphan module below the module being compiled.  This is usually
 670 wasted work, but there is no avoiding it.  You should therefore do
 671 your best to have as few orphan modules as possible.
 672
 673 </para><para>
 674 You can identify an orphan module by looking in its interface file, M.hi.  If there is a ``!'' on
 675 the first line, GHC considers it an orphan module.
 676 </para>
 677 </sect2>
 678
 679   </sect1>
 680
 681 <!-- Emacs stuff:
 682      ;;; Local Variables: ***
 683      ;;; mode: sgml ***
 684      ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
 685      ;;; End: ***
 686  -->