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