docs/users_guide/separate_compilation.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2   <sect1 id="separate-compilation">
   3     <title>Filenames and separate compilation</title>
   4
   5     <indexterm><primary>separate compilation</primary></indexterm>
   6     <indexterm><primary>recompilation checker</primary></indexterm>
   7     <indexterm><primary>make and recompilation</primary></indexterm>
   8
   9     <para>This section describes what files GHC expects to find, what
  10     files it creates, where these files are stored, and what options
  11     affect this behaviour.</para>
  12
  13     <para>Note that this section is written with
  14     <firstterm>hierarchical modules</firstterm> in mind (see <xref
  15     linkend="hierarchical-modules"/>); hierarchical modules are an
  16     extension to Haskell 98 which extends the lexical syntax of
  17     module names to include a dot &lsquo;.&rsquo;.  Non-hierarchical
  18     modules are thus a special case in which none of the module names
  19     contain dots.</para>
  20
  21     <para>Pathname conventions vary from system to system.  In
  22     particular, the directory separator is
  23     &lsquo;<literal>/</literal>&rsquo; on Unix systems and
  24     &lsquo;<literal>\</literal>&rsquo; on Windows systems.  In the
  25     sections that follow, we shall consistently use
  26     &lsquo;<literal>/</literal>&rsquo; as the directory separator;
  27     substitute this for the appropriate character for your
  28     system.</para>
  29
  30     <sect2 id="source-files">
  31       <title>Haskell source files</title>
  32
  33       <indexterm><primary>filenames</primary></indexterm>
  34
  35       <para>Each Haskell source module should be placed in a file on
  36       its own.</para>
  37
  38       <para>Usually, the file should be named after the module name,
  39       replacing dots in the module name by directory separators.  For
  40       example, on a Unix system, the module <literal>A.B.C</literal>
  41       should be placed in the file <literal>A/B/C.hs</literal>,
  42       relative to some base directory.  If the module is not going to
  43       be imported by another module (<literal>Main</literal>, for
  44       example), then you are free to use any filename for it.</para>
  45
  46       <indexterm><primary>unicode</primary></indexterm>
  47
  48       <para> GHC assumes that source files are
  49       ASCII<indexterm><primary>ASCII</primary></indexterm> or
  50       UTF-8<indexterm><primary>UTF-8</primary></indexterm> only, other
  51       encodings<indexterm><primary>encoding</primary></indexterm> are
  52       not recognised.  However, invalid UTF-8 sequences will be
  53       ignored in comments, so it is possible to use other encodings
  54       such as
  55       Latin-1<indexterm><primary>Latin-1</primary></indexterm>, as
  56       long as the non-comment source code is ASCII only.</para>
  57     </sect2>
  58
  59     <sect2 id="output-files">
  60       <title>Output files</title>
  61
  62       <indexterm><primary>interface files</primary></indexterm>
  63       <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
  64       <indexterm><primary>object files</primary></indexterm>
  65       <indexterm><primary><literal>.o</literal> files</primary></indexterm>
  66
  67       <para>When asked to compile a source file, GHC normally
  68       generates two files: an <firstterm>object file</firstterm>, and
  69       an <firstterm>interface file</firstterm>. </para>
  70
  71       <para>The object file, which normally ends in a
  72       <literal>.o</literal> suffix, contains the compiled code for the
  73       module.</para>
  74
  75       <para>The interface file,
  76       which normally ends in a <literal>.hi</literal> suffix, contains
  77       the information that GHC needs in order to compile further
  78       modules that depend on this module.  It contains things like the
  79       types of exported functions, definitions of data types, and so
  80       on.  It is stored in a binary format, so don't try to read one;
  81       use the <option>--show-iface</option> option instead (see <xref
  82       linkend="hi-options"/>).</para>
  83
  84       <para>You should think of the object file and the interface file as a
  85       pair, since the interface file is in a sense a compiler-readable
  86       description of the contents of the object file.  If the
  87       interface file and object file get out of sync for any reason,
  88       then the compiler may end up making assumptions about the object
  89       file that aren't true; trouble will almost certainly follow.
  90       For this reason, we recommend keeping object files and interface
  91       files in the same place (GHC does this by default, but it is
  92       possible to override the defaults as we'll explain
  93       shortly).</para>
  94
  95       <para>Every module has a <emphasis>module name</emphasis>
  96       defined in its source code (<literal>module A.B.C where
  97       ...</literal>).</para>
  98
  99       <para>The name of the object file generated by GHC is derived
 100       according to the following rules, where
 101       <replaceable>osuf</replaceable> is the object-file suffix (this
 102       can be changed with the <option>-osuf</option> option).</para>
 103
 104       <itemizedlist>
 105         <listitem>
 106           <para>If there is no <option>-odir</option> option (the
 107           default), then the object filename is derived from the
 108           source filename (ignoring the module name) by replacing the
 109           suffix with <replaceable>osuf</replaceable>.</para>
 110         </listitem>
 111         <listitem>
 112           <para>If
 113           <option>-odir</option>&nbsp;<replaceable>dir</replaceable>
 114           has been specified, then the object filename is
 115           <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>,
 116           where <replaceable>mod</replaceable> is the module name with
 117           dots replaced by slashes.  GHC will silently create the necessary directory
 118           structure underneath <replaceable>dir</replaceable>, if it does not
 119           already exist.</para>
 120         </listitem>
 121       </itemizedlist>
 122
 123       <para>The name of the interface file is derived using the same
 124       rules, except that the suffix is
 125       <replaceable>hisuf</replaceable> (<literal>.hi</literal> by
 126       default) instead of <replaceable>osuf</replaceable>, and the
 127       relevant options are <option>-hidir</option> and
 128       <option>-hisuf</option> instead of <option>-odir</option> and
 129       <option>-osuf</option> respectively.</para>
 130
 131       <para>For example, if GHC compiles the module
 132       <literal>A.B.C</literal> in the file
 133       <filename>src/A/B/C.hs</filename>, with no
 134       <literal>-odir</literal> or <literal>-hidir</literal> flags, the
 135       interface file will be put in <literal>src/A/B/C.hi</literal>
 136       and the object file in <literal>src/A/B/C.o</literal>.</para>
 137
 138       <para>For any module that is imported, GHC requires that the
 139       name of the module in the import statement exactly matches the
 140       name of the module in the interface file (or source file) found
 141       using the strategy specified in <xref linkend="search-path"/>.
 142       This means that for most modules, the source file name should
 143       match the module name.</para>
 144
 145       <para>However, note that it is reasonable to have a module
 146       <literal>Main</literal> in a file named
 147       <filename>foo.hs</filename>, but this only works because GHC
 148       never needs to search for the interface for module
 149       <literal>Main</literal> (because it is never imported).  It is
 150       therefore possible to have several <literal>Main</literal>
 151       modules in separate source files in the same directory, and GHC
 152       will not get confused.</para>
 153
 154       <para>In batch compilation mode, the name of the object file can
 155       also be overridden using the <option>-o</option> option, and the
 156       name of the interface file can be specified directly using the
 157       <option>-ohi</option> option.</para>
 158     </sect2>
 159
 160     <sect2 id="search-path">
 161       <title>The search path</title>
 162
 163       <indexterm><primary>search path</primary>
 164       </indexterm>
 165       <indexterm><primary>interface files, finding them</primary></indexterm>
 166       <indexterm><primary>finding interface files</primary></indexterm>
 167
 168       <para>In your program, you import a module
 169       <literal>Foo</literal> by saying <literal>import Foo</literal>.
 170       In <option>--make</option> mode or GHCi, GHC will look for a
 171       source file for <literal>Foo</literal> and arrange to compile it
 172       first.  Without <option>--make</option>, GHC will look for the
 173       interface file for <literal>Foo</literal>, which should have
 174       been created by an earlier compilation of
 175       <literal>Foo</literal>.  GHC uses the same strategy in each of
 176       these cases for finding the appropriate file.</para>
 177
 178       <para>This strategy is as follows: GHC keeps a list of
 179       directories called the <firstterm>search path</firstterm>.  For
 180       each of these directories, it tries appending
 181       <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
 182       to the directory, and checks whether the file exists.  The value
 183       of <replaceable>basename</replaceable> is the module name with
 184       dots replaced by the directory separator ('/' or '\', depending
 185       on the system), and <replaceable>extension</replaceable> is a
 186       source extension (<literal>hs</literal>, <literal>lhs</literal>)
 187       if we are in <option>--make</option> mode and GHCi, or
 188       <replaceable>hisuf</replaceable> otherwise.</para>
 189
 190       <para>For example, suppose the search path contains directories
 191       <literal>d1</literal>, <literal>d2</literal>, and
 192       <literal>d3</literal>, and we are in <literal>--make</literal>
 193       mode looking for the source file for a module
 194       <literal>A.B.C</literal>.  GHC will look in
 195       <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
 196       <literal>d2/A/B/C.hs</literal>, and so on.</para>
 197
 198       <para>The search path by default contains a single directory:
 199       <quote>.</quote> (i.e. the current directory).  The following
 200       options can be used to add to or change the contents of the
 201       search path:</para>
 202
 203       <variablelist>
 204         <varlistentry>
 205           <term><option>-i<replaceable>dirs</replaceable></option></term>
 206           <listitem>
 207             <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
 208             </primary></indexterm>This flag appends a colon-separated
 209             list of <filename>dirs</filename> to the search path.</para>
 210           </listitem>
 211         </varlistentry>
 212
 213         <varlistentry>
 214           <term><option>-i</option></term>
 215           <listitem>
 216             <para>resets the search path back to nothing.</para>
 217           </listitem>
 218         </varlistentry>
 219       </variablelist>
 220
 221       <para>This isn't the whole story: GHC also looks for modules in
 222       pre-compiled libraries, known as packages.  See the section on
 223       packages (<xref linkend="packages"/>), for details.</para>
 224     </sect2>
 225
 226     <sect2 id="options-output">
 227       <title>Redirecting the compilation output(s)</title>
 228
 229       <indexterm><primary>output-directing options</primary></indexterm>
 230       <indexterm><primary>redirecting compilation output</primary></indexterm>
 231
 232       <variablelist>
 233         <varlistentry>
 234           <term>
 235             <option>-o</option> <replaceable>file</replaceable>
 236             <indexterm><primary><option>-o</option></primary></indexterm>
 237           </term>
 238           <listitem>
 239             <para>GHC's compiled output normally goes into a
 240             <filename>.hc</filename>, <filename>.o</filename>, etc.,
 241             file, depending on the last-run compilation phase.  The
 242             option <option>-o <replaceable>file</replaceable></option>
 243             re-directs the output of that last-run phase to
 244             <replaceable>file</replaceable>.</para>
 245
 246             <para>Note: this &ldquo;feature&rdquo; can be
 247             counterintuitive: <command>ghc -C -o foo.o
 248             foo.hs</command> will put the intermediate C code in the
 249             file <filename>foo.o</filename>, name
 250             notwithstanding!</para>
 251
 252             <para>This option is most often used when creating an
 253             executable file, to set the filename of the executable.
 254             For example:
 255 <screen>   ghc -o prog --make Main</screen>
 256
 257             will compile the program starting with module
 258             <literal>Main</literal>  and put the executable in the
 259             file <literal>prog</literal>.</para>
 260
 261             <para>Note: on Windows, if the result is an executable
 262             file, the extension "<filename>.exe</filename>" is added
 263             if the specified filename does not already have an
 264             extension.  Thus
 265 <programlisting>
 266    ghc -o foo Main.hs
 267 </programlisting>
 268           will compile and link the module
 269           <filename>Main.hs</filename>, and put the resulting
 270           executable in <filename>foo.exe</filename> (not
 271           <filename>foo</filename>).</para>
 272
 273           <para>If you use <command>ghc --make</command> and you don't
 274           use the <option>-o</option>, the name GHC will choose
 275           for the executable will be based on the name of the file
 276           containing the module <literal>Main</literal>.
 277           Note that with GHC the <literal>Main</literal> module doesn't
 278           have to be put in file <filename>Main.hs</filename>.
 279           Thus both
 280 <programlisting>
 281    ghc --make Prog
 282 </programlisting>
 283           and
 284 <programlisting>
 285    ghc --make Prog.hs
 286 </programlisting>
 287           will produce <filename>Prog</filename> (or
 288           <filename>Prog.exe</filename> if you are on Windows).</para>
 289           </listitem>
 290         </varlistentry>
 291
 292         <varlistentry>
 293           <term>
 294             <option>-odir</option> <replaceable>dir</replaceable>
 295             <indexterm><primary><option>-odir</option></primary></indexterm>
 296           </term>
 297           <listitem>
 298             <para>Redirects object files to directory
 299             <replaceable>dir</replaceable>.  For example:</para>
 300
 301 <screen>
 302 $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
 303 </screen>
 304
 305             <para>The object files, <filename>Foo.o</filename>,
 306             <filename>Bar.o</filename>, and
 307             <filename>Bumble.o</filename> would be put into a
 308             subdirectory named after the architecture of the executing
 309             machine (<filename>x86</filename>,
 310             <filename>mips</filename>, etc).</para>
 311
 312             <para>Note that the <option>-odir</option> option does
 313             <emphasis>not</emphasis> affect where the interface files
 314             are put; use the <option>-hidir</option> option for that.
 315             In the above example, they would still be put in
 316             <filename>parse/Foo.hi</filename>,
 317             <filename>parse/Bar.hi</filename>, and
 318             <filename>gurgle/Bumble.hi</filename>.</para>
 319           </listitem>
 320         </varlistentry>
 321
 322         <varlistentry>
 323           <term>
 324             <option>-ohi</option>  <replaceable>file</replaceable>
 325             <indexterm><primary><option>-ohi</option></primary></indexterm>
 326           </term>
 327           <listitem>
 328             <para>The interface output may be directed to another file
 329             <filename>bar2/Wurble.iface</filename> with the option
 330             <option>-ohi bar2/Wurble.iface</option> (not
 331             recommended).</para>
 332
 333             <para>WARNING: if you redirect the interface file
 334             somewhere that GHC can't find it, then the recompilation
 335             checker may get confused (at the least, you won't get any
 336             recompilation avoidance).  We recommend using a
 337             combination of <option>-hidir</option> and
 338             <option>-hisuf</option> options instead, if
 339             possible.</para>
 340
 341             <para>To avoid generating an interface at all, you could
 342             use this option to redirect the interface into the bit
 343             bucket: <literal>-ohi /dev/null</literal>, for
 344             example.</para>
 345           </listitem>
 346         </varlistentry>
 347
 348         <varlistentry>
 349           <term>
 350             <option>-hidir</option>  <replaceable>dir</replaceable>
 351             <indexterm><primary><option>-hidir</option></primary></indexterm>
 352           </term>
 353           <listitem>
 354             <para>Redirects all generated interface files into
 355             <replaceable>dir</replaceable>, instead of the
 356             default.</para>
 357           </listitem>
 358         </varlistentry>
 359
 360         <varlistentry>
 361           <term>
 362             <option>-stubdir</option>  <replaceable>dir</replaceable>
 363             <indexterm><primary><option>-stubdir</option></primary></indexterm>
 364           </term>
 365           <listitem>
 366             <para>Redirects all generated FFI stub files into
 367             <replaceable>dir</replaceable>.  Stub files are generated when the
 368             Haskell source contains a <literal>foreign export</literal> or
 369             <literal>foreign import "&amp;wrapper"</literal> declaration (see <xref
 370               linkend="foreign-export-ghc" />).  The <option>-stubdir</option>
 371               option behaves in exactly the same way as <option>-odir</option>
 372               and <option>-hidir</option> with respect to hierarchical
 373             modules.</para>
 374           </listitem>
 375         </varlistentry>
 376
 377         <varlistentry>
 378           <term>
 379             <option>-osuf</option> <replaceable>suffix</replaceable>
 380             <indexterm><primary><option>-osuf</option></primary></indexterm>
 381           </term>
 382           <term>
 383             <option>-hisuf</option> <replaceable>suffix</replaceable>
 384             <indexterm><primary><option>-hisuf</option></primary></indexterm>
 385           </term>
 386           <term>
 387             <option>-hcsuf</option> <replaceable>suffix</replaceable>
 388             <indexterm><primary><option>-hcsuf</option></primary></indexterm>
 389           </term>
 390           <listitem>
 391             <para>The <option>-osuf</option>
 392             <replaceable>suffix</replaceable> will change the
 393             <literal>.o</literal> file suffix for object files to
 394             whatever you specify.  We use this when compiling
 395             libraries, so that objects for the profiling versions of
 396             the libraries don't clobber the normal ones.</para>
 397
 398             <para>Similarly, the <option>-hisuf</option>
 399             <replaceable>suffix</replaceable> will change the
 400             <literal>.hi</literal> file suffix for non-system
 401             interface files (see <xref linkend="hi-options"/>).</para>
 402
 403             <para>Finally, the option <option>-hcsuf</option>
 404             <replaceable>suffix</replaceable> will change the
 405             <literal>.hc</literal> file suffix for compiler-generated
 406             intermediate C files.</para>
 407
 408             <para>The <option>-hisuf</option>/<option>-osuf</option>
 409             game is particularly useful if you want to compile a
 410             program both with and without profiling, in the same
 411             directory.  You can say:
 412             <screen>
 413               ghc ...</screen>
 414             to get the ordinary version, and
 415             <screen>
 416               ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen>
 417             to get the profiled version.</para>
 418           </listitem>
 419         </varlistentry>
 420       </variablelist>
 421     </sect2>
 422
 423     <sect2 id="keeping-intermediates">
 424       <title>Keeping Intermediate Files</title>
 425       <indexterm><primary>intermediate files, saving</primary>
 426       </indexterm>
 427       <indexterm><primary><literal>.hc</literal> files, saving</primary>
 428       </indexterm>
 429       <indexterm><primary><literal>.s</literal> files, saving</primary>
 430       </indexterm>
 431
 432       <para>The following options are useful for keeping certain
 433       intermediate files around, when normally GHC would throw these
 434       away after compilation:</para>
 435
 436       <variablelist>
 437         <varlistentry>
 438           <term>
 439             <option>-keep-hc-files</option>
 440             <indexterm><primary><option>-keep-hc-files</option></primary></indexterm>
 441           </term>
 442           <listitem>
 443             <para>Keep intermediate <literal>.hc</literal> files when
 444             doing <literal>.hs</literal>-to-<literal>.o</literal>
 445             compilations via C (NOTE: <literal>.hc</literal> files
 446             aren't generated when using the native code generator, you
 447             may need to use <option>-fvia-C</option> to force them
 448             to be produced).</para>
 449           </listitem>
 450         </varlistentry>
 451
 452         <varlistentry>
 453           <term>
 454             <option>-keep-s-files</option>
 455             <indexterm><primary><option>-keep-s-files</option></primary></indexterm>
 456           </term>
 457           <listitem>
 458             <para>Keep intermediate <literal>.s</literal> files.</para>
 459           </listitem>
 460         </varlistentry>
 461
 462         <varlistentry>
 463           <term>
 464             <option>-keep-raw-s-files</option>
 465             <indexterm><primary><option>-keep-raw-s-files</option></primary></indexterm>
 466           </term>
 467           <listitem>
 468             <para>Keep intermediate <literal>.raw-s</literal> files.
 469             These are the direct output from the C compiler, before
 470             GHC does &ldquo;assembly mangling&rdquo; to produce the
 471             <literal>.s</literal> file.  Again, these are not produced
 472             when using the native code generator.</para>
 473           </listitem>
 474         </varlistentry>
 475
 476         <varlistentry>
 477           <term>
 478             <option>-keep-tmp-files</option>
 479             <indexterm><primary><option>-keep-tmp-files</option></primary></indexterm>
 480             <indexterm><primary>temporary files</primary><secondary>keeping</secondary></indexterm>
 481           </term>
 482           <listitem>
 483             <para>Instructs the GHC driver not to delete any of its
 484             temporary files, which it normally keeps in
 485             <literal>/tmp</literal> (or possibly elsewhere; see <xref
 486             linkend="temp-files"/>).  Running GHC with
 487             <option>-v</option> will show you what temporary files
 488             were generated along the way.</para>
 489           </listitem>
 490         </varlistentry>
 491       </variablelist>
 492     </sect2>
 493
 494     <sect2 id="temp-files">
 495       <title>Redirecting temporary files</title>
 496
 497       <indexterm>
 498         <primary>temporary files</primary>
 499         <secondary>redirecting</secondary>
 500       </indexterm>
 501
 502       <variablelist>
 503         <varlistentry>
 504           <term>
 505             <option>-tmpdir</option>
 506             <indexterm><primary><option>-tmpdir</option></primary></indexterm>
 507           </term>
 508           <listitem>
 509             <para>If you have trouble because of running out of space
 510             in <filename>/tmp</filename> (or wherever your
 511             installation thinks temporary files should go), you may
 512             use the <option>-tmpdir
 513             &lt;dir&gt;</option><indexterm><primary>-tmpdir
 514             &lt;dir&gt; option</primary></indexterm> option to specify
 515             an alternate directory.  For example, <option>-tmpdir
 516             .</option> says to put temporary files in the current
 517             working directory.</para>
 518
 519             <para>Alternatively, use your <constant>TMPDIR</constant>
 520             environment variable.<indexterm><primary>TMPDIR
 521             environment variable</primary></indexterm> Set it to the
 522             name of the directory where temporary files should be put.
 523             GCC and other programs will honour the
 524             <constant>TMPDIR</constant> variable as well.</para>
 525
 526             <para>Even better idea: Set the
 527             <constant>DEFAULT_TMPDIR</constant> make variable when
 528             building GHC, and never worry about
 529             <constant>TMPDIR</constant> again. (see the build
 530             documentation).</para>
 531           </listitem>
 532         </varlistentry>
 533       </variablelist>
 534     </sect2>
 535
 536     <sect2 id="hi-options">
 537       <title>Other options related to interface files</title>
 538       <indexterm><primary>interface files, options</primary></indexterm>
 539
 540       <variablelist>
 541         <varlistentry>
 542           <term>
 543             <option>-ddump-hi</option>
 544             <indexterm><primary><option>-ddump-hi</option></primary></indexterm>
 545           </term>
 546           <listitem>
 547             <para>Dumps the new interface to standard output.</para>
 548           </listitem>
 549         </varlistentry>
 550
 551         <varlistentry>
 552           <term>
 553             <option>-ddump-hi-diffs</option>
 554             <indexterm><primary><option>-ddump-hi-diffs</option></primary></indexterm>
 555           </term>
 556           <listitem>
 557             <para>The compiler does not overwrite an existing
 558             <filename>.hi</filename> interface file if the new one is
 559             the same as the old one; this is friendly to
 560             <command>make</command>.  When an interface does change,
 561             it is often enlightening to be informed.  The
 562             <option>-ddump-hi-diffs</option> option will make GHC run
 563             <command>diff</command> on the old and new
 564             <filename>.hi</filename> files.</para>
 565           </listitem>
 566         </varlistentry>
 567
 568         <varlistentry>
 569           <term>
 570             <option>-ddump-minimal-imports</option>
 571             <indexterm><primary><option>-ddump-minimal-imports</option></primary></indexterm>
 572           </term>
 573           <listitem>
 574             <para>Dump to the file "M.imports" (where M is the module
 575             being compiled) a "minimal" set of import declarations.
 576             You can safely replace all the import declarations in
 577             "M.hs" with those found in "M.imports".  Why would you
 578             want to do that?  Because the "minimal" imports (a) import
 579             everything explicitly, by name, and (b) import nothing
 580             that is not required.  It can be quite painful to maintain
 581             this property by hand, so this flag is intended to reduce
 582             the labour.</para>
 583           </listitem>
 584         </varlistentry>
 585
 586         <varlistentry>
 587           <term>
 588             <option>--show-iface</option> <replaceable>file</replaceable>
 589             <indexterm><primary><option>--show-iface</option></primary></indexterm>
 590           </term>
 591           <listitem>
 592             <para>Where <replaceable>file</replaceable> is the name of
 593             an interface file, dumps the contents of that interface in
 594             a human-readable (ish) format.</para>
 595           </listitem>
 596         </varlistentry>
 597       </variablelist>
 598     </sect2>
 599
 600     <sect2 id="recomp">
 601       <title>The recompilation checker</title>
 602
 603       <indexterm><primary>recompilation checker</primary></indexterm>
 604
 605       <variablelist>
 606         <varlistentry>
 607           <term>
 608             <option>-fforce-recomp</option>
 609             <indexterm><primary><option>-fforce-recomp</option></primary></indexterm>
 610             <indexterm><primary><option>-fno-force-recomp</option></primary></indexterm>
 611           </term>
 612           <listitem>
 613             <para>Turn off recompilation checking (which is on by
 614             default).  Recompilation checking normally stops
 615             compilation early, leaving an existing
 616             <filename>.o</filename> file in place, if it can be
 617             determined that the module does not need to be
 618             recompiled.</para>
 619           </listitem>
 620         </varlistentry>
 621       </variablelist>
 622
 623       <para>In the olden days, GHC compared the newly-generated
 624       <filename>.hi</filename> file with the previous version; if they
 625       were identical, it left the old one alone and didn't change its
 626       modification date.  In consequence, importers of a module with
 627       an unchanged output <filename>.hi</filename> file were not
 628       recompiled.</para>
 629
 630       <para>This doesn't work any more.  Suppose module
 631       <literal>C</literal> imports module <literal>B</literal>, and
 632       <literal>B</literal> imports module <literal>A</literal>.  So
 633       changes to module <literal>A</literal> might require module
 634       <literal>C</literal> to be recompiled, and hence when
 635       <filename>A.hi</filename> changes we should check whether
 636       <literal>C</literal> should be recompiled.  However, the
 637       dependencies of <literal>C</literal> will only list
 638       <literal>B.hi</literal>, not <literal>A.hi</literal>, and some
 639       changes to <literal>A</literal> (changing the definition of a
 640       function that appears in an inlining of a function exported by
 641       <literal>B</literal>, say) may conceivably not change
 642       <filename>B.hi</filename> one jot.  So now&hellip;</para>
 643
 644       <para>GHC keeps a version number on each interface file, and on
 645       each type signature within the interface file.  It also keeps in
 646       every interface file a list of the version numbers of everything
 647       it used when it last compiled the file.  If the source file's
 648       modification date is earlier than the <filename>.o</filename>
 649       file's date (i.e. the source hasn't changed since the file was
 650       last compiled), and the recompilation checking is on, GHC will be
 651       clever.  It compares the version numbers on the things it needs
 652       this time with the version numbers on the things it needed last
 653       time (gleaned from the interface file of the module being
 654       compiled); if they are all the same it stops compiling rather
 655       early in the process saying &ldquo;Compilation IS NOT
 656       required&rdquo;.  What a beautiful sight!</para>
 657
 658       <para>Patrick Sansom had a workshop paper about how all this is
 659       done (though the details have changed quite a bit). <ulink
 660       url="mailto:sansom@dcs.gla.ac.uk">Ask him</ulink> if you want a
 661       copy.</para>
 662
 663     </sect2>
 664
 665     <sect2 id="mutual-recursion">
 666       <title>How to compile mutually recursive modules</title>
 667
 668       <indexterm><primary>module system, recursion</primary></indexterm>
 669       <indexterm><primary>recursion, between modules</primary></indexterm>
 670
 671       <para>GHC supports the compilation of mutually recursive modules.
 672       This section explains how.</para>
 673
 674       <para>Every cycle in the module import graph must be broken by a <filename>hs-boot</filename> file.
 675       Suppose that modules <filename>A.hs</filename> and <filename>B.hs</filename> are Haskell source files,
 676       thus:
 677 <programlisting>
 678 module A where
 679     import B( TB(..) )
 680
 681     newtype TA = MkTA Int
 682
 683     f :: TB -&#62; TA
 684     f (MkTB x) = MkTA x
 685
 686 module B where
 687     import {-# SOURCE #-} A( TA(..) )
 688
 689     data TB = MkTB !Int
 690
 691     g :: TA -&#62; TB
 692     g (MkTA x) = MkTB x
 693 </programlisting>
 694 <indexterm><primary><literal>hs-boot</literal>
 695       files</primary></indexterm> <indexterm><primary>importing,
 696       <literal>hi-boot</literal> files</primary></indexterm>
 697 Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports
 698 <filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the
 699 circular dependency.  For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
 700 in this way there must exist a souce file <literal>A.hs-boot</literal>.  This file contains an abbreviated
 701 version of <filename>A.hs</filename>, thus:
 702 <programlisting>
 703 module A where
 704     newtype TA = MkTA Int
 705 </programlisting>
 706 </para>
 707 <para>To compile these three files, issue the following commands:
 708 <programlisting>
 709   ghc -c A.hs-boot    -- Poduces A.hi-boot, A.o-boot
 710   ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
 711   ghc -c A.hs         -- Consumes B.hi, produces A.hi, A.o
 712   ghc -o foo A.o B.o  -- Linking the program
 713 </programlisting>
 714 </para>
 715 <para>There are several points to note here:
 716 <itemizedlist>
 717 <listitem>
 718   <para>The file <filename>A.hs-boot</filename> is a programmer-written source file.
 719   It must live in the same directory as its parent source file <filename>A.hs</filename>.
 720   Currently, if you use a literate source file <filename>A.lhs</filename> you must
 721   also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa.
 722   </para></listitem>
 723
 724 <listitem><para>
 725   A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
 726 <programlisting>
 727   ghc -c A.hs-boot
 728 </programlisting>
 729 When a hs-boot file <filename>A.hs-boot</filename>
 730    is compiled, it is checked for scope and type errors.
 731    When its parent module <filename>A.hs</filename> is compiled, the two are compared, and
 732    an error is reported if the two are inconsistent.
 733    </para></listitem>
 734
 735         <listitem>
 736           <para> Just as compiling <filename>A.hs</filename> produces an
 737             interface file <filename>A.hi</filename>, and an object file
 738             <filename>A.o</filename>, so compiling
 739             <filename>A.hs-boot</filename> produces an interface file
 740             <filename>A.hi-boot</filename>, and an pseudo-object file
 741             <filename>A.o-boot</filename>: </para>
 742
 743           <itemizedlist>
 744             <listitem>
 745               <para>The pseudo-object file <filename>A.o-boot</filename> is
 746                 empty (don't link it!), but it is very useful when using a
 747                 Makefile, to record when the <filename>A.hi-boot</filename> was
 748                 last brought up to date (see <xref
 749                   linkend="using-make"/>).</para>
 750             </listitem>
 751
 752             <listitem>
 753               <para>The <filename>hi-boot</filename> generated by compiling a
 754                 <filename>hs-boot</filename> file is in the same
 755                 machine-generated binary format as any other GHC-generated
 756                 interface file (e.g. <filename>B.hi</filename>). You can
 757                 display its contents with <command>ghc
 758                   --show-iface</command>. If you specify a directory for
 759                 interface files, the <option>-ohidir</option> flag, then that
 760                 affects <filename>hi-boot</filename> files
 761                 too.</para>
 762             </listitem>
 763           </itemizedlist>
 764         </listitem>
 765
 766    <listitem><para> If hs-boot files are considered distinct from their parent source
 767    files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the
 768    hs-boot file, then the module import graph must have no cycles.  The command
 769    <command>ghc -M</command> will report an error if a cycle is found.
 770    </para></listitem>
 771
 772    <listitem><para> A module <literal>M</literal> that is
 773    <literal>{-# SOURCE #-}</literal>-imported in a program will usually also be
 774    ordinarily imported elsewhere.  If not, <command>ghc --make</command>
 775    automatically adds <literal>M</literal> to the set of moudles it tries to
 776    compile and link, to ensure that <literal>M</literal>'s implementation is included in
 777    the final program.
 778    </para></listitem>
 779 </itemizedlist>
 780 </para>
 781 <para>
 782 A hs-boot file need only contain the bare
 783       minimum of information needed to get the bootstrapping process
 784       started.  For example, it doesn't need to contain declarations
 785       for <emphasis>everything</emphasis> that module
 786       <literal>A</literal> exports, only the things required by the
 787       module(s) that import <literal>A</literal> recursively.</para>
 788 <para>A hs-boot file is written in a subset of Haskell:
 789 <itemizedlist>
 790 <listitem><para> The module header (including the export list), and import statements, are exactly as in
 791 Haskell, and so are the scoping rules.
 792    Hence, to mention a non-Prelude type or class, you must import it.</para></listitem>
 793
 794 <listitem><para> There must be no value declarations, but there can be type signatures for
 795 values.  For example:
 796 <programlisting>
 797   double :: Int -&#62; Int
 798 </programlisting>
 799 </para></listitem>
 800 <listitem><para> Fixity declarations are exactly as in Haskell.</para></listitem>
 801 <listitem><para> Type synonym declarations are exactly as in Haskell.</para></listitem>
 802 <listitem><para> A data type declaration can either be given in full, exactly as in Haskell, or it
 803 can be given abstractly, by omitting the '=' sign and everything that follows.  For example:
 804 <programlisting>
 805   data T a b
 806 </programlisting>
 807             In a <emphasis>source</emphasis> program
 808           this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>),
 809           but in an hi-boot file it means "I don't know or care what the constructors are".
 810             This is the most common form of data type declaration, because it's easy to get right.
 811           You <emphasis>can</emphasis> also write out the constructors but, if you do so, you must write
 812           it out precisely as in its real definition.</para>
 813           <para>
 814             If you do not write out the constructors, you may need to give a kind
 815             annotation (<xref linkend="kinding"/>), to tell
 816             GHC the kind of the type variable, if it is not "*".  (In source files, this is worked out
 817             from the way the type variable is used in the constructors.)  For example:
 818 <programlisting>
 819   data R (x :: * -&#62; *) y
 820 </programlisting>
 821 You cannot use <literal>deriving</literal> on a data type declaration; write in
 822 <literal>instance</literal> declaration instead.
 823 </para></listitem>
 824 <listitem><para> Class declarations is exactly as in Haskell, except that you may not put
 825 default method declarations.  You can also omit all the superclasses and class
 826 methods entirely; but you must either omit them all or put them all in.
 827 </para></listitem>
 828 <listitem><para> You can include instance declarations just as in Haskell; but omit the "where" part.
 829  </para></listitem>
 830 </itemizedlist>
 831 </para>
 832     </sect2>
 833
 834
 835     <sect2 id="using-make">
 836       <title>Using <command>make</command></title>
 837
 838       <indexterm><primary><literal>make</literal></primary></indexterm>
 839
 840       <para>It is reasonably straightforward to set up a
 841       <filename>Makefile</filename> to use with GHC, assuming you name
 842       your source files the same as your modules.  Thus:</para>
 843
 844 <programlisting>
 845 HC      = ghc
 846 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
 847
 848 SRCS = Main.lhs Foo.lhs Bar.lhs
 849 OBJS = Main.o   Foo.o   Bar.o
 850
 851 .SUFFIXES : .o .hs .hi .lhs .hc .s
 852
 853 cool_pgm : $(OBJS)
 854         rm -f $@
 855         $(HC) -o $@ $(HC_OPTS) $(OBJS)
 856
 857 # Standard suffix rules
 858 .o.hi:
 859         @:
 860
 861 .lhs.o:
 862         $(HC) -c $&#60; $(HC_OPTS)
 863
 864 .hs.o:
 865         $(HC) -c $&#60; $(HC_OPTS)
 866
 867 .o-boot.hi-boot:
 868         @:
 869
 870 .lhs-boot.o-boot:
 871         $(HC) -c $&#60; $(HC_OPTS)
 872
 873 .hs-boot.o-boot:
 874         $(HC) -c $&#60; $(HC_OPTS)
 875
 876 # Inter-module dependencies
 877 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 878 Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
 879 </programlisting>
 880
 881       <para>(Sophisticated <command>make</command> variants may
 882       achieve some of the above more elegantly.  Notably,
 883       <command>gmake</command>'s pattern rules let you write the more
 884       comprehensible:</para>
 885
 886 <programlisting>
 887 %.o : %.lhs
 888         $(HC) -c $&#60; $(HC_OPTS)
 889 </programlisting>
 890
 891       <para>What we've shown should work with any
 892       <command>make</command>.)</para>
 893
 894       <para>Note the cheesy <literal>.o.hi</literal> rule: It records
 895       the dependency of the interface (<filename>.hi</filename>) file
 896       on the source.  The rule says a <filename>.hi</filename> file
 897       can be made from a <filename>.o</filename> file by
 898       doing&hellip;nothing.  Which is true.</para>
 899       <para> Note that the suffix rules are all repeated twice, once
 900       for normal Haskell source files, and once for <filename>hs-boot</filename>
 901       files (see <xref linkend="mutual-recursion"/>).</para>
 902
 903       <para>Note also the inter-module dependencies at the end of the
 904       Makefile, which take the form
 905
 906 <programlisting>
 907 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 908 </programlisting>
 909
 910       They tell <command>make</command> that if any of
 911       <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
 912       <literal>Foo.s</literal> have an earlier modification date than
 913       <literal>Baz.hi</literal>, then the out-of-date file must be
 914       brought up to date.  To bring it up to date,
 915       <literal>make</literal> looks for a rule to do so; one of the
 916       preceding suffix rules does the job nicely.  These dependencies
 917       can be generated automatically by <command>ghc</command>; see
 918       <xref linkend="makefile-dependencies"/></para>
 919
 920  </sect2>
 921
 922       <sect2 id="makefile-dependencies">
 923         <title>Dependency generation</title>
 924         <indexterm><primary>dependencies in Makefiles</primary></indexterm>
 925         <indexterm><primary>Makefile dependencies</primary></indexterm>
 926
 927         <para>Putting inter-dependencies of the form <literal>Foo.o :
 928         Bar.hi</literal> into your <filename>Makefile</filename> by
 929         hand is rather error-prone.  Don't worry, GHC has support for
 930         automatically generating the required dependencies.  Add the
 931         following to your <filename>Makefile</filename>:</para>
 932
 933 <programlisting>
 934 depend :
 935         ghc -M $(HC_OPTS) $(SRCS)
 936 </programlisting>
 937
 938         <para>Now, before you start compiling, and any time you change
 939         the <literal>imports</literal> in your program, do
 940         <command>make depend</command> before you do <command>make
 941         cool&lowbar;pgm</command>.  The command <command>ghc -M</command> will
 942         append the needed dependencies to your
 943         <filename>Makefile</filename>.</para>
 944
 945         <para>In general, <command>ghc -M Foo</command> does the following.
 946         For each module <literal>M</literal> in the set
 947         <literal>Foo</literal> plus all its imports (transitively),
 948         it adds to the Makefile:
 949         <itemizedlist>
 950         <listitem><para>A line recording the dependence of the object file on the source file.
 951 <programlisting>
 952 M.o : M.hs
 953 </programlisting>
 954 (or <literal>M.lhs</literal> if that is the filename you used).
 955        </para></listitem>
 956        <listitem><para> For each import declaration <literal>import X</literal> in <literal>M</literal>,
 957        a line recording the dependence of <literal>M</literal> on <literal>X</literal>:
 958 <programlisting>
 959 M.o : X.hi
 960 </programlisting></para></listitem>
 961        <listitem><para> For each import declaration <literal>import {-# SOURCE #-} X</literal> in <literal>M</literal>,
 962        a line recording the dependence of <literal>M</literal> on <literal>X</literal>:
 963 <programlisting>
 964 M.o : X.hi-boot
 965 </programlisting>
 966        (See <xref linkend="mutual-recursion"/> for details of
 967        <literal>hi-boot</literal> style interface files.)
 968       </para></listitem>
 969         </itemizedlist>
 970         If <literal>M</literal> imports multiple modules, then there will
 971        be multiple lines with <filename>M.o</filename> as the
 972        target.</para>
 973        <para>There is no need to list all of the source files as arguments to the <command>ghc -M</command> command;
 974        <command>ghc</command> traces the dependencies, just like <command>ghc --make</command>
 975        (a new feature in GHC 6.4).</para>
 976
 977     <para>Note that <literal>ghc -M</literal> needs to find a <emphasis>source
 978         file</emphasis> for each module in the dependency graph, so that it can
 979       parse the import declarations and follow dependencies.  Any pre-compiled
 980       modules without source files must therefore belong to a
 981       package<footnote><para>This is a change in behaviour relative to 6.2 and
 982         earlier.</para>
 983       </footnote>.</para>
 984
 985         <para>By default, <command>ghc -M</command> generates all the
 986         dependencies, and then concatenates them onto the end of
 987         <filename>makefile</filename> (or
 988         <filename>Makefile</filename> if <filename>makefile</filename>
 989         doesn't exist) bracketed by the lines "<literal>&num; DO NOT
 990         DELETE: Beginning of Haskell dependencies</literal>" and
 991         "<literal>&num; DO NOT DELETE: End of Haskell
 992         dependencies</literal>".  If these lines already exist in the
 993         <filename>makefile</filename>, then the old dependencies are
 994         deleted first.</para>
 995
 996         <para>Don't forget to use the same <option>-package</option>
 997         options on the <literal>ghc -M</literal> command line as you
 998         would when compiling; this enables the dependency generator to
 999         locate any imported modules that come from packages.  The
1000         package modules won't be included in the dependencies
1001         generated, though (but see the
1002         <option>&ndash;&ndash;include-pkg-deps</option> option below).</para>
1003
1004         <para>The dependency generation phase of GHC can take some
1005         additional options, which you may find useful.  For historical
1006         reasons, each option passed to the dependency generator from
1007         the GHC command line must be preceded by
1008         <literal>-optdep</literal>.  For example, to pass <literal>-f
1009         .depend</literal> to the dependency generator, you say
1010
1011 <screen>
1012 ghc -M -optdep-f -optdep.depend ...
1013 </screen>
1014
1015         The options which affect dependency generation are:</para>
1016
1017         <variablelist>
1018           <varlistentry>
1019             <term><option>-w</option></term>
1020             <listitem>
1021               <para>Turn off warnings about interface file shadowing.</para>
1022             </listitem>
1023           </varlistentry>
1024
1025           <varlistentry>
1026             <term><option>-v2</option></term>
1027             <listitem>
1028               <para>Print a full list of the module depenencies to stdout.
1029                     (This is the standard verbosity flag, so the list will
1030               also be displayed with <option>-v3</option> and
1031               <option>-v4</option>;
1032               <xref linkend ="options-help"/>.)</para>
1033             </listitem>
1034           </varlistentry>
1035
1036           <varlistentry>
1037             <term><option>-f</option> <replaceable>file</replaceable></term>
1038             <listitem>
1039               <para>Use <replaceable>file</replaceable> as the makefile,
1040               rather than <filename>makefile</filename> or
1041               <filename>Makefile</filename>.  If
1042               <replaceable>file</replaceable> doesn't exist,
1043               <command>mkdependHS</command> creates it.  We often use
1044               <option>-f .depend</option> to put the dependencies in
1045               <filename>.depend</filename> and then
1046               <command>include</command> the file
1047               <filename>.depend</filename> into
1048               <filename>Makefile</filename>.</para>
1049             </listitem>
1050           </varlistentry>
1051
1052 <!-- Retired with the move away from 'mkdependHS'.
1053           <varlistentry>
1054             <term><option>-o &lt;osuf&gt;</option></term>
1055             <listitem>
1056               <para>Use <filename>.&lt;osuf&gt;</filename> as the
1057               "target file" suffix ( default: <literal>o</literal>).
1058               Multiple <option>-o</option> flags are permitted
1059               (GHC2.05 onwards).  Thus "<option>-o hc -o o</option>"
1060               will generate dependencies for <filename>.hc</filename>
1061               and <filename>.o</filename> files.</para>
1062             </listitem>
1063           </varlistentry>
1064 -->
1065           <varlistentry>
1066             <term><option>-s &lt;suf&gt;</option></term>
1067             <listitem>
1068               <para>Make extra dependencies that declare that files
1069               with suffix
1070               <filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</filename>
1071               depend on interface files with suffix
1072               <filename>.&lt;suf&gt;&lowbar;hi</filename>, or (for
1073               <literal>&lcub;-&num; SOURCE &num;-&rcub;</literal>
1074               imports) on <filename>.hi-boot</filename>.  Multiple
1075               <option>-s</option> flags are permitted.  For example,
1076               <option>-o hc -s a -s b</option> will make dependencies
1077               for <filename>.hc</filename> on
1078               <filename>.hi</filename>,
1079               <filename>.a&lowbar;hc</filename> on
1080               <filename>.a&lowbar;hi</filename>, and
1081               <filename>.b&lowbar;hc</filename> on
1082               <filename>.b&lowbar;hi</filename>.  (Useful in
1083               conjunction with NoFib "ways".)</para>
1084             </listitem>
1085           </varlistentry>
1086
1087           <varlistentry>
1088             <term><option>&ndash;&ndash;exclude-module=&lt;file&gt;</option></term>
1089             <listitem>
1090               <para>Regard <filename>&lt;file&gt;</filename> as
1091               "stable"; i.e., exclude it from having dependencies on
1092               it.</para>
1093             </listitem>
1094           </varlistentry>
1095
1096           <varlistentry>
1097             <term><option>-x</option></term>
1098             <listitem>
1099               <para>same as <option>&ndash;&ndash;exclude-module</option></para>
1100             </listitem>
1101           </varlistentry>
1102
1103 <!-- Not currently implemented:
1104           <varlistentry>
1105             <term><option>&ndash;&ndash;exclude-directory=&lt;dirs&gt;</option></term>
1106             <listitem>
1107               <para>Regard the colon-separated list of directories
1108               <filename>&lt;dirs&gt;</filename> as containing stable,
1109               don't generate any dependencies on modules
1110               therein.</para>
1111             </listitem>
1112           </varlistentry>
1113
1114           <varlistentry>
1115             <term><option>&ndash;&ndash;include-module=&lt;file&gt;</option></term>
1116             <listitem>
1117               <para>Regard <filename>&lt;file&gt;</filename> as not
1118               "stable"; i.e., generate dependencies on it (if
1119               any). This option is normally used in conjunction with
1120               the <option>&ndash;&ndash;exclude-directory</option> option.</para>
1121             </listitem>
1122           </varlistentry>
1123 -->
1124
1125           <varlistentry>
1126             <term><option>&ndash;&ndash;include-pkg-deps</option></term>
1127             <listitem>
1128               <para>Regard modules imported from packages as unstable,
1129               i.e., generate dependencies on any imported package modules
1130               (including <literal>Prelude</literal>, and all other
1131               standard Haskell libraries).  Dependencies are not traced
1132               recursively into packages; dependencies are only generated for
1133               home-package modules on external-package modules directly imported
1134               by the home package module.
1135               This option is normally
1136               only used by the various system libraries.</para>
1137             </listitem>
1138           </varlistentry>
1139         </variablelist>
1140
1141     </sect2>
1142
1143     <sect2 id="orphan-modules">
1144       <title>Orphan modules and instance declarations</title>
1145
1146 <para> Haskell specifies that when compiling module M, any instance
1147 declaration in any module "below" M is visible.  (Module A is "below"
1148 M if A is imported directly by M, or if A is below a module that M imports directly.)
1149 In principle, GHC must therefore read the interface files of every module below M,
1150 just in case they contain an instance declaration that matters to M.  This would
1151 be a disaster in practice, so GHC tries to be clever. </para>
1152
1153 <para>In particular, if an instance declaration is in the same module as the definition
1154 of any type or class mentioned in the head of the instance declaration, then
1155 GHC has to visit that interface file anyway.  Example:</para>
1156 <programlisting>
1157   module A where
1158     instance C a =&gt; D (T a) where ...
1159     data T a = ...
1160 </programlisting>
1161 <para> The instance declaration is only relevant if the type T is in use, and if
1162 so, GHC will have visited A's interface file to find T's definition. </para>
1163
1164 <para> The only problem comes when a module contains an instance declaration
1165 and GHC has no other reason for visiting the module.  Example:
1166 <programlisting>
1167   module Orphan where
1168     instance C a =&gt; D (T a) where ...
1169     class C a where ...
1170 </programlisting>
1171 Here, neither D nor T is declared in module Orphan.
1172 We call such modules ``orphan modules'',
1173 defined thus:</para>
1174 <itemizedlist>
1175   <listitem> <para> An <emphasis>orphan module</emphasis>
1176   <indexterm><primary>orphan module</primary></indexterm>
1177   contains at least one <emphasis>orphan instance</emphasis> or at
1178   least one <emphasis>orphan rule</emphasis>.</para> </listitem>
1179
1180   <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
1181   <indexterm><primary>orphan instance</primary></indexterm>
1182   none of the type constructors
1183   or classes mentioned in the instance head (the part after the ``<literal>=&gt;</literal>'') are declared
1184   in M.</para>
1185
1186   <para> Only the instance head counts.  In the example above, it is not good enough for C's declaration
1187   to be in module A; it must be the declaration of D or T.</para>
1188   </listitem>
1189
1190   <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
1191   <indexterm><primary>orphan rule</primary></indexterm>
1192   if none of the variables, type constructors,
1193   or classes that are free in the left hand side of the rule are declared in M.
1194   </para> </listitem>
1195  </itemizedlist>
1196
1197
1198 <para> GHC identifies orphan modules, and visits the interface file of
1199 every orphan module below the module being compiled.  This is usually
1200 wasted work, but there is no avoiding it.  You should therefore do
1201 your best to have as few orphan modules as possible.
1202
1203 </para>
1204
1205 <para> You can identify an orphan module by looking in its interface
1206 file, <filename>M.hi</filename>, using the
1207 <option>--show-iface</option>.  If there is a ``!'' on the first line,
1208 GHC considers it an orphan module.
1209 </para>
1210 </sect2>
1211
1212   </sect1>
1213
1214 <!-- Emacs stuff:
1215      ;;; Local Variables: ***
1216      ;;; mode: xml ***
1217      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1218      ;;; End: ***
1219  -->