separate_compilation.xml 50.1 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
  <sect1 id="separate-compilation">
3
    <title>Filenames and separate compilation</title>
sof's avatar
sof committed
4

5
6
7
    <indexterm><primary>separate compilation</primary></indexterm>
    <indexterm><primary>recompilation checker</primary></indexterm>
    <indexterm><primary>make and recompilation</primary></indexterm>
sof's avatar
sof committed
8

9
10
11
12
13
14
    <para>This section describes what files GHC expects to find, what
    files it creates, where these files are stored, and what options
    affect this behaviour.</para>

    <para>Note that this section is written with
    <firstterm>hierarchical modules</firstterm> in mind (see <xref
15
    linkend="hierarchical-modules"/>); hierarchical modules are an
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
    extension to Haskell 98 which extends the lexical syntax of
    module names to include a dot &lsquo;.&rsquo;.  Non-hierarchical
    modules are thus a special case in which none of the module names
    contain dots.</para>

    <para>Pathname conventions vary from system to system.  In
    particular, the directory separator is
    &lsquo;<literal>/</literal>&rsquo; on Unix systems and
    &lsquo;<literal>\</literal>&rsquo; on Windows systems.  In the
    sections that follow, we shall consistently use
    &lsquo;<literal>/</literal>&rsquo; as the directory separator;
    substitute this for the appropriate character for your
    system.</para>

    <sect2 id="source-files">
      <title>Haskell source files</title>
sof's avatar
sof committed
32

33
34
      <indexterm><primary>filenames</primary></indexterm>

35
36
37
      <para>Each Haskell source module should be placed in a file on
      its own.</para>

38
      <para>Usually, the file should be named after the module name,
39
40
41
      replacing dots in the module name by directory separators.  For
      example, on a Unix system, the module <literal>A.B.C</literal>
      should be placed in the file <literal>A/B/C.hs</literal>,
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
      relative to some base directory.  If the module is not going to
      be imported by another module (<literal>Main</literal>, for
      example), then you are free to use any filename for it.</para>

      <indexterm><primary>unicode</primary></indexterm>

      <para> GHC assumes that source files are
      ASCII<indexterm><primary>ASCII</primary></indexterm> or
      UTF-8<indexterm><primary>UTF-8</primary></indexterm> only, other
      encodings<indexterm><primary>encoding</primary></indexterm> are
      not recognised.  However, invalid UTF-8 sequences will be
      ignored in comments, so it is possible to use other encodings
      such as
      Latin-1<indexterm><primary>Latin-1</primary></indexterm>, as
      long as the non-comment source code is ASCII only.</para>
57
58
59
60
    </sect2>

    <sect2 id="output-files">
      <title>Output files</title>
61

62
63
      <indexterm><primary>interface files</primary></indexterm>
      <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
64
65
      <indexterm><primary>object files</primary></indexterm>
      <indexterm><primary><literal>.o</literal> files</primary></indexterm>
sof's avatar
sof committed
66

67
68
69
70
71
      <para>When asked to compile a source file, GHC normally
      generates two files: an <firstterm>object file</firstterm>, and
      an <firstterm>interface file</firstterm>. </para>

      <para>The object file, which normally ends in a
72
73
      <literal>.o</literal> suffix, contains the compiled code for the
      module.</para>
74
75
76
77
78
79
80
81

      <para>The interface file,
      which normally ends in a <literal>.hi</literal> suffix, contains
      the information that GHC needs in order to compile further
      modules that depend on this module.  It contains things like the
      types of exported functions, definitions of data types, and so
      on.  It is stored in a binary format, so don't try to read one;
      use the <option>--show-iface</option> option instead (see <xref
82
      linkend="hi-options"/>).</para>
83
84
85
86
87
88
89
90
91
92
93
94
95
96

      <para>You should think of the object file and the interface file as a
      pair, since the interface file is in a sense a compiler-readable
      description of the contents of the object file.  If the
      interface file and object file get out of sync for any reason,
      then the compiler may end up making assumptions about the object
      file that aren't true; trouble will almost certainly follow.
      For this reason, we recommend keeping object files and interface
      files in the same place (GHC does this by default, but it is
      possible to override the defaults as we'll explain
      shortly).</para>

      <para>Every module has a <emphasis>module name</emphasis>
      defined in its source code (<literal>module A.B.C where
97
98
99
100
101
102
103
104
105
106
107
      ...</literal>).</para>

      <para>The name of the object file generated by GHC is derived
      according to the following rules, where
      <replaceable>osuf</replaceable> is the object-file suffix (this
      can be changed with the <option>-osuf</option> option).</para>

      <itemizedlist>
	<listitem>
	  <para>If there is no <option>-odir</option> option (the
	  default), then the object filename is derived from the
108
109
	  source filename (ignoring the module name) by replacing the
	  suffix with <replaceable>osuf</replaceable>.</para>
110
111
112
113
114
115
116
	</listitem>
	<listitem>
	  <para>If
	  <option>-odir</option>&nbsp;<replaceable>dir</replaceable>
	  has been specified, then the object filename is
	  <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>,
	  where <replaceable>mod</replaceable> is the module name with
117
118
119
	  dots replaced by slashes.  GHC will silently create the necessary directory 
          structure underneath <replaceable>dir</replaceable>, if it does not
          already exist.</para> 
120
121
122
123
124
125
126
127
128
129
130
131
	</listitem>
      </itemizedlist>

      <para>The name of the interface file is derived using the same
      rules, except that the suffix is
      <replaceable>hisuf</replaceable> (<literal>.hi</literal> by
      default) instead of <replaceable>osuf</replaceable>, and the
      relevant options are <option>-hidir</option> and
      <option>-hisuf</option> instead of <option>-odir</option> and
      <option>-osuf</option> respectively.</para>

      <para>For example, if GHC compiles the module
132
      <literal>A.B.C</literal> in the file
133
134
135
136
137
      <filename>src/A/B/C.hs</filename>, with no
      <literal>-odir</literal> or <literal>-hidir</literal> flags, the
      interface file will be put in <literal>src/A/B/C.hi</literal>
      and the object file in <literal>src/A/B/C.o</literal>.</para>

138
139
140
      <para>For any module that is imported, GHC requires that the
      name of the module in the import statement exactly matches the
      name of the module in the interface file (or source file) found
141
      using the strategy specified in <xref linkend="search-path"/>.
142
143
144
145
      This means that for most modules, the source file name should
      match the module name.</para>

      <para>However, note that it is reasonable to have a module
146
147
148
149
150
151
      <literal>Main</literal> in a file named
      <filename>foo.hs</filename>, but this only works because GHC
      never needs to search for the interface for module
      <literal>Main</literal> (because it is never imported).  It is
      therefore possible to have several <literal>Main</literal>
      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
ross's avatar
ross committed
155
      also be overridden using the <option>-o</option> option, and the
156
157
      name of the interface file can be specified directly using the
      <option>-ohi</option> option.</para>
158
159
    </sect2>

160
161
    <sect2 id="search-path">
      <title>The search path</title>
162

163
164
      <indexterm><primary>search path</primary>
      </indexterm>
165
166
167
168
169
      <indexterm><primary>interface files, finding them</primary></indexterm>
      <indexterm><primary>finding interface files</primary></indexterm>

      <para>In your program, you import a module
      <literal>Foo</literal> by saying <literal>import Foo</literal>.
170
171
172
173
174
175
176
      In <option>--make</option> mode or GHCi, GHC will look for a
      source file for <literal>Foo</literal> and arrange to compile it
      first.  Without <option>--make</option>, GHC will look for the
      interface file for <literal>Foo</literal>, which should have
      been created by an earlier compilation of
      <literal>Foo</literal>.  GHC uses the same strategy in each of
      these cases for finding the appropriate file.</para>
177

178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
      <para>This strategy is as follows: GHC keeps a list of
      directories called the <firstterm>search path</firstterm>.  For
      each of these directories, it tries appending
      <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
      to the directory, and checks whether the file exists.  The value
      of <replaceable>basename</replaceable> is the module name with
      dots replaced by the directory separator ('/' or '\', depending
      on the system), and <replaceable>extension</replaceable> is a
      source extension (<literal>hs</literal>, <literal>lhs</literal>)
      if we are in <option>--make</option> mode and GHCi, or
      <replaceable>hisuf</replaceable> otherwise.</para>

      <para>For example, suppose the search path contains directories
      <literal>d1</literal>, <literal>d2</literal>, and
      <literal>d3</literal>, and we are in <literal>--make</literal>
      mode looking for the source file for a module
      <literal>A.B.C</literal>.  GHC will look in
      <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
      <literal>d2/A/B/C.hs</literal>, and so on.</para>

      <para>The search path by default contains a single directory:
      <quote>.</quote> (i.e. the current directory).  The following
      options can be used to add to or change the contents of the
      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
210
211
            list of <filename>dirs</filename> to the search path.</para>
	  </listitem>
	</varlistentry>
212

213
214
215
216
217
218
219
220
221
222
	<varlistentry>
	  <term><option>-i</option></term>
	  <listitem>
	    <para>resets the search path back to nothing.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>This isn't the whole story: GHC also looks for modules in
      pre-compiled libraries, known as packages.  See the section on
223
      packages (<xref linkend="packages"/>), for details.</para>
224
225
226
227
228
229
230
231
232
233
    </sect2>

    <sect2 id="options-output">
      <title>Redirecting the compilation output(s)</title>

      <indexterm><primary>output-directing options</primary></indexterm>
      <indexterm><primary>redirecting compilation output</primary></indexterm>

      <variablelist>
	<varlistentry>
234
235
236
237
	  <term>
            <option>-o</option> <replaceable>file</replaceable>
            <indexterm><primary><option>-o</option></primary></indexterm>
          </term>
238
239
240
241
242
243
244
	  <listitem>
	    <para>GHC's compiled output normally goes into a
            <filename>.hc</filename>, <filename>.o</filename>, etc.,
            file, depending on the last-run compilation phase.  The
            option <option>-o <replaceable>file</replaceable></option>
            re-directs the output of that last-run phase to
            <replaceable>file</replaceable>.</para>
245

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
	    <para>Note: this &ldquo;feature&rdquo; can be
            counterintuitive: <command>ghc -C -o foo.o
            foo.hs</command> will put the intermediate C code in the
            file <filename>foo.o</filename>, name
            notwithstanding!</para>

	    <para>This option is most often used when creating an
	    executable file, to set the filename of the executable.
	    For example:
<screen>   ghc -o prog --make Main</screen>

            will compile the program starting with module
            <literal>Main</literal>  and put the executable in the
            file <literal>prog</literal>.</para>

	    <para>Note: on Windows, if the result is an executable
            file, the extension "<filename>.exe</filename>" is added
            if the specified filename does not already have an
            extension.  Thus
<programlisting>
   ghc -o foo Main.hs
</programlisting>
          will compile and link the module
          <filename>Main.hs</filename>, and put the resulting
          executable in <filename>foo.exe</filename> (not
          <filename>foo</filename>).</para>
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288

          <para>If you use <command>ghc --make</command> and you don't
          use the <option>-o</option>, the name GHC will choose
          for the executable will be based on the name of the file
          containing the module <literal>Main</literal>. 
          Note that with GHC the <literal>Main</literal> module doesn't
          have to be put in file <filename>Main.hs</filename>.
          Thus both
<programlisting>
   ghc --make Prog
</programlisting>
          and
<programlisting>
   ghc --make Prog.hs
</programlisting>
          will produce <filename>Prog</filename> (or
          <filename>Prog.exe</filename> if you are on Windows).</para>
289
290
291
292
	  </listitem>
	</varlistentry>

	<varlistentry>
293
294
295
296
	  <term>
            <option>-odir</option> <replaceable>dir</replaceable>
            <indexterm><primary><option>-odir</option></primary></indexterm>
          </term>
297
298
299
300
	  <listitem>
	    <para>Redirects object files to directory
	    <replaceable>dir</replaceable>.  For example:</para>

301
<screen>
302
$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
303
</screen>
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322

	    <para>The object files, <filename>Foo.o</filename>,
            <filename>Bar.o</filename>, and
            <filename>Bumble.o</filename> would be put into a
            subdirectory named after the architecture of the executing
            machine (<filename>x86</filename>,
            <filename>mips</filename>, etc).</para>

	    <para>Note that the <option>-odir</option> option does
            <emphasis>not</emphasis> affect where the interface files
            are put; use the <option>-hidir</option> option for that.
            In the above example, they would still be put in
            <filename>parse/Foo.hi</filename>,
            <filename>parse/Bar.hi</filename>, and
            <filename>gurgle/Bumble.hi</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
323
324
325
326
	  <term>
            <option>-ohi</option>  <replaceable>file</replaceable>
            <indexterm><primary><option>-ohi</option></primary></indexterm>
          </term>
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
	  <listitem>
	    <para>The interface output may be directed to another file
            <filename>bar2/Wurble.iface</filename> with the option
            <option>-ohi bar2/Wurble.iface</option> (not
            recommended).</para>

	    <para>WARNING: if you redirect the interface file
	    somewhere that GHC can't find it, then the recompilation
	    checker may get confused (at the least, you won't get any
	    recompilation avoidance).  We recommend using a
	    combination of <option>-hidir</option> and
	    <option>-hisuf</option> options instead, if
	    possible.</para>

	    <para>To avoid generating an interface at all, you could
            use this option to redirect the interface into the bit
            bucket: <literal>-ohi /dev/null</literal>, for
            example.</para>
	  </listitem>
	</varlistentry>
sof's avatar
sof committed
347

348
	<varlistentry>
349
350
351
352
	  <term>
            <option>-hidir</option>  <replaceable>dir</replaceable>
            <indexterm><primary><option>-hidir</option></primary></indexterm>
          </term>
353
	  <listitem>
354
355
356
	    <para>Redirects all generated interface files into
	    <replaceable>dir</replaceable>, instead of the
	    default.</para>
357
358
359
	  </listitem>
	</varlistentry>

360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
	<varlistentry>
	  <term>
            <option>-stubdir</option>  <replaceable>dir</replaceable>
            <indexterm><primary><option>-stubdir</option></primary></indexterm>
          </term>
	  <listitem>
	    <para>Redirects all generated FFI stub files into
	    <replaceable>dir</replaceable>.  Stub files are generated when the
	    Haskell source contains a <literal>foreign export</literal> or
	    <literal>foreign import "&amp;wrapper"</literal> declaration (see <xref
	      linkend="foreign-export-ghc" />).  The <option>-stubdir</option>
	      option behaves in exactly the same way as <option>-odir</option>
	      and <option>-hidir</option> with respect to hierarchical
	    modules.</para>
	  </listitem>
	</varlistentry>

377
	<varlistentry>
378
379
380
381
382
383
384
385
386
387
388
389
	  <term>
            <option>-osuf</option> <replaceable>suffix</replaceable>
            <indexterm><primary><option>-osuf</option></primary></indexterm>
          </term>
	  <term>
            <option>-hisuf</option> <replaceable>suffix</replaceable>
            <indexterm><primary><option>-hisuf</option></primary></indexterm>
          </term>
	  <term>
            <option>-hcsuf</option> <replaceable>suffix</replaceable>
            <indexterm><primary><option>-hcsuf</option></primary></indexterm>
          </term>
390
	  <listitem>
391
	    <para>The <option>-osuf</option>
392
393
394
395
396
397
398
399
400
            <replaceable>suffix</replaceable> will change the
            <literal>.o</literal> file suffix for object files to
            whatever you specify.  We use this when compiling
            libraries, so that objects for the profiling versions of
            the libraries don't clobber the normal ones.</para>

	    <para>Similarly, the <option>-hisuf</option>
            <replaceable>suffix</replaceable> will change the
            <literal>.hi</literal> file suffix for non-system
401
            interface files (see <xref linkend="hi-options"/>).</para>
402
403
404
405
406
407
408
409
410
411

	    <para>Finally, the option <option>-hcsuf</option>
            <replaceable>suffix</replaceable> will change the
            <literal>.hc</literal> file suffix for compiler-generated
            intermediate C files.</para>

	    <para>The <option>-hisuf</option>/<option>-osuf</option>
            game is particularly useful if you want to compile a
            program both with and without profiling, in the same
            directory.  You can say:
412
413
	    <screen>
	      ghc ...</screen>
414
	    to get the ordinary version, and
415
416
	    <screen>
	      ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen>
417
418
419
	    to get the profiled version.</para>
	  </listitem>
	</varlistentry>
420
      </variablelist>
421
    </sect2>
422
  
423
424
425
426
427
428
429
430
    <sect2 id="keeping-intermediates">
      <title>Keeping Intermediate Files</title>
      <indexterm><primary>intermediate files, saving</primary>
      </indexterm>
      <indexterm><primary><literal>.hc</literal> files, saving</primary>
      </indexterm>
      <indexterm><primary><literal>.s</literal> files, saving</primary>
      </indexterm>
431

432
433
434
      <para>The following options are useful for keeping certain
      intermediate files around, when normally GHC would throw these
      away after compilation:</para>
435

436
437
      <variablelist>
	<varlistentry>
438
439
440
441
	  <term>
            <option>-keep-hc-files</option>
            <indexterm><primary><option>-keep-hc-files</option></primary></indexterm>
          </term>
442
443
444
445
446
447
448
449
450
451
452
	  <listitem>
	    <para>Keep intermediate <literal>.hc</literal> files when
	    doing <literal>.hs</literal>-to-<literal>.o</literal>
	    compilations via C (NOTE: <literal>.hc</literal> files
	    aren't generated when using the native code generator, you
	    may need to use <option>-fvia-C</option> to force them
	    to be produced).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
453
454
455
456
	  <term>
            <option>-keep-s-files</option>
            <indexterm><primary><option>-keep-s-files</option></primary></indexterm>
          </term>
457
458
459
460
461
462
	  <listitem>
	    <para>Keep intermediate <literal>.s</literal> files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
463
464
465
466
	  <term>
            <option>-keep-raw-s-files</option>
            <indexterm><primary><option>-keep-raw-s-files</option></primary></indexterm>
          </term>
467
468
469
470
471
472
473
474
475
476
	  <listitem>
	    <para>Keep intermediate <literal>.raw-s</literal> files.
	    These are the direct output from the C compiler, before
	    GHC does &ldquo;assembly mangling&rdquo; to produce the
	    <literal>.s</literal> file.  Again, these are not produced
	    when using the native code generator.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
477
478
479
480
481
	  <term>
            <option>-keep-tmp-files</option>
            <indexterm><primary><option>-keep-tmp-files</option></primary></indexterm>
            <indexterm><primary>temporary files</primary><secondary>keeping</secondary></indexterm>
          </term>
482
483
484
485
	  <listitem>
	    <para>Instructs the GHC driver not to delete any of its
	    temporary files, which it normally keeps in
	    <literal>/tmp</literal> (or possibly elsewhere; see <xref
486
	    linkend="temp-files"/>).  Running GHC with
487
488
489
490
491
	    <option>-v</option> will show you what temporary files
	    were generated along the way.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
492
493
    </sect2>

494
495
496
497
498
499
500
501
502
503
    <sect2 id="temp-files">
      <title>Redirecting temporary files</title>

      <indexterm>
	<primary>temporary files</primary>
	<secondary>redirecting</secondary>
      </indexterm>

      <variablelist>
	<varlistentry>
504
505
506
507
	  <term>
            <option>-tmpdir</option>
            <indexterm><primary><option>-tmpdir</option></primary></indexterm>
          </term>
508
509
510
511
512
	  <listitem>
	    <para>If you have trouble because of running out of space
            in <filename>/tmp</filename> (or wherever your
            installation thinks temporary files should go), you may
            use the <option>-tmpdir
513
514
            &lt;dir&gt;</option><indexterm><primary>-tmpdir
            &lt;dir&gt; option</primary></indexterm> option to specify
515
516
517
518
            an alternate directory.  For example, <option>-tmpdir
            .</option> says to put temporary files in the current
            working directory.</para>

519
520
521
	    <para>Alternatively, use your <constant>TMPDIR</constant>
            environment variable.<indexterm><primary>TMPDIR
            environment variable</primary></indexterm> Set it to the
522
523
            name of the directory where temporary files should be put.
            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
531
532
533
            documentation).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
534
535
    </sect2>

536
    <sect2 id="hi-options">
537
538
539
540
541
      <title>Other options related to interface files</title>
      <indexterm><primary>interface files, options</primary></indexterm>

      <variablelist>
	<varlistentry>
542
543
544
545
	  <term>
            <option>-ddump-hi</option>
            <indexterm><primary><option>-ddump-hi</option></primary></indexterm>
          </term>
546
547
548
549
550
551
	  <listitem>
	    <para>Dumps the new interface to standard output.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
552
553
554
555
	  <term>
            <option>-ddump-hi-diffs</option>
            <indexterm><primary><option>-ddump-hi-diffs</option></primary></indexterm>
          </term>
556
557
558
559
560
561
562
563
564
565
566
567
568
	  <listitem>
	    <para>The compiler does not overwrite an existing
            <filename>.hi</filename> interface file if the new one is
            the same as the old one; this is friendly to
            <command>make</command>.  When an interface does change,
            it is often enlightening to be informed.  The
            <option>-ddump-hi-diffs</option> option will make GHC run
            <command>diff</command> on the old and new
            <filename>.hi</filename> files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
569
570
571
572
	  <term>
            <option>-ddump-minimal-imports</option>
            <indexterm><primary><option>-ddump-minimal-imports</option></primary></indexterm>
          </term>
573
574
575
576
577
578
579
580
581
582
583
584
	  <listitem>
	    <para>Dump to the file "M.imports" (where M is the module
            being compiled) a "minimal" set of import declarations.
            You can safely replace all the import declarations in
            "M.hs" with those found in "M.imports".  Why would you
            want to do that?  Because the "minimal" imports (a) import
            everything explicitly, by name, and (b) import nothing
            that is not required.  It can be quite painful to maintain
            this property by hand, so this flag is intended to reduce
            the labour.</para>
	  </listitem>
	</varlistentry>
585
586

	<varlistentry>
587
588
589
590
	  <term>
            <option>--show-iface</option> <replaceable>file</replaceable>
            <indexterm><primary><option>--show-iface</option></primary></indexterm>
          </term>
591
592
593
594
595
596
	  <listitem>
	    <para>Where <replaceable>file</replaceable> is the name of
	    an interface file, dumps the contents of that interface in
	    a human-readable (ish) format.</para>
	  </listitem>
	</varlistentry>
597
598
599
600
601
602
603
604
605
606
      </variablelist>
    </sect2>

    <sect2 id="recomp">
      <title>The recompilation checker</title>

      <indexterm><primary>recompilation checker</primary></indexterm>

      <variablelist>
	<varlistentry>
607
	  <term>
608
609
610
            <option>-fforce-recomp</option>
            <indexterm><primary><option>-fforce-recomp</option></primary></indexterm>
            <indexterm><primary><option>-fno-force-recomp</option></primary></indexterm>
611
          </term>
612
613
614
615
616
617
618
619
620
621
	  <listitem>
	    <para>Turn off recompilation checking (which is on by
            default).  Recompilation checking normally stops
            compilation early, leaving an existing
            <filename>.o</filename> file in place, if it can be
            determined that the module does not need to be
            recompiled.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
sof's avatar
sof committed
622

623
624
625
626
627
628
629
630
631
632
      <para>In the olden days, GHC compared the newly-generated
      <filename>.hi</filename> file with the previous version; if they
      were identical, it left the old one alone and didn't change its
      modification date.  In consequence, importers of a module with
      an unchanged output <filename>.hi</filename> file were not
      recompiled.</para>

      <para>This doesn't work any more.  Suppose module
      <literal>C</literal> imports module <literal>B</literal>, and
      <literal>B</literal> imports module <literal>A</literal>.  So
633
634
635
636
637
638
639
640
      changes to module <literal>A</literal> might require module
      <literal>C</literal> to be recompiled, and hence when
      <filename>A.hi</filename> changes we should check whether
      <literal>C</literal> should be recompiled.  However, the
      dependencies of <literal>C</literal> will only list
      <literal>B.hi</literal>, not <literal>A.hi</literal>, and some
      changes to <literal>A</literal> (changing the definition of a
      function that appears in an inlining of a function exported by
641
642
643
644
645
646
647
648
649
      <literal>B</literal>, say) may conceivably not change
      <filename>B.hi</filename> one jot.  So now&hellip;</para>

      <para>GHC keeps a version number on each interface file, and on
      each type signature within the interface file.  It also keeps in
      every interface file a list of the version numbers of everything
      it used when it last compiled the file.  If the source file's
      modification date is earlier than the <filename>.o</filename>
      file's date (i.e. the source hasn't changed since the file was
ross's avatar
ross committed
650
      last compiled), and the recompilation checking is on, GHC will be
651
652
653
654
655
656
657
658
      clever.  It compares the version numbers on the things it needs
      this time with the version numbers on the things it needed last
      time (gleaned from the interface file of the module being
      compiled); if they are all the same it stops compiling rather
      early in the process saying &ldquo;Compilation IS NOT
      required&rdquo;.  What a beautiful sight!</para>

      <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
662
663
664
      copy.</para>

    </sect2>

665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
    <sect2 id="mutual-recursion">
      <title>How to compile mutually recursive modules</title>

      <indexterm><primary>module system, recursion</primary></indexterm>
      <indexterm><primary>recursion, between modules</primary></indexterm>

      <para>GHC supports the compilation of mutually recursive modules.
      This section explains how.</para>

      <para>Every cycle in the module import graph must be broken by a <filename>hs-boot</filename> file.
      Suppose that modules <filename>A.hs</filename> and <filename>B.hs</filename> are Haskell source files, 
      thus:
<programlisting>
module A where
    import B( TB(..) )
    
    newtype TA = MkTA Int
    
    f :: TB -&#62; TA
    f (MkTB x) = MkTA x

module B where
    import {-# SOURCE #-} A( TA(..) )
    
    data TB = MkTB !Int
    
    g :: TA -&#62; TB
    g (MkTA x) = MkTB x
</programlisting>
<indexterm><primary><literal>hs-boot</literal>
      files</primary></indexterm> <indexterm><primary>importing,
      <literal>hi-boot</literal> files</primary></indexterm>
Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports
<filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the
circular dependency.  For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
in this way there must exist a souce file <literal>A.hs-boot</literal>.  This file contains an abbreviated
version of <filename>A.hs</filename>, thus:
<programlisting>
module A where
    newtype TA = MkTA Int
</programlisting>
</para>
<para>To compile these three files, issue the following commands:
<programlisting>
  ghc -c A.hs-boot    -- Poduces A.hi-boot, A.o-boot
  ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
  ghc -c A.hs	      -- Consumes B.hi, produces A.hi, A.o
  ghc -o foo A.o B.o  -- Linking the program
</programlisting>
</para>
<para>There are several points to note here:
<itemizedlist>
<listitem>
  <para>The file <filename>A.hs-boot</filename> is a programmer-written source file.
  It must live in the same directory as its parent source file <filename>A.hs</filename>.
720
721
  Currently, if you use a literate source file <filename>A.lhs</filename> you must
  also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa.
722
723
  </para></listitem>

724
725
726
727
728
729
<listitem><para>
  A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
<programlisting>
  ghc -c A.hs-boot
</programlisting>
When a hs-boot file <filename>A.hs-boot</filename> 
730
731
732
733
734
   is compiled, it is checked for scope and type errors.
   When its parent module <filename>A.hs</filename> is compiled, the two are compared, and
   an error is reported if the two are inconsistent.
   </para></listitem>
   
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
	<listitem>
	  <para> Just as compiling <filename>A.hs</filename> produces an
	    interface file <filename>A.hi</filename>, and an object file
	    <filename>A.o</filename>, so compiling
	    <filename>A.hs-boot</filename> produces an interface file
	    <filename>A.hi-boot</filename>, and an pseudo-object file
	    <filename>A.o-boot</filename>: </para>

	  <itemizedlist>
	    <listitem>
	      <para>The pseudo-object file <filename>A.o-boot</filename> is
		empty (don't link it!), but it is very useful when using a
		Makefile, to record when the <filename>A.hi-boot</filename> was
		last brought up to date (see <xref
		  linkend="using-make"/>).</para>
	    </listitem>

	    <listitem>
	      <para>The <filename>hi-boot</filename> generated by compiling a
		<filename>hs-boot</filename> file is in the same
		machine-generated binary format as any other GHC-generated
		interface file (e.g. <filename>B.hi</filename>). You can
		display its contents with <command>ghc
		  --show-iface</command>. If you specify a directory for
		interface files, the <option>-ohidir</option> flag, then that
		affects <filename>hi-boot</filename> files
		too.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
765

766
767
   <listitem><para> If hs-boot files are considered distinct from their parent source
   files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the
768
769
770
771
   hs-boot file, then the module import graph must have no cycles.  The command
   <command>ghc -M</command> will report an error if a cycle is found.
   </para></listitem>

772
773
774
775
776
777
   <listitem><para> A module <literal>M</literal> that is 
   <literal>{-# SOURCE #-}</literal>-imported in a program will usually also be
   ordinarily imported elsewhere.  If not, <command>ghc --make</command>
   automatically adds <literal>M</literal> to the set of moudles it tries to
   compile and link, to ensure that <literal>M</literal>'s implementation is included in
   the final program.
778
779
780
781
782
783
784
785
786
   </para></listitem>
</itemizedlist>
</para>
<para>
A hs-boot file need only contain the bare
      minimum of information needed to get the bootstrapping process
      started.  For example, it doesn't need to contain declarations
      for <emphasis>everything</emphasis> that module
      <literal>A</literal> exports, only the things required by the
787
      module(s) that import <literal>A</literal> recursively.</para>
788
789
<para>A hs-boot file is written in a subset of Haskell:
<itemizedlist>
790
791
792
793
<listitem><para> The module header (including the export list), and import statements, are exactly as in
Haskell, and so are the scoping rules.  
   Hence, to mention a non-Prelude type or class, you must import it.</para></listitem>
   
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
<listitem><para> There must be no value declarations, but there can be type signatures for
values.  For example:
<programlisting>
  double :: Int -&#62; Int
</programlisting>
</para></listitem>
<listitem><para> Fixity declarations are exactly as in Haskell.</para></listitem>
<listitem><para> Type synonym declarations are exactly as in Haskell.</para></listitem>
<listitem><para> A data type declaration can either be given in full, exactly as in Haskell, or it 
can be given abstractly, by omitting the '=' sign and everything that follows.  For example:
<programlisting>
  data T a b
</programlisting>
	    In a <emphasis>source</emphasis> program
	  this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>),
	  but in an hi-boot file it means "I don't know or care what the constructors are".
	    This is the most common form of data type declaration, because it's easy to get right.
	  You <emphasis>can</emphasis> also write out the constructors but, if you do so, you must write
	  it out precisely as in its real definition.</para>
	  <para>
	    If you do not write out the constructors, you may need to give a kind 
815
	    annotation (<xref linkend="kinding"/>), to tell
816
817
818
819
820
	    GHC the kind of the type variable, if it is not "*".  (In source files, this is worked out
	    from the way the type variable is used in the constructors.)  For example:
<programlisting>
  data R (x :: * -&#62; *) y
</programlisting>
821
822
You cannot use <literal>deriving</literal> on a data type declaration; write in
<literal>instance</literal> declaration instead.
823
824
</para></listitem>
<listitem><para> Class declarations is exactly as in Haskell, except that you may not put
825
826
default method declarations.  You can also omit all the superclasses and class
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
830
831
832
833
834
 </para></listitem>
</itemizedlist>
</para>
    </sect2>


835
836
837
838
839
840
841
842
843
    <sect2 id="using-make">
      <title>Using <command>make</command></title>

      <indexterm><primary><literal>make</literal></primary></indexterm>

      <para>It is reasonably straightforward to set up a
      <filename>Makefile</filename> to use with GHC, assuming you name
      your source files the same as your modules.  Thus:</para>

844
<programlisting>
845
846
847
848
849
850
851
852
853
HC      = ghc
HC_OPTS = -cpp $(EXTRA_HC_OPTS)

SRCS = Main.lhs Foo.lhs Bar.lhs
OBJS = Main.o   Foo.o   Bar.o

.SUFFIXES : .o .hs .hi .lhs .hc .s

cool_pgm : $(OBJS)
ken's avatar
ken committed
854
        rm -f $@
855
856
857
858
859
860
861
862
863
864
865
866
        $(HC) -o $@ $(HC_OPTS) $(OBJS)

# Standard suffix rules
.o.hi:
        @:

.lhs.o:
        $(HC) -c $&#60; $(HC_OPTS)

.hs.o:
        $(HC) -c $&#60; $(HC_OPTS)

867
868
869
870
871
872
873
874
875
.o-boot.hi-boot:
        @:

.lhs-boot.o-boot:
        $(HC) -c $&#60; $(HC_OPTS)

.hs-boot.o-boot:
        $(HC) -c $&#60; $(HC_OPTS)

876
877
878
# Inter-module dependencies
Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
879
</programlisting>
880
881
882
883
884
885

      <para>(Sophisticated <command>make</command> variants may
      achieve some of the above more elegantly.  Notably,
      <command>gmake</command>'s pattern rules let you write the more
      comprehensible:</para>

886
<programlisting>
887
888
%.o : %.lhs
        $(HC) -c $&#60; $(HC_OPTS)
889
</programlisting>
890
891
892
893
894
895
896
897
898

      <para>What we've shown should work with any
      <command>make</command>.)</para>

      <para>Note the cheesy <literal>.o.hi</literal> rule: It records
      the dependency of the interface (<filename>.hi</filename>) file
      on the source.  The rule says a <filename>.hi</filename> file
      can be made from a <filename>.o</filename> file by
      doing&hellip;nothing.  Which is true.</para>
899
900
      <para> Note that the suffix rules are all repeated twice, once
      for normal Haskell source files, and once for <filename>hs-boot</filename>
901
      files (see <xref linkend="mutual-recursion"/>).</para>
902

903
904
      <para>Note also the inter-module dependencies at the end of the
      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
912
913
914
915
      <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
      <literal>Foo.s</literal> have an earlier modification date than
      <literal>Baz.hi</literal>, then the out-of-date file must be
      brought up to date.  To bring it up to date,
      <literal>make</literal> looks for a rule to do so; one of the
916
917
      preceding suffix rules does the job nicely.  These dependencies
      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
924
925
926
927
928
929
930
931
932
	<title>Dependency generation</title>
	<indexterm><primary>dependencies in Makefiles</primary></indexterm>
	<indexterm><primary>Makefile dependencies</primary></indexterm>

	<para>Putting inter-dependencies of the form <literal>Foo.o :
        Bar.hi</literal> into your <filename>Makefile</filename> by
        hand is rather error-prone.  Don't worry, GHC has support for
        automatically generating the required dependencies.  Add the
        following to your <filename>Makefile</filename>:</para>

933
<programlisting>
934
935
depend :
        ghc -M $(HC_OPTS) $(SRCS)
936
</programlisting>
937
938
939
940

	<para>Now, before you start compiling, and any time you change
        the <literal>imports</literal> in your program, do
        <command>make depend</command> before you do <command>make
941
        cool&lowbar;pgm</command>.  The command <command>ghc -M</command> will
942
943
944
        append the needed dependencies to your
        <filename>Makefile</filename>.</para>

945
946
947
948
949
950
	<para>In general, <command>ghc -M Foo</command> does the following.
	For each module <literal>M</literal> in the set 
	<literal>Foo</literal> plus all its imports (transitively),
	it adds to the Makefile:
	<itemizedlist>
	<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
955
956
957
(or <literal>M.lhs</literal> if that is the filename you used).
       </para></listitem>
       <listitem><para> For each import declaration <literal>import X</literal> in <literal>M</literal>,
       a line recording the dependence of <literal>M</literal> on <literal>X</literal>:
958
<programlisting>
959
960
961
962
M.o : X.hi
</programlisting></para></listitem>
       <listitem><para> For each import declaration <literal>import {-# SOURCE #-} X</literal> in <literal>M</literal>,
       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
968
969
970
971
       <literal>hi-boot</literal> style interface files.)
      </para></listitem>
        </itemizedlist> 
	If <literal>M</literal> imports multiple modules, then there will
       be multiple lines with <filename>M.o</filename> as the
972
       target.</para>
973
974
975
       <para>There is no need to list all of the source files as arguments to the <command>ghc -M</command> command;
       <command>ghc</command> traces the dependencies, just like <command>ghc --make</command>
       (a new feature in GHC 6.4).</para>
976

977
978
979
980
981
982
983
984
    <para>Note that <literal>ghc -M</literal> needs to find a <emphasis>source
	file</emphasis> for each module in the dependency graph, so that it can
      parse the import declarations and follow dependencies.  Any pre-compiled
      modules without source files must therefore belong to a
      package<footnote><para>This is a change in behaviour relative to 6.2 and
	earlier.</para>
      </footnote>.</para>

985
986
987
988
989
990
991
992
993
994
995
        <para>By default, <command>ghc -M</command> generates all the
        dependencies, and then concatenates them onto the end of
        <filename>makefile</filename> (or
        <filename>Makefile</filename> if <filename>makefile</filename>
        doesn't exist) bracketed by the lines "<literal>&num; DO NOT
        DELETE: Beginning of Haskell dependencies</literal>" and
        "<literal>&num; DO NOT DELETE: End of Haskell
        dependencies</literal>".  If these lines already exist in the
        <filename>makefile</filename>, then the old dependencies are
        deleted first.</para>

996
997
998
999
1000
1001
	<para>Don't forget to use the same <option>-package</option>
	options on the <literal>ghc -M</literal> command line as you
	would when compiling; this enables the dependency generator to
	locate any imported modules that come from packages.  The
	package modules won't be included in the dependencies
	generated, though (but see the
1002
	<option>&ndash;&ndash;include-pkg-deps</option> option below).</para>
1003

1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
	<para>The dependency generation phase of GHC can take some
        additional options, which you may find useful.  For historical
        reasons, each option passed to the dependency generator from
        the GHC command line must be preceded by
        <literal>-optdep</literal>.  For example, to pass <literal>-f
        .depend</literal> to the dependency generator, you say

<screen>
ghc -M -optdep-f -optdep.depend ...
</screen>
sof's avatar
sof committed
1014

1015
	The options which affect dependency generation are:</para>
sof's avatar
sof committed
1016

1017
	<variablelist>
1018
1019
1020
1021
1022
1023
1024
1025
1026
	  <varlistentry>
	    <term><option>-ddump-mod-cycles</option></term>
	    <listitem>
	      <para>Display a list of the cycles in the module graph. This is
	  useful when trying to eliminate such cycles.  You do not need the <literal>-optdep</literal> prefix
	  for this flag.</para>
	    </listitem>
	  </varlistentry>

1027
1028
1029
1030
1031
1032
	  <varlistentry>
	    <term><option>-w</option></term>
	    <listitem>
	      <para>Turn off warnings about interface file shadowing.</para>
	    </listitem>
	  </varlistentry>
sof's avatar
sof committed
1033

1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
	  <varlistentry>
	    <term><option>-v2</option></term>
	    <listitem>
	      <para>Print a full list of the module depenencies to stdout.
	            (This is the standard verbosity flag, so the list will
	      also be displayed with <option>-v3</option> and
	      <option>-v4</option>;
	      <xref linkend ="options-help"/>.)</para>
	    </listitem>
	  </varlistentry>

1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
	  <varlistentry>
	    <term><option>-f</option> <replaceable>file</replaceable></term>
	    <listitem>
	      <para>Use <replaceable>file</replaceable> as the makefile,
              rather than <filename>makefile</filename> or
              <filename>Makefile</filename>.  If
              <replaceable>file</replaceable> doesn't exist,
              <command>mkdependHS</command> creates it.  We often use
              <option>-f .depend</option> to put the dependencies in
              <filename>.depend</filename> and then
              <command>include</command> the file
              <filename>.depend</filename> into
              <filename>Makefile</filename>.</para>
	    </listitem>
	  </varlistentry>

sof's avatar
sof committed
1061
<!-- Retired with the move away from 'mkdependHS'.
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
	  <varlistentry>
	    <term><option>-o &lt;osuf&gt;</option></term>
	    <listitem>
	      <para>Use <filename>.&lt;osuf&gt;</filename> as the
              "target file" suffix ( default: <literal>o</literal>).
              Multiple <option>-o</option> flags are permitted
              (GHC2.05 onwards).  Thus "<option>-o hc -o o</option>"
              will generate dependencies for <filename>.hc</filename>
              and <filename>.o</filename> files.</para>
	    </listitem>
	  </varlistentry>
sof's avatar
sof committed
1073
-->
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
	  <varlistentry>
	    <term><option>-s &lt;suf&gt;</option></term>
	    <listitem>
	      <para>Make extra dependencies that declare that files
              with suffix
              <filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</filename>
              depend on interface files with suffix
              <filename>.&lt;suf&gt;&lowbar;hi</filename>, or (for
              <literal>&lcub;-&num; SOURCE &num;-&rcub;</literal>
              imports) on <filename>.hi-boot</filename>.  Multiple
              <option>-s</option> flags are permitted.  For example,
              <option>-o hc -s a -s b</option> will make dependencies
              for <filename>.hc</filename> on
              <filename>.hi</filename>,
              <filename>.a&lowbar;hc</filename> on
              <filename>.a&lowbar;hi</filename>, and
              <filename>.b&lowbar;hc</filename> on
              <filename>.b&lowbar;hi</filename>.  (Useful in
              conjunction with NoFib "ways".)</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
1097
	    <term><option>&ndash;&ndash;exclude-module=&lt;file&gt;</option></term>
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
	    <listitem>
	      <para>Regard <filename>&lt;file&gt;</filename> as
              "stable"; i.e., exclude it from having dependencies on
              it.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><option>-x</option></term>
	    <listitem>
1108
	      <para>same as <option>&ndash;&ndash;exclude-module</option></para>
1109
1110
1111
	    </listitem>
	  </varlistentry>

1112
<!-- Not currently implemented:
1113
	  <varlistentry>
1114
	    <term><option>&ndash;&ndash;exclude-directory=&lt;dirs&gt;</option></term>
1115
1116
1117
1118
1119
1120
1121
1122
1123
	    <listitem>
	      <para>Regard the colon-separated list of directories
              <filename>&lt;dirs&gt;</filename> as containing stable,
              don't generate any dependencies on modules
              therein.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
1124
	    <term><option>&ndash;&ndash;include-module=&lt;file&gt;</option></term>
1125
1126
1127
1128
	    <listitem>
	      <para>Regard <filename>&lt;file&gt;</filename> as not
              "stable"; i.e., generate dependencies on it (if
              any). This option is normally used in conjunction with
1129
              the <option>&ndash;&ndash;exclude-directory</option> option.</para>
1130
1131
	    </listitem>
	  </varlistentry>
1132
-->
1133
1134

	  <varlistentry>
1135
	    <term><option>&ndash;&ndash;include-pkg-deps</option></term>
1136
	    <listitem>
1137
	      <para>Regard modules imported from packages as unstable,
1138
              i.e., generate dependencies on any imported package modules
1139
              (including <literal>Prelude</literal>, and all other
1140
1141
1142
1143
1144
              standard Haskell libraries).  Dependencies are not traced
	      recursively into packages; dependencies are only generated for
	      home-package modules on external-package modules directly imported
	      by the home package module.
	      This option is normally
1145
              only used by the various system libraries.</para>
1146
1147
1148
1149
1150
	    </listitem>
	  </varlistentry>
	</variablelist>

    </sect2>
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164

    <sect2 id="orphan-modules">
      <title>Orphan modules and instance declarations</title>

<para> Haskell specifies that when compiling module M, any instance
declaration in any module "below" M is visible.  (Module A is "below"
M if A is imported directly by M, or if A is below a module that M imports directly.)
In principle, GHC must therefore read the interface files of every module below M,
just in case they contain an instance declaration that matters to M.  This would
be a disaster in practice, so GHC tries to be clever. </para>

<para>In particular, if an instance declaration is in the same module as the definition
of any type or class mentioned in the head of the instance declaration, then
GHC has to visit that interface file anyway.  Example:</para>
1165
<programlisting>
1166
  module A where
1167
    instance C a =&gt; D (T a) where ...
1168
    data T a = ...
1169
</programlisting>
1170
1171
1172
1173
1174
<para> The instance declaration is only relevant if the type T is in use, and if
so, GHC will have visited A's interface file to find T's definition. </para>

<para> The only problem comes when a module contains an instance declaration
and GHC has no other reason for visiting the module.  Example:
1175
<programlisting>
1176
  module Orphan where
1177
    instance C a =&gt; D (T a) where ...
1178
    class C a where ...
1179
</programlisting>
1180
1181
1182
1183
Here, neither D nor T is declared in module Orphan.
We call such modules ``orphan modules'',
defined thus:</para>
<itemizedlist>
sof's avatar
sof committed
1184
  <listitem> <para> An <emphasis>orphan module</emphasis>
1185
  <indexterm><primary>orphan module</primary></indexterm>
sof's avatar
sof committed
1186
  contains at least one <emphasis>orphan instance</emphasis> or at
1187
1188
1189
1190
1191
  least one <emphasis>orphan rule</emphasis>.</para> </listitem>

  <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
  <indexterm><primary>orphan instance</primary></indexterm>
  none of the type constructors
1192
  or classes mentioned in the instance head (the part after the ``<literal>=&gt;</literal>'') are declared
sof's avatar
sof committed
1193
  in M.</para>
1194

sof's avatar
sof committed
1195
  <para> Only the instance head counts.  In the example above, it is not good enough for C's declaration
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
  to be in module A; it must be the declaration of D or T.</para>
  </listitem>

  <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
  <indexterm><primary>orphan rule</primary></indexterm>
  if none of the variables, type constructors,
  or classes that are free in the left hand side of the rule are declared in M.
  </para> </listitem>
 </itemizedlist>


<para> GHC identifies orphan modules, and visits the interface file of
every orphan module below the module being compiled.  This is usually
wasted work, but there is no avoiding it.  You should therefore do
your best to have as few orphan modules as possible.

1212
1213
1214
1215
1216
1217
</para>

<para> You can identify an orphan module by looking in its interface
file, <filename>M.hi</filename>, using the
<option>--show-iface</option>.  If there is a ``!'' on the first line,
GHC considers it an orphan module.
1218
1219
1220
</para>
</sect2>

1221
1222
1223
1224
  </sect1>

<!-- Emacs stuff:
     ;;; Local Variables: ***
1225
     ;;; mode: xml ***
1226
     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1227
1228
     ;;; End: ***
 -->