using.sgml 96.5 KB
Newer Older
rrt's avatar
rrt committed
1
2
3
4
5
6
7
8
9
10
<Chapter id="using-GHC">
<Title>Using GHC
</Title>

<Para>
<IndexTerm><Primary>GHC, using</Primary></IndexTerm>
<IndexTerm><Primary>using GHC</Primary></IndexTerm>
GHC is a command-line compiler: in order to compile a Haskell program,
GHC must be invoked on the source file(s) by typing a command to the
shell.  The steps involved in compiling a program can be automated
rrt's avatar
rrt committed
11
using the <Command>make</Command> tool (this is especially useful if the program
rrt's avatar
rrt committed
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
consists of multiple source files which depend on each other).  This
section describes how to use GHC from the command-line.
</Para>

<Sect1 id="command-line-structure">
<Title>Overall command-line structure
</Title>

<Para>
<IndexTerm><Primary>structure, command-line</Primary></IndexTerm>
<IndexTerm><Primary>command-line structure</Primary></IndexTerm>
</Para>

<Para>
An invocation of GHC takes the following form:
</Para>

<Para>

<Screen>
ghc [argument...]
</Screen>

</Para>

<Para>
Command-line arguments are either options or file names.
</Para>

<Para>
Command-line options begin with <Literal>-</Literal>.  They may <Emphasis>not</Emphasis> be
rrt's avatar
rrt committed
43
44
grouped: <Option>-vO</Option> is different from <Option>-v -O</Option>.  Options need not
precede filenames: e.g., <Command>ghc *.o -o foo</Command>.  All options are
rrt's avatar
rrt committed
45
processed and then applied to all files; you cannot, for example, invoke
rrt's avatar
rrt committed
46
47
48
<Command>ghc -c -O1 Foo.hs -O2 Bar.hs</Command> to apply different optimisation
levels to the files <Filename>Foo.hs</Filename> and <Filename>Bar.hs</Filename>.  For conflicting
options, e.g., <Option>-c -S</Option>, we reserve the right to do anything we
rrt's avatar
rrt committed
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
want.  (Usually, the last one applies.)
</Para>

</Sect1>

<Sect1 id="file-suffixes">
<Title>Meaningful file suffixes
</Title>

<Para>
<IndexTerm><Primary>suffixes, file</Primary></IndexTerm>
<IndexTerm><Primary>file suffixes for GHC</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
64
65
File names with &ldquo;meaningful&rdquo; suffixes (e.g., <Filename>.lhs</Filename> or <Filename>.o</Filename>)
cause the &ldquo;right thing&rdquo; to happen to those files.
rrt's avatar
rrt committed
66
67
68
69
70
71
</Para>

<Para>
<VariableList>

<VarListEntry>
rrt's avatar
rrt committed
72
<Term><Filename>.lhs</Filename>:</Term>
rrt's avatar
rrt committed
73
74
75
<ListItem>
<Para>
<IndexTerm><Primary>lhs suffix</Primary></IndexTerm>
rrt's avatar
rrt committed
76
A &ldquo;literate Haskell&rdquo; module.
rrt's avatar
rrt committed
77
78
79
80
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
81
<Term><Filename>.hs</Filename>:</Term>
rrt's avatar
rrt committed
82
83
84
85
86
87
88
<ListItem>
<Para>
A not-so-literate Haskell module.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
89
<Term><Filename>.hi</Filename>:</Term>
rrt's avatar
rrt committed
90
91
92
93
94
95
96
<ListItem>
<Para>
A Haskell interface file, probably compiler-generated.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
97
<Term><Filename>.hc</Filename>:</Term>
rrt's avatar
rrt committed
98
99
100
101
102
103
104
<ListItem>
<Para>
Intermediate C file produced by the Haskell compiler.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
105
<Term><Filename>.c</Filename>:</Term>
rrt's avatar
rrt committed
106
107
108
109
110
111
112
<ListItem>
<Para>
A C&nbsp;file not produced by the Haskell compiler.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
113
<Term><Filename>.s</Filename>:</Term>
rrt's avatar
rrt committed
114
115
116
117
118
119
120
121
<ListItem>
<Para>
An assembly-language source file, usually
produced by the compiler.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
122
<Term><Filename>.o</Filename>:</Term>
rrt's avatar
rrt committed
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
<ListItem>
<Para>
An object file, produced by an assembler.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

<Para>
Files with other suffixes (or without suffixes) are passed straight
to the linker.
</Para>

</Sect1>

<Sect1 id="options-help">
<Title>Help and verbosity options
</Title>

<Para>
<IndexTerm><Primary>help options (GHC)</Primary></IndexTerm>
<IndexTerm><Primary>verbose option (GHC)</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
149
A good option to start with is the <Option>-help</Option> (or <Option>-?</Option>) option.
rrt's avatar
rrt committed
150
151
152
153
154
155
<IndexTerm><Primary>-help option</Primary></IndexTerm>
<IndexTerm><Primary>-? option</Primary></IndexTerm>
GHC spews a long message to standard output and then exits.
</Para>

<Para>
rrt's avatar
rrt committed
156
The <Option>-v</Option><IndexTerm><Primary>-v option</Primary></IndexTerm> option makes GHC <Emphasis>verbose</Emphasis>: it
rrt's avatar
rrt committed
157
158
reports its version number and shows (on stderr) exactly how it invokes each
phase of the compilation system.  Moreover, it passes
rrt's avatar
rrt committed
159
the <Option>-v</Option> flag to most phases; each reports
rrt's avatar
rrt committed
160
161
162
163
its version number (and possibly some other information).
</Para>

<Para>
rrt's avatar
rrt committed
164
Please, oh please, use the <Option>-v</Option> option when reporting bugs!
rrt's avatar
rrt committed
165
166
167
168
169
170
Knowing that you ran the right bits in the right order is always the
first thing we want to verify.
</Para>

<Para>
If you're just interested in the compiler version number, the
rrt's avatar
rrt committed
171
<Option>--version</Option><IndexTerm><Primary>--version option</Primary></IndexTerm> option prints out a
rrt's avatar
rrt committed
172
173
174
175
176
177
178
179
180
181
182
183
one-line string containing the requested info.
</Para>

</Sect1>

<Sect1 id="options-order">
<Title>Running the right phases in the right order
</Title>

<Para>
<IndexTerm><Primary>order of passes in GHC</Primary></IndexTerm>
<IndexTerm><Primary>pass ordering in GHC</Primary></IndexTerm>
rrt's avatar
rrt committed
184
The basic task of the <Command>ghc</Command> driver is to run each input file
rrt's avatar
rrt committed
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
through the right phases (compiling, linking, etc.).
</Para>

<Para>
The first phase to run is determined by the input-file suffix, and the
last phase is determined by a flag.  If no relevant flag is present,
then go all the way through linking.  This table summarises:
</Para>

<Para>
<InformalTable>
<TGroup Cols="4">
<ColSpec Align="Left">
<ColSpec Align="Left">
<ColSpec Align="Left">
<ColSpec Align="Left">
<TBody>

<Row>
<Entry>Phase of the compilation system</Entry>
rrt's avatar
rrt committed
205
206
<Entry>Suffix saying &ldquo;start here&rdquo;</Entry>
<Entry>Flag saying &ldquo;stop after&rdquo;</Entry>
rrt's avatar
rrt committed
207
208
209
210
211
212
213
214
215
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
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
<Entry>(suffix of) output file</Entry>
</Row>

<Row>
<Entry>
literate pre-processor </Entry>
<Entry> .lhs </Entry>
<Entry> - </Entry>
<Entry> - </Entry>
</Row>
<Row>
<Entry>
C pre-processor (opt.) </Entry>
<Entry> - </Entry>
<Entry> - </Entry>
<Entry> - </Entry>
</Row>
<Row>
<Entry>
Haskell compiler </Entry>
<Entry> .hs </Entry>
<Entry> -C, -S </Entry>
<Entry> .hc, .s </Entry>
</Row>
<Row>
<Entry>
C compiler (opt.) </Entry>
<Entry> .hc or .c </Entry>
<Entry> -S </Entry>
<Entry> .s </Entry>
</Row>
<Row>
<Entry>
assembler </Entry>
<Entry> .s </Entry>
<Entry> -c </Entry>
<Entry> .o </Entry>
</Row>
<Row>
<Entry>
linker </Entry>
<Entry> other </Entry>
<Entry> - </Entry>
<Entry> a.out </Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>

<IndexTerm><Primary>-C option</Primary></IndexTerm>
<IndexTerm><Primary>-S option</Primary></IndexTerm>
<IndexTerm><Primary>-c option</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
262
Thus, a common invocation would be: <Command>ghc -c Foo.hs</Command>
rrt's avatar
rrt committed
263
264
265
266
267
268
269
270
271
</Para>

<Para>
Note: What the Haskell compiler proper produces depends on whether a
native-code generator is used (producing assembly language) or not
(producing C).
</Para>

<Para>
rrt's avatar
rrt committed
272
The option <Option>-cpp</Option><IndexTerm><Primary>-cpp option</Primary></IndexTerm> must be given for the C
rrt's avatar
rrt committed
273
274
275
276
277
pre-processor phase to be run, that is, the pre-processor will be run
over your Haskell source file before continuing.
</Para>

<Para>
rrt's avatar
rrt committed
278
The option <Option>-E</Option><IndexTerm><Primary>-E option</Primary></IndexTerm> runs just the pre-processing
rrt's avatar
rrt committed
279
280
281
passes of the compiler, outputting the result on stdout before
stopping. If used in conjunction with -cpp, the output is the
code blocks of the original (literal) source after having put it
rrt's avatar
rrt committed
282
through the grinder that is the C pre-processor. Sans <Option>-cpp</Option>, the
rrt's avatar
rrt committed
283
284
285
286
output is the de-litted version of the original source.
</Para>

<Para>
rrt's avatar
rrt committed
287
The option <Option>-optcpp-E</Option><IndexTerm><Primary>-optcpp-E option</Primary></IndexTerm> runs just the
rrt's avatar
rrt committed
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
pre-processing stage of the C-compiling phase, sending the result to
stdout.  (For debugging or obfuscation contests, usually.)
</Para>

</Sect1>

<Sect1 id="options-output">
<Title>Re-directing the compilation output(s)
</Title>

<Para>
<IndexTerm><Primary>output-directing options</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
303
304
305
306
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
foo</Option><IndexTerm><Primary>-o option</Primary></IndexTerm> re-directs the output of that last-run
phase to file <Filename>foo</Filename>.
rrt's avatar
rrt committed
307
308
309
</Para>

<Para>
rrt's avatar
rrt committed
310
Note: this &ldquo;feature&rdquo; can be counterintuitive:
rrt's avatar
rrt committed
311
312
<Command>ghc -C -o foo.o foo.hs</Command> will put the intermediate C code in the
file <Filename>foo.o</Filename>, name notwithstanding!
rrt's avatar
rrt committed
313
314
315
</Para>

<Para>
rrt's avatar
rrt committed
316
EXOTICA: But the <Option>-o</Option> option isn't of much use if you have
rrt's avatar
rrt committed
317
318
319
<Emphasis>several</Emphasis> input files&hellip; Non-interface output files are
normally put in the same directory as their corresponding input file
came from.  You may specify that they be put in another directory
rrt's avatar
rrt committed
320
using the <Option>-odir &lt;dir&gt;</Option><IndexTerm><Primary>-odir &lt;dir&gt; option</Primary></IndexTerm> (the
rrt's avatar
rrt committed
321
&ldquo;Oh, dear&rdquo; option).  For example:
rrt's avatar
rrt committed
322
323
324
325
326
327
328
329
330
331
332
</Para>

<Para>

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

</Para>

<Para>
rrt's avatar
rrt committed
333
The output files, <Filename>Foo.o</Filename>, <Filename>Bar.o</Filename>, and <Filename>Bumble.o</Filename> would be
rrt's avatar
rrt committed
334
put into a subdirectory named after the architecture of the executing
rrt's avatar
rrt committed
335
machine (<Filename>sun4</Filename>, <Filename>mips</Filename>, etc).  The directory must already
rrt's avatar
rrt committed
336
337
338
339
exist; it won't be created.
</Para>

<Para>
rrt's avatar
rrt committed
340
Note that the <Option>-odir</Option> option does <Emphasis>not</Emphasis> affect where the
rrt's avatar
rrt committed
341
interface files are put.  In the above example, they would still be
rrt's avatar
rrt committed
342
put in <Filename>parse/Foo.hi</Filename>, <Filename>parse/Bar.hi</Filename>, and <Filename>gurgle/Bumble.hi</Filename>.
rrt's avatar
rrt committed
343
344
345
</Para>

<Para>
rrt's avatar
rrt committed
346
347
MORE EXOTICA: The <Option>-osuf &lt;suffix&gt;</Option><IndexTerm><Primary>-osuf &lt;suffix&gt;
option</Primary></IndexTerm> will change the <Filename>.o</Filename> file suffix for object files to
rrt's avatar
rrt committed
348
whatever you specify.  (We use this in compiling the prelude.).
rrt's avatar
rrt committed
349
350
Similarly, the <Option>-hisuf &lt;suffix&gt;</Option><IndexTerm><Primary>-hisuf &lt;suffix&gt;
option</Primary></IndexTerm> will change the <Filename>.hi</Filename> file suffix for non-system
rrt's avatar
rrt committed
351
352
353
354
interface files (see <XRef LinkEnd="hi-options">).
</Para>

<Para>
rrt's avatar
rrt committed
355
The <Option>-hisuf</Option>/<Option>-osuf</Option> game is useful if you want to compile a program
rrt's avatar
rrt committed
356
with both GHC and HBC (say) in the same directory.  Let HBC use the
rrt's avatar
rrt committed
357
358
standard <Filename>.hi</Filename>/<Filename>.o</Filename> suffixes; add <Option>-hisuf g&lowbar;hi -osuf g&lowbar;o</Option> to your
<Command>make</Command> rule for GHC compiling&hellip;
rrt's avatar
rrt committed
359
360
</Para>

361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
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
413
414
415
416
417
418
419
    <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>

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

      <variablelist>
	<varlistentry>
	  <term><literal>-keep-hc-files</literal></term>
	  <indexterm>
	    <primary><literal>-keep-hc-files</literal></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 <literal>-fvia-C</literal> to force them
	    to be produced).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-keep-s-files</literal></term>
	  <indexterm>
	    <primary><literal>-keep-s-files</literal></primary>
	  </indexterm>
	  <listitem>
	    <para>Keep intermediate <literal>.s</literal> files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-keep-raw-s-files</literal></term>
	  <indexterm>
	    <primary><literal>-keep-raw-s-files</literal></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><literal>-keep-tmp-files</literal></term>
	  <indexterm>
	    <primary><literal>-keep-tmp-files</literal></primary>
	  </indexterm>
	  <indexterm>
420
	    <primary>temporary files</primary>
421
422
423
424
425
426
427
428
429
430
431
432
433
	    <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
	    <literal>-v</literal> will show you what temporary files
	    were generated along the way.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
rrt's avatar
rrt committed
434
435
436
437
438
439
440
441
442
443
444

<Sect2 id="saving-ghc-stderr">
<Title>Saving GHC's standard error output
</Title>

<Para>
<IndexTerm><Primary>standard error, saving</Primary></IndexTerm>
</Para>

<Para>
Sometimes, you may cause GHC to be rather chatty on standard error;
rrt's avatar
rrt committed
445
446
with <Option>-v</Option>, for example.  You can instruct GHC to <Emphasis>append</Emphasis> this
output to a particular log file with a <Option>-odump &lt;blah&gt;</Option><IndexTerm><Primary>-odump
rrt's avatar
rrt committed
447
448
449
450
451
452
453
454
455
&lt;blah&gt; option</Primary></IndexTerm> option.
</Para>

</Sect2>

<Sect2 id="temp-files">
<Title>Redirecting temporary files
</Title>

456
457
458
459
      <indexterm>
	<primary>temporary files</primary>
	<secondary>redirecting</secondary>
      </indexterm>
rrt's avatar
rrt committed
460
461

<Para>
462
463
464
465
466
467
468
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.
rrt's avatar
rrt committed
469
470
471
</Para>

<Para>
472
473
474
475
476
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.
rrt's avatar
rrt committed
477
478
479
</Para>

<Para>
rrt's avatar
rrt committed
480
481
Even better idea: Set the <Constant>TMPDIR</Constant> variable when building GHC, and
never worry about <Constant>TMPDIR</Constant> again. (see the build documentation).
rrt's avatar
rrt committed
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
</Para>

</Sect2>

</Sect1>

<Sect1 id="options-sanity">
<Title>Warnings and sanity-checking
</Title>

<Para>
<IndexTerm><Primary>sanity-checking options</Primary></IndexTerm>
<IndexTerm><Primary>warnings</Primary></IndexTerm>
GHC has a number of options that select which types of non-fatal error
messages, otherwise known as warnings, can be generated during
compilation.  By default, you get a standard set of warnings which are
generally likely to indicate bugs in your program.  These are:
rrt's avatar
rrt committed
499
500
<Option>-fwarn-overlpapping-patterns</Option>, <Option>-fwarn-duplicate-exports</Option>, and
<Option>-fwarn-missing-methods</Option>.  The following flags are simple ways to
rrt's avatar
rrt committed
501
select standard &ldquo;packages&rdquo; of warnings:
rrt's avatar
rrt committed
502
503
504
505
506
507
</Para>

<Para>
<VariableList>

<VarListEntry>
rrt's avatar
rrt committed
508
<Term><Option>-Wnot</Option>:</Term>
rrt's avatar
rrt committed
509
510
511
512
513
514
515
516
517
<ListItem>
<Para>
<IndexTerm><Primary>-Wnot option</Primary></IndexTerm>
Turns off all warnings, including the standard ones.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
518
<Term><Option>-w</Option>:</Term>
rrt's avatar
rrt committed
519
520
521
<ListItem>
<Para>
<IndexTerm><Primary>-w option</Primary></IndexTerm>
rrt's avatar
rrt committed
522
Synonym for <Option>-Wnot</Option>.
rrt's avatar
rrt committed
523
524
525
526
527
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
528
<Term><Option>-W</Option>:</Term>
rrt's avatar
rrt committed
529
530
531
<ListItem>
<Para>
<IndexTerm><Primary>-W option</Primary></IndexTerm>
rrt's avatar
rrt committed
532
533
Provides the standard warnings plus <Option>-fwarn-incomplete-patterns</Option>,
<Option>-fwarn-unused-imports</Option> and <Option>-fwarn-unused-binds</Option>.
rrt's avatar
rrt committed
534
535
536
537
538
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
539
<Term><Option>-Wall</Option>:</Term>
rrt's avatar
rrt committed
540
541
542
543
544
545
546
547
548
549
550
551
552
<ListItem>
<Para>
<IndexTerm><Primary>-Wall option</Primary></IndexTerm>
Turns on all warning options.
</Para>
</ListItem>
</VarListEntry>

</VariableList>
</Para>

<Para>
The full set of warning options is described below.  To turn off any
rrt's avatar
rrt committed
553
warning, simply give the corresponding <Option>-fno-warn-...</Option> option on
rrt's avatar
rrt committed
554
555
556
557
558
559
560
the command line.
</Para>

<Para>
<VariableList>

<VarListEntry>
rrt's avatar
rrt committed
561
<Term><Option>-fwarn-name-shadowing</Option>:</Term>
rrt's avatar
rrt committed
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-name-shadowing option</Primary></IndexTerm>
<IndexTerm><Primary>shadowing, warning</Primary></IndexTerm>This option causes a warning to be emitted whenever an inner-scope
value has the same name as an outer-scope value, i.e. the inner value
shadows the outer one.  This can catch typographical errors that turn
into hard-to-find bugs, e.g., in the inadvertent cyclic definition
<Literal>let x = ... x ... in</Literal>.
</Para>

<Para>
Consequently, this option does <Emphasis>not</Emphasis> allow cyclic recursive
definitions.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
580
<Term><Option>-fwarn-overlapping-patterns</Option>:</Term>
rrt's avatar
rrt committed
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-overlapping-patterns option</Primary></IndexTerm>
<IndexTerm><Primary>overlapping patterns, warning</Primary></IndexTerm>
<IndexTerm><Primary>patterns, overlapping</Primary></IndexTerm>
By default, the compiler will warn you if a set of patterns are
overlapping, i.e.,
</Para>

<Para>
<ProgramListing>
f :: String -&#62; Int
f []     = 0
f (_:xs) = 1
f "2"    = 2
</ProgramListing>
</Para>

<Para>
rrt's avatar
rrt committed
600
where the last pattern match in <Function>f</Function> won't ever be reached, as the
rrt's avatar
rrt committed
601
602
603
604
605
606
607
second pattern overlaps it. More often than not, redundant patterns
is a programmer mistake/error, so this option is enabled by default.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
608
<Term><Option>-fwarn-incomplete-patterns</Option>:</Term>
rrt's avatar
rrt committed
609
610
611
612
613
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-incomplete-patterns option</Primary></IndexTerm>
<IndexTerm><Primary>incomplete patterns, warning</Primary></IndexTerm>
<IndexTerm><Primary>patterns, incomplete</Primary></IndexTerm>
rrt's avatar
rrt committed
614
Similarly for incomplete patterns, the function <Function>g</Function> below will fail
rrt's avatar
rrt committed
615
when applied to non-empty lists, so the compiler will emit a warning
rrt's avatar
rrt committed
616
about this when <Option>-fwarn-incomplete-patterns</Option> is enabled.
rrt's avatar
rrt committed
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
</Para>

<Para>
<ProgramListing>
g [] = 2
</ProgramListing>
</Para>

<Para>
This option isn't enabled be default because it can be a bit noisy,
and it doesn't always indicate a bug in the program.  However, it's
generally considered good practice to cover all the cases in your
functions.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
635
<Term><Option>-fwarn-missing-methods</Option>:</Term>
rrt's avatar
rrt committed
636
637
638
639
640
641
642
643
644
645
646
647
648
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-methods option</Primary></IndexTerm>
<IndexTerm><Primary>missing methods, warning</Primary></IndexTerm>
<IndexTerm><Primary>methods, missing</Primary></IndexTerm>
This option is on by default, and warns you whenever an instance
declaration is missing one or more methods, and the corresponding
class declaration has no default declaration for them.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
649
<Term><Option>-fwarn-missing-fields</Option>:</Term>
rrt's avatar
rrt committed
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-fields option</Primary></IndexTerm>
<IndexTerm><Primary>missing fields, warning</Primary></IndexTerm>
<IndexTerm><Primary>fields, missing</Primary></IndexTerm>
This option is on by default, and warns you whenever the construction
of a labelled field constructor isn't complete, missing initializers
for one or more fields. While not an error (the missing fields are
initialised with bottoms), it is often an indication of a programmer
error.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
665
<Term><Option>-fwarn-unused-imports</Option>:</Term>
rrt's avatar
rrt committed
666
667
668
669
670
671
672
673
674
675
676
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-imports option</Primary></IndexTerm>
<IndexTerm><Primary>unused imports, warning</Primary></IndexTerm>
<IndexTerm><Primary>imports, unused</Primary></IndexTerm>
Report any objects that are explicitly imported but never used.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
677
<Term><Option>-fwarn-unused-binds</Option>:</Term>
rrt's avatar
rrt committed
678
679
680
681
682
683
684
685
686
687
688
689
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-binds option</Primary></IndexTerm>
<IndexTerm><Primary>unused binds, warning</Primary></IndexTerm>
<IndexTerm><Primary>binds, unused</Primary></IndexTerm>
Report any function definitions (and local bindings) which are unused.
For top-level functions, the warning is only given if the binding is
not exported.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
rrt's avatar
rrt committed
690
<Term><Option>-fwarn-unused-matches</Option>:</Term>
rrt's avatar
rrt committed
691
692
693
694
695
696
697
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-unused-matches option</Primary></IndexTerm>
<IndexTerm><Primary>unused matches, warning</Primary></IndexTerm>
<IndexTerm><Primary>matches, unused</Primary></IndexTerm>
Report all unused variables which arise from pattern matches,
including patterns consisting of a single variable.  For instance <Literal>f x
rrt's avatar
rrt committed
698
y = []</Literal> would report <VarName>x</VarName> and <VarName>y</VarName> as unused.  To eliminate the warning,
rrt's avatar
rrt committed
699
700
701
702
703
704
all unused variables can be replaced with wildcards.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
705
<Term><Option>-fwarn-duplicate-exports</Option>:</Term>
rrt's avatar
rrt committed
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-duplicate-exports option</Primary></IndexTerm>
<IndexTerm><Primary>duplicate exports, warning</Primary></IndexTerm>
<IndexTerm><Primary>export lists, duplicates</Primary></IndexTerm>
Have the compiler warn about duplicate entries in export lists. This
is useful information if you maintain large export lists, and want to
avoid the continued export of a definition after you've deleted (one)
mention of it in the export list.
</Para>

<Para>
This option is on by default.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
724
<Term><Option>-fwarn-type-defaults</Option>:</Term>
rrt's avatar
rrt committed
725
726
727
728
729
730
731
732
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-type-defaults option</Primary></IndexTerm>
<IndexTerm><Primary>defaulting mechanism, warning</Primary></IndexTerm>
Have the compiler warn/inform you where in your source the Haskell
defaulting mechanism for numeric types kicks in. This is useful
information when converting code from a context that assumed one
default into one with another, e.g., the `default default' for Haskell
rrt's avatar
rrt committed
733
1.4 caused the otherwise unconstrained value <Constant>1</Constant> to be given
rrt's avatar
rrt committed
734
735
736
737
738
739
740
741
742
743
744
745
the type <Literal>Int</Literal>, whereas Haskell 98 defaults it to
<Literal>Integer</Literal>.  This may lead to differences in performance and
behaviour, hence the usefulness of being non-silent about this.
</Para>

<Para>
This warning is off by default.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
746
<Term><Option>-fwarn-missing-signatures</Option>:</Term>
rrt's avatar
rrt committed
747
748
749
750
751
<ListItem>
<Para>
<IndexTerm><Primary>-fwarn-missing-signatures option</Primary></IndexTerm>
<IndexTerm><Primary>type signatures, missing</Primary></IndexTerm>
If you would like GHC to check that every top-level function/value has
rrt's avatar
rrt committed
752
a type signature, use the <Option>-fwarn-missing-signatures</Option> option.  This
rrt's avatar
rrt committed
753
754
755
756
757
758
759
760
option is off by default.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

<Para>
rrt's avatar
rrt committed
761
If you're feeling really paranoid, the <Option>-dcore-lint</Option>
rrt's avatar
rrt committed
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
option<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm> is a good choice.  It turns on
heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's
sanity, not yours.)
</Para>

</Sect1>

<Sect1 id="separate-compilation">
<Title>Separate compilation
</Title>

<Para>
<IndexTerm><Primary>separate compilation</Primary></IndexTerm>
<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
<IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
This section describes how GHC supports separate compilation.
</Para>

<Sect2 id="hi-files">
<Title>Interface files
</Title>

<Para>
<IndexTerm><Primary>interface files</Primary></IndexTerm>
<IndexTerm><Primary>.hi files</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
790
791
792
When GHC compiles a source file <Filename>F</Filename> which contains a module <Literal>A</Literal>, say,
it generates an object <Filename>F.o</Filename>, <Emphasis>and</Emphasis> a companion <Emphasis>interface
file</Emphasis> <Filename>A.hi</Filename>.  The interface file is not intended for human
rrt's avatar
rrt committed
793
794
795
796
797
798
consumption, as you'll see if you take a look at one.  It's merely
there to help the compiler compile other modules in the same program.
</Para>

<Para>
NOTE: Having the name of the interface file follow the module name and
rrt's avatar
rrt committed
799
800
not the file name, means that working with tools such as <Command>make</Command>
become harder. <Command>make</Command> implicitly assumes that any output files
rrt's avatar
rrt committed
801
802
803
804
805
806
807
808
809
produced by processing a translation unit will have file names that
can be derived from the file name of the translation unit.  For
instance, pattern rules becomes unusable.  For this reason, we
recommend you stick to using the same file name as the module name.
</Para>

<Para>
The interface file for <Literal>A</Literal> contains information needed by the compiler
when it compiles any module <Literal>B</Literal> that imports <Literal>A</Literal>, whether directly or
rrt's avatar
rrt committed
810
indirectly.  When compiling <Literal>B</Literal>, GHC will read <Filename>A.hi</Filename> to find the
rrt's avatar
rrt committed
811
812
813
814
815
816
817
details that it needs to know about things defined in <Literal>A</Literal>.
</Para>

<Para>
Furthermore, when compiling module <Literal>C</Literal> which imports <Literal>B</Literal>, GHC may
decide that it needs to know something about <Literal>A</Literal>&mdash;for example, <Literal>B</Literal>
might export a function that involves a type defined in <Literal>A</Literal>.  In this
rrt's avatar
rrt committed
818
case, GHC will go and read <Command>A.hi</Command> even though <Literal>C</Literal> does not explicitly
rrt's avatar
rrt committed
819
820
821
822
823
824
import <Literal>A</Literal> at all.
</Para>

<Para>
The interface file may contain all sorts of things that aren't
explicitly exported from <Literal>A</Literal> by the programmer.  For example, even
rrt's avatar
rrt committed
825
826
though a data type is exported abstractly, <Filename>A.hi</Filename> will contain the
full data type definition.  For small function definitions, <Filename>A.hi</Filename>
rrt's avatar
rrt committed
827
will contain the complete definition of the function.  For bigger
rrt's avatar
rrt committed
828
829
830
831
functions, <Filename>A.hi</Filename> will contain strictness information about the
function.  And so on.  GHC puts much more information into <Filename>.hi</Filename> files
when optimisation is turned on with the <Option>-O</Option> flag.  Without <Option>-O</Option> it
puts in just the minimum; with <Option>-O</Option> it lobs in a whole pile of stuff.
rrt's avatar
rrt committed
832
833
834
835
<IndexTerm><Primary>optimsation, effect on .hi files</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
836
837
838
<Filename>A.hi</Filename> should really be thought of as a compiler-readable version of
<Filename>A.o</Filename>.  If you use a <Filename>.hi</Filename> file that wasn't generated by the same
compilation run that generates the <Filename>.o</Filename> file the compiler may assume
rrt's avatar
rrt committed
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
all sorts of incorrect things about <Literal>A</Literal>, resulting in core dumps and
other unpleasant happenings.
</Para>

</Sect2>

<Sect2 id="options-finding-imports">
<Title>Finding interface files
</Title>

<Para>
<IndexTerm><Primary>interface files, finding them</Primary></IndexTerm>
<IndexTerm><Primary>finding interface files</Primary></IndexTerm>
</Para>

<Para>
In your program, you import a module <Literal>Foo</Literal> by saying
rrt's avatar
rrt committed
856
857
<Literal>import Foo</Literal>.  GHC goes looking for an interface file, <Filename>Foo.hi</Filename>.
It has a builtin list of directories (notably including <Filename>.</Filename>) where
rrt's avatar
rrt committed
858
859
860
861
862
863
864
it looks.
</Para>

<Para>
<VariableList>

<VarListEntry>
rrt's avatar
rrt committed
865
<Term><Option>-i&lt;dirs&gt;</Option></Term>
rrt's avatar
rrt committed
866
867
868
<ListItem>
<Para>
<IndexTerm><Primary>-i&lt;dirs&gt; option</Primary></IndexTerm>This flag
rrt's avatar
rrt committed
869
870
prepends a colon-separated list of <Filename>dirs</Filename> to the &ldquo;import
directories&rdquo; list.
rrt's avatar
rrt committed
871
See also <XRef LinkEnd="recomp"> for the significance of using
rrt's avatar
rrt committed
872
relative and absolute pathnames in the <Option>-i</Option> list.
rrt's avatar
rrt committed
873
874
875
876
877
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
878
<Term><Option>-i</Option></Term>
rrt's avatar
rrt committed
879
880
<ListItem>
<Para>
rrt's avatar
rrt committed
881
resets the &ldquo;import directories&rdquo; list back to nothing.
rrt's avatar
rrt committed
882
883
884
885
886
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
887
<Term><Option>-fno-implicit-prelude</Option></Term>
rrt's avatar
rrt committed
888
889
890
<ListItem>
<Para>
<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
rrt's avatar
rrt committed
891
892
GHC normally imports <Filename>Prelude.hi</Filename> files for you.  If you'd rather it
didn't, then give it a <Option>-fno-implicit-prelude</Option> option.  You are
rrt's avatar
rrt committed
893
894
895
896
897
898
899
unlikely to get very far without a Prelude, but, hey, it's a free
country.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
rrt's avatar
rrt committed
900
<Term><Option>-I&lt;dir&gt;</Option></Term>
rrt's avatar
rrt committed
901
902
903
<ListItem>
<Para>
<IndexTerm><Primary>-I&lt;dir&gt; option</Primary></IndexTerm>
rrt's avatar
rrt committed
904
905
906
907
Once a Haskell module has been compiled to C (<Filename>.hc</Filename> file), you may
wish to specify where GHC tells the C compiler to look for <Filename>.h</Filename> files.
(Or, if you are using the <Option>-cpp</Option> option<IndexTerm><Primary>-cpp option</Primary></IndexTerm>, where
it tells the C pre-processor to look&hellip;)  For this purpose, use a <Option>-I</Option>
rrt's avatar
rrt committed
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
option in the usual C-ish way.
</Para>
</ListItem>
</VarListEntry>

</VariableList>
</Para>

</Sect2>

<Sect2 id="hi-options">
<Title>Other options related to interface files
</Title>

<Para>
<IndexTerm><Primary>interface files, options</Primary></IndexTerm>
The interface output may be directed to another file
rrt's avatar
rrt committed
925
<Filename>bar2/Wurble.iface</Filename> with the option <Option>-ohi bar2/Wurble.iface</Option><IndexTerm><Primary>-ohi
rrt's avatar
rrt committed
926
927
928
929
&lt;file&gt; option</Primary></IndexTerm> (not recommended).
</Para>

<Para>
rrt's avatar
rrt committed
930
To avoid generating an interface file at all, use a <Option>-nohi</Option>
rrt's avatar
rrt committed
931
932
933
934
option.<IndexTerm><Primary>-nohi option</Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
935
The compiler does not overwrite an existing <Filename>.hi</Filename> interface file if
rrt's avatar
rrt committed
936
the new one is byte-for-byte the same as the old one; this is friendly
rrt's avatar
rrt committed
937
938
939
to <Command>make</Command>.  When an interface does change, it is often enlightening to
be informed.  The <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm> option will
make GHC run <Command>diff</Command> on the old and new <Filename>.hi</Filename> files. You can also
rrt's avatar
rrt committed
940
record the difference in the interface file itself, the
rrt's avatar
rrt committed
941
<Option>-keep-hi-diffs</Option><IndexTerm><Primary>-keep-hi-diffs</Primary></IndexTerm> option takes care of that.
rrt's avatar
rrt committed
942
943
944
</Para>

<Para>
rrt's avatar
rrt committed
945
The <Filename>.hi</Filename> files from GHC contain &ldquo;usage&rdquo; information which changes
rrt's avatar
rrt committed
946
947
often and uninterestingly.  If you really want to see these changes
reported, you need to use the
rrt's avatar
rrt committed
948
<Option>-hi-diffs-with-usages</Option><IndexTerm><Primary>-hi-diffs-with-usages option</Primary></IndexTerm>
rrt's avatar
rrt committed
949
950
951
952
953
954
955
956
option.
</Para>

<Para>
Interface files are normally jammed full of compiler-produced
<Emphasis>pragmas</Emphasis>, which record arities, strictness info, etc.  If you
think these pragmas are messing you up (or you are doing some kind of
weird experiment), you can tell GHC to ignore them with the
rrt's avatar
rrt committed
957
<Option>-fignore-interface-pragmas</Option><IndexTerm><Primary>-fignore-interface-pragmas
rrt's avatar
rrt committed
958
959
960
961
962
963
964
965
option</Primary></IndexTerm> option.
</Para>

<Para>
When compiling without optimisations on, the compiler is extra-careful
about not slurping in data constructors and instance declarations that
it will not need. If you believe it is getting it wrong and not
importing stuff which you think it should, this optimisation can be
rrt's avatar
rrt committed
966
turned off with <Option>-fno-prune-tydecls</Option> and <Option>-fno-prune-instdecls</Option>.
rrt's avatar
rrt committed
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
<IndexTerm><Primary>-fno-prune-tydecls option</Primary></IndexTerm><IndexTerm><Primary>-fno-prune-instdecls
option</Primary></IndexTerm>
</Para>

<Para>
See also <XRef LinkEnd="options-linker">, which describes how the linker finds standard
Haskell libraries.
</Para>

</Sect2>

<Sect2 id="recomp">
<Title>The recompilation checker
</Title>

<IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
983
984
985
986
987
988
989
990

<Para>
<variablelist>
<VarListEntry>
<Term><Option>-recomp</Option></Term>
<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
<ListItem>
<Para>
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
(On by default) Turn on recompilation checking.  This will stop
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>
<VarListEntry>
<Term><Option>-no-recomp</Option></Term>
<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
<ListItem>
<Para>
Turn off recompilation checking.
1004
1005
1006
1007
</Para>
</ListItem>
</VarListEntry>
</VariableList>
rrt's avatar
rrt committed
1008
1009
1010
</Para>

<Para>
1011
1012
1013
1014
1015
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.
rrt's avatar
rrt committed
1016
1017
1018
</Para>

<Para>
1019
1020
1021
1022
1023
1024
1025
This doesn't work any more.  In our earlier example, module
<Literal>C</Literal> does not import module <Literal>A</Literal>
directly, yet changes to <Filename>A.hi</Filename> should force a
recompilation of <Literal>C</Literal>.  And some changes to
<Literal>A</Literal> (changing the definition of a function that
appears in an inlining of a function exported by <Literal>B</Literal>,
say) may conceivably not change <Filename>B.hi</Filename> one jot.  So
rrt's avatar
rrt committed
1026
1027
1028
1029
1030
1031
1032
1033
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
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
than the <Filename>.o</Filename> file's date (i.e. the source hasn't
changed since the file was last compiled), and the
<option>-recomp</option> is given on the command line, 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>
rrt's avatar
rrt committed
1046
1047
1048
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>
1049

rrt's avatar
rrt committed
1050
1051
</Sect2>

rrt's avatar
rrt committed
1052

rrt's avatar
rrt committed
1053
<Sect2 id="using-make">
rrt's avatar
rrt committed
1054
<Title>Using <Command>make</Command>
rrt's avatar
rrt committed
1055
1056
1057
1058
1059
1060
1061
</Title>

<Para>
<IndexTerm><Primary><literal>make</literal></Primary></IndexTerm>
</Para>

<Para>
rrt's avatar
rrt committed
1062
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.
rrt's avatar
rrt committed
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
Thus:
</Para>

<Para>

<ProgramListing>
HC      = ghc
HC_OPTS = -cpp $(EXTRA_HC_OPTS)

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

rrt's avatar
rrt committed
1075
.SUFFIXES : .o .hs .hi .lhs .hc .s
rrt's avatar
rrt committed
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098

cool_pgm : $(OBJS)
        rm $@
        $(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>

<Para>
rrt's avatar
rrt committed
1099
1100
(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
rrt's avatar
rrt committed
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
comprehensible:
</Para>

<Para>

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

</Para>

<Para>
rrt's avatar
rrt committed
1114
What we've shown should work with any <Command>make</Command>.)
rrt's avatar
rrt committed
1115
1116
1117
1118
</Para>

<Para>
Note the cheesy <Literal>.o.hi</Literal> rule: It records the dependency of the
rrt's avatar
rrt committed
1119
1120
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.
rrt's avatar
rrt committed
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
</Para>

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

<Para>

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

</Para>

<Para>
rrt's avatar
rrt committed
1137
They tell <Command>make</Command> that if any of <Literal>Foo.o</Literal>, <Literal>Foo.hc</Literal> or <Literal>Foo.s</Literal> have an
rrt's avatar
rrt committed
1138
1139
1140
1141
1142
1143
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>

1144
    </sect2>
rrt's avatar
rrt committed
1145

1146
1147
    <sect2 id="sec-makefile-dependencies">
      <title>Dependency generation</title>
1148
1149
1150
1151
1152
1153
1154
1155
      <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>
rrt's avatar
rrt committed
1156
1157
1158

<ProgramListing>
depend :
1159
        ghc -M $(HC_OPTS) $(SRCS)
rrt's avatar
rrt committed
1160
1161
</ProgramListing>

1162
1163
1164
      <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
1165
      cool&lowbar;pgm</Command>.  <Command>ghc -M</Command> will append
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
      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>

1176
       then <command>ghc -M</command> will generate a dependency
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
       line of the form:

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

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

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

1189
       then <command>ghc -M</command> will generate a dependency
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
       line of the form:

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

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

1201
      <para>By default, <Command>ghc -M</Command> generates all the
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
      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>

      <para>Internally, GHC uses a script to generate the
      dependencies, called <command>mkdependHS</command>.  This script
      has some options of its own, which you might find useful.
      Options can be passed directly to <command>mkdependHS</command>
      with GHC's <literal>-optdep</literal> option.  For example, to
      generate the dependencies into a file called
      <literal>.depend</literal> instead of
      <literal>Makefile</literal>:</para>

<screen>
ghc -M -optdep-f optdep.depend ...
</screen>
      
      <para>The full list of options accepted by
      <command>mkdependHS</command> is:</para>

      <variablelist>

	<varlistentry>
	  <term><option>-w</option></term>
	  <listitem>
	    <para>Turn off warnings about interface file shadowing.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-f blah</option></term>
	  <listitem>
	    <para>Use <Filename>blah</Filename> as the makefile,
            rather than <Filename>makefile</Filename> or
            <Filename>Makefile</Filename>.  If
            <Filename>blah</Filename> 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>
	  <term><option>--exclude-module=&lt;file&gt;</option></term>
	  <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>
	    <para>same as <option>--exclude-module</option></para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--exclude-directory=&lt;dirs&gt;</option></term>
	  <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>
	  <term><option>-xdirs</option></term>
	  <listitem>
	    <para>same as <Option>--exclude-directory</Option>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--include-module=&lt;file&gt;</option></term>
	  <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 the
            <Option>--exclude-directory</Option> option.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--include-prelude</option></term>
	  <listitem>
	    <para>Regard prelude libraries as unstable, i.e., generate
            dependencies on the prelude modules used (including
            <Literal>Prelude</Literal>).  This option is normally only
            used by the various system libraries. If a
1334
            <Option>-package</Option> option is used, dependencies will
1335
1336
1337
1338
            also be generated on the library's interfaces.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
rrt's avatar
rrt committed
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385

</Sect2>

<Sect2 id="mutual-recursion">
<Title>How to compile mutually recursive modules
</Title>

<Para>
<IndexTerm><Primary>module system, recursion</Primary></IndexTerm>
<IndexTerm><Primary>recursion, between modules</Primary></IndexTerm>
</Para>

<Para>
Currently, the compiler does not have proper support for dealing with
mutually recursive modules:
</Para>

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

<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
rrt's avatar
rrt committed
1386
1387
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:
rrt's avatar
rrt committed
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
<IndexTerm><Primary>hi-boot files</Primary></IndexTerm>
<IndexTerm><Primary>importing, hi-boot files</Primary></IndexTerm>
</Para>

<Para>

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

</Para>

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

<Para>

<ProgramListing>
__interface A 1 404 where
__export A TA{MkTA} ;
1 newtype TA = MkTA PrelBase.Int ;
</ProgramListing>

</Para>

<Para>
rrt's avatar
rrt committed
1424
1425
1426
The syntax is essentially the same as a normal <Filename>.hi</Filename> file
(unfortunately), but you can usually tailor an existing <Filename>.hi</Filename> file to
make a <Filename>.hi-boot</Filename> file.
rrt's avatar
rrt committed
1427
1428
1429
1430
</Para>

<Para>
Notice that we only put the declaration for the newtype <Literal>TA</Literal> in the
rrt's avatar
rrt committed
1431
<Literal>hi-boot</Literal> file, not the signature for <Function>f</Function>, since <Function>f</Function> isn't used by
rrt's avatar
rrt committed
1432
1433
1434
1435
<Literal>B</Literal>.
</Para>

<Para>
rrt's avatar
rrt committed
1436
1437
The number &ldquo;1&rdquo; after &ldquo;&lowbar;&lowbar;interface A&rdquo; gives the version number of module A;
it is incremented whenever anything in A's interface file changes.  The &ldquo;404&rdquo; is
rrt's avatar
rrt committed
1438
1439
1440
1441
1442
1443
the version number of the interface file <Emphasis>syntax</Emphasis>; we change it when
we change the syntax of interface files so that you get a better error message when
you try to read an old-format file with a new-format compiler.
</Para>

<Para>
rrt's avatar
rrt committed
1444
The number &ldquo;1&rdquo; at the beginning of a declaration is the <Emphasis>version
rrt's avatar
rrt committed
1445
number</Emphasis> of that declaration: for the purposes of <Filename>.hi-boot</Filename> files
rrt's avatar
rrt committed
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
these can all be set to 1.  All names must be fully qualified with the
<Emphasis>original</Emphasis> module that an object comes from: for example, the
reference to <Literal>Int</Literal> in the interface for <Literal>A</Literal> comes from <Literal>PrelBase</Literal>,
which is a module internal to GHC's prelude.  It's a pain, but that's
the way it is.
</Para>

<Para>
If you want an hi-boot 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>

<Para>

<ProgramListing>
__interface A 1 404 where
__export A TA;
1 data TA
</ProgramListing>

</Para>

<Para>
(You must write all the type parameters, but leave out the '=' and everything that follows it.)
</Para>

<Para>
<Emphasis>Note:</Emphasis> This is all a temporary solution, a version of the
compiler that handles mutually recursive modules properly without the manual
construction of interface files, is (allegedly) in the works.
</Para>

</Sect2>

</Sect1>

1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
  <sect1 id="packages">
    <title>Packages</title>
    <indexterm><primary>packages</primary></indexterm>

    <para>Packages are collections of libraries, conveniently grouped
    together as a single entity.  The package system is flexible: a
    package may consist of Haskell code, foreign language code (eg. C
    libraries), or a mixture of the two.  A package is a good way to
    group together related Haskell modules, and is essential if you
    intend to make the modules into a Windows DLL (see below).</para>

    <para>Because packages can contain both Haskell and C libraries, they
    are also a good way to provide convenient access to a Haskell
    layer over a C library.</para>

    <para>GHC comes with several packages (see <xref
    linkend="book-hslibs">), and packages can be added/removed from an
    existing GHC installation.</para>

    <sect2 id="listing-packages">
      <title>Listing the available packages</title>
      <indexterm><primary>packages</primary>
	<secondary>listing</secondary></indexterm>

      <para>To see what packages are currently installed, use the
      <literal>--list-packages</literal> option:</para>
      <indexterm><primary><literal>--list-packages</literal></primary>
      </indexterm>

<screen>
  $ ghc --list-packages
  gmp, rts, std, lang, concurrent, data, net, posix, text, util
</screen>

      <para>Note that your GHC installation might have a slightly
      different set of packages installed.</para>

      <para>The <literal>gmp</literal> and <literal>rts</literal>
      packages are always present, and represent the multi-precision
      integer and runtime system libraries respectively.  The
      <literal>std</literal> package contains the Haskell prelude.
      The rest of the packages are optional libraries.</para>

    </sect2>

    <sect2 id="using-packages">
      <title>Using a package</title>
      <indexterm><primary>packages</primary>
	<secondary>using</secondary></indexterm>
      
      <para>To use a package, add the <literal>-package</literal> flag
      to the command line:</para>

      <variablelist>
	<varlistentry>
	  <term><option>-package &lt;lib&gt;</option></term>
	  <indexterm><primary>-package &lt;lib&gt; option</primary></indexterm>
	  <listitem>
	    <para>This option brings into scope all the modules from
	    package <literal>&lt;lib&gt;</literal> (they still have to
	    be imported in your Haskell source, however).  It also
	    causes the relevant libraries to be linked when linking is
	    being done.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Some packages depend on other packages, for example the
      <literal>text</literal> package makes use of some of the modules
      in the <literal>lang</literal> package.  The package system
      takes care of all these dependencies, so that when you say
      <literal>-package text</literal> on the command line, you
      automatically get <literal>-package lang</literal> too.</para>
    </sect2>

    <sect2 id="building-packages">
      <title>Building a package from Haskell source</title>
      <indexterm><primary>packages</primary>
	<secondary>building</secondary></indexterm>

      <para>It takes some special considerations to build a new
      package:</para>

      <itemizedlist>
	<listitem>
	  <para>A package may contain several Haskell modules. A
          package may span many directories, or many packages may
          exist in a single directory. Packages may not be mutually
          recursive.</para>
	</listitem>

	<listitem>
	  <para>A package has a name
  	  (e.g. <filename>std</filename>)</para>
	</listitem>

	<listitem>
	  <para>The Haskell code in a package may be built into one or
	  more Unix libraries (e.g. <Filename>libHSfoo.a</Filename>),
	  or a single DLL on Windows
	  (e.g. <Filename>HSfoo.dll</Filename>).  The restriction to a
	  single DLL on Windows is that the package system is used to
	  tell the compiler when it should make an inter-DLL call
	  rather than an intra-DLL call (inter-DLL calls require an
	  extra indirection).</para>
	</listitem>

	<listitem>
	  <para>GHC does not maintain detailed cross-package
          dependency information.  It does remember which modules in
          other packages the current module depends on, but not which
          things within those imported things.</para>
	</listitem>
      </itemizedlist>

      <para>To compile a module which is to be part of a new package,
      use the <literal>-package-name</literal> option:</para>

      <variablelist>
	<varlistentry>
	  <term><option>-package-name &lt;foo&gt;</option></term>
	  <indexterm><primary><literal>-package-name</literal></primary>
	    <secondary>option</secondary></indexterm>
	  <listitem>
	    <para>This option is added to the command line when
	    compiling a module that is destined to be part of package
	    <literal>foo</literal>.  If this flag is omitted then the
	    default package <literal>Main</literal> is assumed.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Failure to use the <literal>-package-name</literal> option
      when compiling a package will result in disaster on Windows, but
      is relatively harmless on Unix at the moment (it will just cause
      a few extra dependencies in some interface files).  However,
      bear in mind that we might add support for Unix shared libraries
      at some point in the future.</para>

      <para>It is worth noting that on Windows, because each package
      is built as a DLL, and a reference to a DLL costs an extra
      indirection, intra-package references are cheaper than
      inter-package references. Of course, this applies to the
      <Filename>Main</Filename> package as well.</para>

    </sect2>
    <sect2 id="package-management">
      <title>Package management</title>
      <indexterm><primary>packages</primary>
	<secondary>management</secondary></indexterm>
      
      <para>GHC uses a package configuration file, called
      <literal>packages.conf</literal>, which can be found in your GHC
      install directory.  This file isn't intended to be edited
      directly, instead GHC provides options for adding & removing
      packages:</para>

      <variablelist>
	<varlistentry>
	  <term><option>--add-package</option></term>
	  <indexterm><primary><literal>--add-package</literal></primary>
	      <secondary>option</secondary></indexterm>
	  <listitem>
	    <para>Reads a package specification (see below) on stdin,
	    and adds it to the database of installed packages.  The
	    package specification must be a package that isn't already
	    installed.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--delete-package &lt;foo&gt;</option></term>
	  <indexterm><primary><literal>--delete-package</literal></primary>
	      <secondary>option</secondary></indexterm>
	  <listitem>
	    <para>Removes the specified package from the installed
	    configuration.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>In both cases, the old package configuration file is saved
      in <literal>packages.conf.old</literal> in your GHC install
      directory, so in an emergency you can always copy this file into
      <literal>package.conf</literal> to restore the old
      settings.</para>

      <para>A package specification looks like this:</para>

<screen>
 ("mypkg",
  "4.08",
  Package
       {
        import_dirs    =  ["/usr/local/lib/imports/mypkg"],
	library_dirs   =  ["/usr/local/lib"],
	libraries      =  ["HSmypkg", "HSmypkg_cbits"],
1679
1680
	include_dirs   =  [],
	c_includes     =  ["HsMyPkg.h"],
1681
	package_deps   =  ["text", "data"],
1682
1683
1684
	extra_ghc_opts =  [],
	extra_cc_opts  =  [],
	extra_ld_opts  =  ["-lmy_clib"]
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
       }
 )
</screen>

      <para>The first line is the name of the package, for use with
      the <literal>-package</literal> flag and as listed in the
      <literal>--list-packages</literal> list.  The second line is the
      version of GHC that was used to compile any Haskell code in this
      package (GHC will refuse to add the package if its version
      number differs from this one).  The rest of the components of
1695
      the package specification may be specified in any order, and
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
      are:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>import_dirs</literal></term>
	  <indexterm><primary><literal>import_dirs</literal></primary>
	    <secondary>package specification</secondary></indexterm>
	  <listitem>
	    <para>A list of directories containing interface files
	    (<literal>.hi</literal> files) for this package.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>library_dirs</literal></term>
	  <indexterm><primary><literal>library_dirs</literal></primary>
	    <secondary>package specification</secondary></indexterm>
	  <listitem>
	    <para>A list of directories containing libraries for this
	    package.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>libraries</literal></term>
	  <indexterm><primary><literal>libraries</literal></primary>
	    <secondary>package specification</secondary></indexterm>
	  <listitem>
	    <para>A list of libraries for this package, with the
	    <literal>.a</literal> or <literal>.dll</literal> suffix
	    omitted.  On Unix, the <literal>lib</literal> prefix is
	    also omitted.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
1732
1733
	  <term><literal>include_dirs</literal></term>
	  <indexterm><primary><literal>include_dirs</literal></primary>
1734
1735
	    <secondary>package specification</secondary></indexterm>
	  <listitem>
1736
1737
	    <para>A list of directories containing C includes for this
	    package (maybe the empty list).</para>
1738
1739
1740
1741
	  </listitem>
	</varlistentry>

	<varlistentry>
1742
1743
	  <term><literal>c_includes</literal></term>
	  <indexterm><primary><literal>c_includes</literal></primary>
1744
1745
	    <secondary>package specification</secondary></indexterm>
	  <listitem>
1746
1747
1748
1749
1750
1751
	    <para>A list of files to include for via-C compilations
	    using this package.  Typically this include file will
	    contain function prototypes for any C functions used in
	    the package, in case they end up being called as a result
	    of Haskell functions from the package being
	    inlined.</para>
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797