separate_compilation.sgml 43.5 KB
Newer Older
1
  <sect1 id="separate-compilation">
2
    <title>Filenames and separate compilation</title>
3
4
5
6
7
    
    <indexterm><primary>separate compilation</primary></indexterm>
    <indexterm><primary>recompilation checker</primary></indexterm>
    <indexterm><primary>make and recompilation</primary></indexterm>
    
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
    <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
    linkend="hierarchical-modules">); hierarchical modules are an
    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>
    
      <para>Each Haskell source module should be placed in a file on
      its own.</para>

      <para>The file should usually be named after the module name, by
      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>,
      relative to some base directory.  GHC's behaviour if this rule
      is not followed is fully defined by the following section (<xref
      linkend="output-files">).</para>
    </sect2>

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

47
48
      <indexterm><primary>interface files</primary></indexterm>
      <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
49
50
      <indexterm><primary>object files</primary></indexterm>
      <indexterm><primary><literal>.o</literal> files</primary></indexterm>
51
      
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
      <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
      <literal>.o</literal> suffix (or <literal>.obj</literal> if
      you're on Windows), contains the compiled code for the module.</para>

      <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
      linkend="hi-options">).</para>

      <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
      ...</literal>).  Unless overridden with the
      <literal>-o</literal> and <literal>-ohi</literal> flags
      respectively, GHC always puts the object file for module
      <literal>A.B.C</literal> in
      <replaceable>odir</replaceable><literal>/A/B/C.</literal><replaceable>osuf</replaceable>,
      and the interface file in the file
      <replaceable>hidir</replaceable><literal>/A/B/C.</literal><replaceable>hisuf</replaceable>,
      where <replaceable>hidir</replaceable>,
      <replaceable>hisuf</replaceable>,
      <replaceable>odir</replaceable>, and
      <replaceable>osuf</replaceable>, defined as follows:

      <variablelist>
	<varlistentry>
	  <term><replaceable>hidir</replaceable></term>
	  <listitem>
	    <para>is the value of the <option>-hidir</option> option if
99
	    one was given (<xref linkend="options-output">), or
100
101
102
103
104
105
106
	    <replaceable>root-path</replaceable> otherwise.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><replaceable>hisuf</replaceable></term>
	  <listitem>
	    <para>is the value of the <option>-hisuf</option> option if
107
	    one was given (<xref linkend="options-output">), or <literal>hi</literal>
108
109
110
111
112
113
114
115
	    otherwise.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><replaceable>odir</replaceable></term>
	  <listitem>
	    <para>is the value of the <option>-odir</option> option if
116
	    one was given (<xref linkend="options-output">), or
117
118
119
120
121
122
123
	    <replaceable>root-path</replaceable> otherwise.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><replaceable>osuf</replaceable></term>
	  <listitem>
	    <para>is the value of the <option>-osuf</option> option if
124
	    one was given (<xref linkend="options-output">), or <literal>o</literal>
125
126
127
128
	    otherwise (<literal>obj</literal> on Windows).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
129

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
      The <replaceable>root-path</replaceable>, used in the above definitions, is derived from the
      location of the source file, <replaceable>source-filename</replaceable>, as follows:

  <variablelist>
  <varlistentry>
  <term>Rule 1</term>
  <listitem>
  <para>GHC matches <replaceable>source-filename</replaceable> against the pattern:
  
  <screen><replaceable>root-path</replaceable>/<literal>A/B/C.</literal><replaceable>extension</replaceable></screen>

      where:

      <variablelist>
	<varlistentry>
	  <term><replaceable>extension</replaceable></term>
	  <listitem>
	    <para>is the source file extension (usually
	    <literal>.hs</literal> or <literal>.lhs</literal>).</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><replaceable>root-path</replaceable></term>
	  <listitem>
	    <para>is what is left after <literal>A/B/C.</literal><replaceable>extension</replaceable>
	    has been stripped off the end of <replaceable>source-file</replaceable>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
  </para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term>Rule 2</term>
  <listitem>
	<para>If <replaceable>source-filename</replaceable> does not match the pattern
	above (presumably because it doesn't finish with <literal>A/B/C.hs</literal>
	or <literal>A/B/C.lhs</literal>)
	then <replaceable>root-path</replaceable> becomes the
	whole of the directory portion of the filename.  </para>
  </listitem>
  </varlistentry>
  </variablelist>

      For example, if GHC compiles the module
      <literal>A.B.C</literal> in the file
      <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> (using Rule 1).
      If the same module <literal>A.B.C</literal> was in file 
      <filename>src/ABC.hs</filename>, 
      the interface file will still be put in <literal>src/A/B/C.hi</literal> and the object file in 
      <literal>src/A/B/C.o</literal> (using Rule 2).
      </para>
      <para>A common use for Rule 2 is to have many modules all called <literal>Main</literal> held in 
      files <literal>Test1.hs</literal> <literal>Test2.hs</literal>, etc.    Beware, though: when compiling
      (say) <literal>Test2.hs</literal>, GHC will consult <literal>Main.hi</literal> for version information
      from the last recompilation.  Currently (a bug, really) GHC is not clever enough to spot that the source file has changed,
      and so there is a danger that the recompilation checker will declare that no recompilation is needed when in fact it is.
      Solution: delete the interface file first.
      </para>
  <para>Notice that (unless overriden with <option>-o</option> or <option>-ohi</option>) the filenames
  of the object and interface files are always based on the module name. The reason for this is so that
  GHC can find the interface file for module <literal>A.B.C</literal> when compiling the declaration
  "<literal>import A.B.C</literal>".
  </para>
197
198
    </sect2>

199
200
    <sect2 id="search-path">
      <title>The search path</title>
201

202
203
      <indexterm><primary>search path</primary>
      </indexterm>
204
205
206
207
208
      <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>.
209
210
211
212
213
214
215
      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>
216

217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
      <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>
241

242
      <variablelist>
243
	<varlistentry>
244
	  <term><option>-i<replaceable>dirs</replaceable></option></term>
245
	  <listitem>
246
	    <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
247
            </primary></indexterm>This flag appends a colon-separated
248
249
250
            list of <filename>dirs</filename> to the search path.</para>
	  </listitem>
	</varlistentry>
251

252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
	<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
      packages (<xref linkend="packages">), for details.</para>
    </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>
	  <term><option>-o</option> <replaceable>file</replaceable></term>
	  <indexterm><primary><option>-o</option></primary></indexterm>
	  <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>
282

283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
	    <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>
309
310
311
312
	  </listitem>
	</varlistentry>

	<varlistentry>
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
	  <term><option>-odir</option> <replaceable>dir</replaceable></term>
	  <indexterm><primary><option>-odir</option></primary></indexterm>
	  <listitem>
	    <para>Redirects object files to directory
	    <replaceable>dir</replaceable>.  For example:</para>

<Screen>
$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
</Screen>

	    <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>
	  <term><option>-ohi</option>  <replaceable>file</replaceable></term>
	  <indexterm><primary><option>-ohi</option></primary>
	  </indexterm>
	  <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>
      
	<varlistentry>
	  <term><option>-hidir</option>  <replaceable>dir</replaceable></term>
	  <indexterm><primary><option>-hidir</option></primary>
	  </indexterm>
369
	  <listitem>
370
371
372
	    <para>Redirects all generated interface files into
	    <replaceable>dir</replaceable>, instead of the
	    default.</para>
373
374
375
	  </listitem>
	</varlistentry>

376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
	<varlistentry>
	  <term><option>-osuf</option> <replaceable>suffix</replaceable></term>
	  <term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
	  <term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
	  <indexterm><primary><option>-osuf</option></primary></indexterm>
	  <indexterm><primary><option>-hisuf</option></primary></indexterm>
	  <indexterm><primary><option>-hcsuf</option></primary></indexterm>
	  <listitem>
	    <para>EXOTICA: The <option>-osuf</option>
            <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
            interface files (see <XRef LinkEnd="hi-options">).</para>

	    <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:
	    <Screen>
	      ghc ...</Screen>
	    to get the ordinary version, and
	    <Screen>
	      ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen>
	    to get the profiled version.</para>
	  </listitem>
	</varlistentry>
413
      </variablelist>
414
415
416
417
418
419
420
421
422
423
    </sect2>

    <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>
424

425
426
427
      <para>The following options are useful for keeping certain
      intermediate files around, when normally GHC would throw these
      away after compilation:</para>
428

429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
      <variablelist>
	<varlistentry>
	  <term><option>-keep-hc-files</option></term>
	  <indexterm>
	    <primary><option>-keep-hc-files</option></primary>
	  </indexterm>
	  <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>
	  <term><option>-keep-s-files</option></term>
	  <indexterm>
	    <primary><option>-keep-s-files</option></primary>
	  </indexterm>
	  <listitem>
	    <para>Keep intermediate <literal>.s</literal> files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-keep-raw-s-files</option></term>
	  <indexterm>
	    <primary><option>-keep-raw-s-files</option></primary>
	  </indexterm>
	  <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>
	  <term><option>-keep-tmp-files</option></term>
	  <indexterm>
	    <primary><option>-keep-tmp-files</option></primary>
	  </indexterm>
	  <indexterm>
	    <primary>temporary files</primary>
	    <secondary>keeping</secondary>
	  </indexterm>
	  <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
	    linkend="temp-files">).  Running GHC with
	    <option>-v</option> will show you what temporary files
	    were generated along the way.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
488
489
    </sect2>

490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
    <sect2 id="temp-files">
      <title>Redirecting temporary files</title>

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

      <variablelist>
	<varlistentry>
	  <term><option>-tmpdir</option></term>
	  <indexterm><primary><option>-tmpdir</option></primary></indexterm>
	  <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
            &lt;dir&gt;</option><IndexTerm><Primary>-tmpdir
            &lt;dir&gt; option</Primary></IndexTerm> option to specify
            an alternate directory.  For example, <option>-tmpdir
            .</option> says to put temporary files in the current
            working directory.</para>

	    <para>Alternatively, use your <Constant>TMPDIR</Constant>
            environment variable.<IndexTerm><Primary>TMPDIR
            environment variable</Primary></IndexTerm> Set it to the
            name of the directory where temporary files should be put.
            GCC and other programs will honour the
            <Constant>TMPDIR</Constant> variable as well.</para>

	    <para>Even better idea: Set the
            <Constant>DEFAULT_TMPDIR</Constant> make variable when
            building GHC, and never worry about
            <Constant>TMPDIR</Constant> again. (see the build
            documentation).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
528
529
    </sect2>

530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
    <Sect2 id="hi-options">
      <title>Other options related to interface files</title>
      <indexterm><primary>interface files, options</primary></indexterm>

      <variablelist>
	<varlistentry>
	  <term><option>-ddump-hi</option></term>
	  <indexterm><primary><option>-ddump-hi</option></primary>
	  </indexterm>
	  <listitem>
	    <para>Dumps the new interface to standard output.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-ddump-hi-diffs</option></term>
	  <indexterm><primary><option>-ddump-hi-diffs</option></primary>
	  </indexterm>
	  <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>
	  <term><option>-ddump-minimal-imports</option></term>
	  <indexterm><primary><option>-ddump-minimal-imports</option></primary>
	  </indexterm>
	  <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>
576
577
578
579
580
581
582
583
584
585
586
587

	<varlistentry>
	  <term><option>--show-iface</option>
	  <replaceable>file</replaceable></term>
	  <indexterm><primary><option>--show-iface</option></primary>
	  </indexterm>
	  <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>
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
      </variablelist>
    </sect2>

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

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

      <variablelist>
	<varlistentry>
	  <term><option>-no-recomp</option></term>
	  <indexterm><primary><option>-recomp</option></primary></indexterm>
	  <indexterm><primary><option>-no-recomp</option></primary></indexterm>
	  <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>
      
      <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
622
623
624
625
626
627
628
629
      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
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
      <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
      last compiled), and the reompilation checking is on, GHC will be
      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
      done (though the details have changed quite a bit). <ULink
      URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
      copy.</para>

    </sect2>

    <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>

<ProgramListing>
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
673
        rm -f $@
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
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
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
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
        $(HC) -o $@ $(HC_OPTS) $(OBJS)

# Standard suffix rules
.o.hi:
        @:

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

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

# 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
</ProgramListing>

      <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>

<ProgramListing>
%.o : %.lhs
        $(HC) -c $&#60; $(HC_OPTS)
</ProgramListing>

      <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>

      <para>Note the inter-module dependencies at the end of the
      Makefile, which take the form</para>

<ProgramListing>
Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
</ProgramListing>

      <para>They tell <command>make</command> that if any of
      <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
      preceding suffix rules does the job nicely.</para>

      <sect3 id="sec-makefile-dependencies">
	<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>

<ProgramListing>
depend :
        ghc -M $(HC_OPTS) $(SRCS)
</ProgramListing>

	<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
        cool&lowbar;pgm</command>.  <command>ghc -M</command> will
        append the needed dependencies to your
        <filename>Makefile</filename>.</para>

	<para>In general, if module <literal>A</literal> contains the
        line

<programlisting>
import B ...blah...
</programlisting>

	then <command>ghc -M</command> will generate a dependency line
        of the form:

<programlisting>
A.o : B.hi
</programlisting>

	If module <literal>A</literal> contains the line

<programlisting>
import {-# SOURCE #-} B ...blah...
</programlisting>

	then <command>ghc -M</command> will generate a dependency
	line of the form:

<programlisting>
A.o : B.hi-boot
</programlisting>

       (See <xref linkend="mutual-recursion"> for details of
       <literal>hi-boot</literal> style interface files.)  If
       <literal>A</literal> imports multiple modules, then there will
       be multiple lines with <filename>A.o</filename> as the
       target.</para>

        <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>

792
793
794
795
796
797
	<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
798
	<option>&ndash;&ndash;include-prelude</option> option below).</para>
799

800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
	<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>
      
	The options which affect dependency generation are:</para>
	
	<variablelist>
	  <varlistentry>
	    <term><option>-w</option></term>
	    <listitem>
	      <para>Turn off warnings about interface file shadowing.</para>
	    </listitem>
	  </varlistentry>
	  
	  <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>

	  <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>

	  <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>
872
	    <term><option>&ndash;&ndash;exclude-module=&lt;file&gt;</option></term>
873
874
875
876
877
878
879
880
881
882
	    <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>
883
	      <para>same as <option>&ndash;&ndash;exclude-module</option></para>
884
885
886
887
	    </listitem>
	  </varlistentry>

	  <varlistentry>
888
	    <term><option>&ndash;&ndash;exclude-directory=&lt;dirs&gt;</option></term>
889
890
891
892
893
894
895
896
897
	    <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>
898
	    <term><option>&ndash;&ndash;include-module=&lt;file&gt;</option></term>
899
900
901
902
	    <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
903
              the <option>&ndash;&ndash;exclude-directory</option> option.</para>
904
905
906
907
	    </listitem>
	  </varlistentry>

	  <varlistentry>
908
	    <term><option>&ndash;&ndash;include-prelude</option></term>
909
	    <listitem>
910
911
912
913
914
	      <para>Regard modules imported from packages as unstable,
              i.e., generate dependencies on the package modules used
              (including <literal>Prelude</literal>, and all other
              standard Haskell libraries).  This option is normally
              only used by the various system libraries.</para>
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
	    </listitem>
	  </varlistentry>
	</variablelist>

      </sect3>
    </sect2>

    <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>Currently, the compiler does not have proper support for
      dealing with mutually recursive modules:</para>

<ProgramListing>
module A where

import B

newtype TA = MkTA Int

f :: TB -&#62; TA
f (MkTB x) = MkTA x
--------
module B where

import A

data TB = MkTB !Int

g :: TA -&#62; TB
g (MkTA x) = MkTB x
</ProgramListing>

      <para>When compiling either module A and B, the compiler will
      try (in vain) to look for the interface file of the other. So,
      to get mutually recursive modules off the ground, you need to
      hand write an interface file for A or B, so as to break the
      loop.  These hand-written interface files are called
      <literal>hi-boot</literal> files, and are placed in a file
      called <filename>&lt;module&gt;.hi-boot</filename>.  To import
      from an <literal>hi-boot</literal> file instead of the standard
      <filename>.hi</filename> file, use the following syntax in the
      importing module: <indexterm><primary><literal>hi-boot</literal>
      files</primary></indexterm> <indexterm><primary>importing,
      <literal>hi-boot</literal> files</primary></indexterm></para>

<ProgramListing>
import {-# SOURCE #-} A
</ProgramListing>

      <para>The hand-written interface 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
      module that imports <literal>A</literal> recursively.</para>

      <para>For the example at hand, the boot interface file for A
      would look like the following:</para>

<ProgramListing>
979
980
module A where
newtype TA = MkTA GHC.Base.Int
981
982
</ProgramListing>

983
984
985
986
987
988
989
990
991
992
993
      <para>The syntax is similar to a normal Haskell source file, but
      with some important differences:</para>

      <itemizedlist>
	<listitem>
	  <para>Non-local entities must be qualified with their
	  <emphasis>original</emphasis> defining module.  Qualifying
	  by a module which just re-exports the entity won't do.  In
	  particular, most <literal>Prelude</literal> entities aren't
	  actually defined in the <literal>Prelude</literal> (see for
	  example <literal>GHC.Base.Int</literal> in the above
994
995
996
997
998
999
1000
1001
1002
	  example).  HINT: to find out the fully-qualified name for
	  entities in the <literal>Prelude</literal> (or anywhere for
	  that matter), try using GHCi's
	  <literal>:info</literal> command, eg.</para>
<programlisting>Prelude> :m -Prelude
> :i IO.IO
-- GHC.IOBase.IO is a type constructor
newtype GHC.IOBase.IO a
...</programlisting>
1003
1004
1005
1006
	</listitem>
	<listitem>
	  <para>Only <literal>data</literal>, <literal>type</literal>,
	  <literal>newtype</literal>, <literal>class</literal>, and
1007
1008
1009
	  type signature declarations may be included. You cannot declare
	  <literal>instances</literal> or derive them automatically.
</para>
1010
1011
	</listitem>
      </itemizedlist>
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023

      <para>Notice that we only put the declaration for the newtype
      <literal>TA</literal> in the <literal>hi-boot</literal> file,
      not the signature for <Function>f</Function>, since
      <Function>f</Function> isn't used by <literal>B</literal>.</para>

      <para>If you want an <literal>hi-boot</literal> file to export a
      data type, but you don't want to give its constructors (because
      the constructors aren't used by the SOURCE-importing module),
      you can write simply:</para>

<ProgramListing>
1024
1025
module A where
data TA
1026
1027
1028
1029
1030
</ProgramListing>

      <para>(You must write all the type parameters, but leave out the
      '=' and everything that follows it.)</para>
    </sect2>
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047


    <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>
<ProgramListing>
  module A where
1048
    instance C a =&gt; D (T a) where ...
1049
1050
1051
1052
1053
1054
1055
1056
1057
    data T a = ...
</ProgramListing>
<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:
<ProgramListing>
  module Orphan where
1058
    instance C a =&gt; D (T a) where ...
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
    class C a where ...
</ProgramListing>
Here, neither D nor T is declared in module Orphan.
We call such modules ``orphan modules'',
defined thus:</para>
<itemizedlist>
  <listitem> <para> An <emphasis>orphan module</emphasis> 
  <indexterm><primary>orphan module</primary></indexterm>
  contains at least one <emphasis>orphan instance</emphasis> or at 
  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
1073
  or classes mentioned in the instance head (the part after the ``<literal>=&gt;</literal>'') are declared
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
  in M.</para> 

  <para> Only the instance head counts.  In the example above, it is not good enough for C's declaration 
  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.

1093
1094
1095
1096
1097
1098
</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.
1099
1100
1101
</para>
</sect2>

1102
1103
1104
1105
1106
1107
1108
1109
  </sect1>

<!-- Emacs stuff:
     ;;; Local Variables: ***
     ;;; mode: sgml ***
     ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
     ;;; End: ***
 -->