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