using.sgml 68.3 KB
Newer Older
1
<chapter id="using-ghc">
2
  <title>Using GHC</title>
rrt's avatar
rrt committed
3

4
5
  <indexterm><primary>GHC, using</primary></indexterm>
  <indexterm><primary>using GHC</primary></indexterm>
rrt's avatar
rrt committed
6

7
  <para>GHC can work in one of three &ldquo;modes&rdquo;:</para>
rrt's avatar
rrt committed
8

9
10
11
  <variablelist>
    <varlistentry>
      <term><cmdsynopsis><command>ghc</command>
12
	  <arg choice=plain>&ndash;&ndash;interactive</arg>
13
14
15
16
17
18
19
20
21
22
23
	</cmdsynopsis></term>
      <indexterm><primary>interactive mode</primary>
      </indexterm>
      <indexterm><primary>ghci</primary>
      </indexterm>
      <listitem>
	<para>Interactive mode, which is also available as
	<command>ghci</command>.  Interactive mode is described in
	more detail in <xref linkend="ghci">.</para>
      </listitem>
    </varlistentry>
rrt's avatar
rrt committed
24

25
26
    <varlistentry>
      <term><cmdsynopsis><command>ghc</command>
27
	  <arg choice=plain>&ndash;&ndash;make</arg>
28
29
30
	</cmdsynopsis></term>
      <indexterm><primary>make mode</primary>
      </indexterm>
31
      <indexterm><primary><option>&ndash;&ndash;make</option></primary>
32
33
34
35
36
37
38
39
40
      </indexterm>
      <listitem>
	<para>In this mode, GHC will build a multi-module Haskell
	program automatically, figuring out dependencies for itself.
	If you have a straightforward Haskell program, this is likely
	to be much easier, and faster, than using
	<command>make</command>.</para>
      </listitem>
    </varlistentry>
rrt's avatar
rrt committed
41

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
    <varlistentry>
      <term><cmdsynopsis>
	  <command>ghc</command>
	  <group>
	    <arg>-E</arg>
	    <arg>-C</arg>
	    <arg>-S</arg>
	    <arg>-c</arg>
	  </group>
	</cmdsynopsis></term>
      <indexterm><primary><option>-E</option></primary></indexterm>
      <indexterm><primary><option>-C</option></primary></indexterm>
      <indexterm><primary><option>-S</option></primary></indexterm>
      <indexterm><primary><option>-c</option></primary></indexterm>
      <listitem>
	<para>This is the traditional batch-compiler mode, in which
58
59
	  GHC can compile source files one at a time, or link objects
	  together into an executable.</para>
60
61
62
63
      </listitem>
    </varlistentry>
  </variablelist>
  
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
  <sect1>
    <title>Options overview</title>
    
    <para>GHC's behaviour is controlled by
    <firstterm>options</firstterm>, which for historical reasons are
    also sometimes referred to as command-line flags or arguments.
    Options can be specified in three ways:</para>

    <sect2>
      <title>Command-line arguments</title>
      
      <indexterm><primary>structure, command-line</primary></indexterm>
      <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
      <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
      
      <para>An invocation of GHC takes the following form:</para>
rrt's avatar
rrt committed
80
81
82
83
84

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

85
86
87
88
89
90
91
92
93
94
95
96
      <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 grouped:
      <option>-vO</option> is different from <option>-v -O</option>.
      Options need not precede filenames: e.g., <literal>ghc *.o -o
      foo</literal>.  All options are processed and then applied to
      all files; you cannot, for example, invoke <literal>ghc -c -O1
      Foo.hs -O2 Bar.hs</literal> to apply different optimisation
      levels to the files <filename>Foo.hs</filename> and
      <filename>Bar.hs</filename>.</para>
    </sect2>
rrt's avatar
rrt committed
97

98
99
100
101
102
103
104
105
106
107
108
109
110
111
    <Sect2 id="source-file-options">
      <title>Command line options in source files</title>
    
      <indexterm><primary>source-file options</primary></indexterm>

      <para>Sometimes it is useful to make the connection between a
      source file and the command-line options it requires quite
      tight. For instance, if a Haskell source file uses GHC
      extensions, it will always need to be compiled with the
      <option>-fglasgow-exts</option> option.  Rather than maintaining
      the list of per-file options in a <filename>Makefile</filename>,
      it is possible to do this directly in the source file using the
      <literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS
      pragma</primary></indexterm>:</para>
rrt's avatar
rrt committed
112

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<ProgramListing>
{-# OPTIONS -fglasgow-exts #-}
module X where
...
</ProgramListing>
      
      <para><literal>OPTIONS</literal> pragmas are only looked for at
      the top of your source files, upto the first
      (non-literate,non-empty) line not containing
      <literal>OPTIONS</literal>. Multiple <literal>OPTIONS</literal>
      pragmas are recognised. Note that your command shell does not
      get to the source file options, they are just included literally
      in the array of command-line arguments the compiler driver
      maintains internally, so you'll be desperately disappointed if
      you try to glob etc. inside <literal>OPTIONS</literal>.</para>

      <para>NOTE: the contents of OPTIONS are prepended to the
      command-line options, so you <emphasis>do</emphasis> have the
      ability to override OPTIONS settings via the command
      line.</para>

      <para>It is not recommended to move all the contents of your
      Makefiles into your source files, but in some circumstances, the
      <literal>OPTIONS</literal> pragma is the Right Thing. (If you
      use <option>-keep-hc-file-too</option> and have OPTION flags in
      your module, the OPTIONS will get put into the generated .hc
      file).</para>
    </sect2>
rrt's avatar
rrt committed
141

142
143
    <sect2>
      <title>Setting options in GHCi</title>
rrt's avatar
rrt committed
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
      <para>Options may also be modified from within GHCi, using the
      <literal>:set</literal> command.  See <xref linkend="ghci-set">
      for more details.</para>
    </sect2>
  </sect1>
    
  <sect1 id="static-dynamic-flags">
    <title>Static vs. Dynamic options</title>
    <indexterm><primary>static</primary><secondary>options</secondary>
    </indexterm>
    <indexterm><primary>dynamic</primary><secondary>options</secondary>
    </indexterm>

    <para>Each of GHC's command line options is classified as either
    <firstterm>static</firstterm> or <firstterm>dynamic</firstterm>.
    A static flag may only be specified on the command line, whereas a
    dynamic flag may also be given in an <literal>OPTIONS</literal>
    pragma in a source file or set from the GHCi command-line with
    <literal>:set</literal>.</para>

    <para>As a rule of thumb, all the language options are dynamic, as
    are the warning options and the debugging options.  The rest are
    static, with the notable exceptions of <option>-v</option>,
    <option>-cpp</option>, <option>-fasm</option>,
    <option>-fvia-C</option>, and <option>-#include</option>.

    The flag reference tables (<xref linkend="flag-reference">) lists
    the status of each flag.</para>
  </sect1>
rrt's avatar
rrt committed
174

175
176
  <sect1 id="file-suffixes">
    <title>Meaningful file suffixes</title>
rrt's avatar
rrt committed
177

178
179
    <indexterm><primary>suffixes, file</primary></indexterm>
    <indexterm><primary>file suffixes for GHC</primary></indexterm>
rrt's avatar
rrt committed
180

181
182
183
    <para>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.</para>
rrt's avatar
rrt committed
184

185
    <variablelist>
rrt's avatar
rrt committed
186

187
188
189
190
191
192
193
      <varlistentry>
	<term><filename>.lhs</filename></term>
	<indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	<listitem>
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
194

195
196
197
198
199
200
201
202
203
204
205
206
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
      <varlistentry>
	<term><filename>.hs</filename></term>
	<listitem>
	  <para>A not-so-literate Haskell module.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>.hi</filename></term>
	<listitem>
	  <para>A Haskell interface file, probably
	  compiler-generated.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>.hc</filename></term>
	<listitem>
	  <para>Intermediate C file produced by the Haskell
	  compiler.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>.c</filename></term>
	<listitem>
	  <para>A C&nbsp;file not produced by the Haskell
	  compiler.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><filename>.s</filename></term>
	<listitem>
	  <para>An assembly-language source file, usually produced by
          the compiler.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>.o</filename></term>
	<listitem>
	  <para>An object file, produced by an assembler.</para>
	</listitem>
      </varlistentry>
    </variablelist>

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

  </sect1>
rrt's avatar
rrt committed
246

247
248
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
249

250
251
    <IndexTerm><Primary>help options</Primary></IndexTerm>
    <IndexTerm><Primary>verbosity options</Primary></IndexTerm>
252
253
254

    <variablelist>
      <varlistentry>
255
	<term><option>&ndash;&ndash;help</option></term>
256
257
	<term><option>-?</option></term>
	<indexterm><primary><option>-?</option></primary></indexterm>
258
	<indexterm><primary><option>&ndash;&ndash;help</option></primary></indexterm>
259
260
261
262
263
	<listitem>
	  <para>Cause GHC to spew a long usage message to standard
          output and then exit.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
264

265
      <varlistentry>
266
267
	<term><option>-v</option></term>
	<indexterm><primary><option>-v</option></primary></indexterm>
268
269
	<listitem>
	  <para>The <option>-v</option> option makes GHC
270
          <emphasis>verbose</emphasis>: it reports its version number
271
272
273
274
275
276
277
278
279
280
281
282
283
          and shows (on stderr) exactly how it invokes each phase of
          the compilation system.  Moreover, it passes the
          <option>-v</option> flag to most phases; each reports its
          version number (and possibly some other information).</para>

	  <para>Please, oh please, use the <option>-v</option> option
          when reporting bugs!  Knowing that you ran the right bits in
          the right order is always the first thing we want to
          verify.</para>
	</listitem>
      </varlistentry>
	
      <varlistentry>
284
	<term><option>-v</option><replaceable>n</replaceable></term>
285
	<indexterm><primary><option>-v</option></primary></indexterm>
286
287
288
289
290
291
292
293
294
	<listitem>
	  <para>To provide more control over the compiler's verbosity,
	  the <option>-v</option> flag takes an optional numeric
	  argument.  Specifying <option>-v</option> on its own is
	  equivalent to <option>-v3</option>, and the other levels
	  have the following meanings:</para>
	  
	  <variablelist>
	    <varlistentry>
295
	      <term><option>-v0</option></term>
296
297
298
299
300
301
302
	      <listitem>
		<para>Disable all non-essential messages (this is the
		default).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
303
	      <term><option>-v1</option></term>
304
305
306
	      <listitem>
		<para>Minimal verbosity: print one line per
		compilation (this is the default when
307
308
		<option>&ndash;&ndash;make</option> or
		<option>&ndash;&ndash;interactive</option> is on).</para>
309
310
311
312
	      </listitem>
	    </varlistentry>

	    <varlistentry>
313
	      <term><option>-v2</option></term>
314
315
316
317
318
319
320
321
	      <listitem>
		<para>Print the name of each compilation phase as it
		is executed. (equivalent to
		<option>-dshow-passes</option>).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
322
	      <term><option>-v3</option></term>
323
324
325
326
327
328
329
330
	      <listitem>
		<para>The same as <option>-v2</option>, except that in
                addition the full command line (if appropriate) for
                each compilation phase is also printed.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
331
	      <term><option>-v4</option></term>
332
333
334
335
336
337
338
339
340
341
342
343
	      <listitem>
		<para>The same as <option>-v3</option> except that the
		intermediate program representation after each
		compilation phase is also printed (excluding
		preprocessed and C/assembly files).</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>
      
      <varlistentry>
344
345
	<term><option>&ndash;&ndash;version</option></term>
	<indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
346
347
348
349
	<listitem>
	  <para>Print a one-line string including GHC's version number.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
350

351
      <varlistentry>
352
353
	<term><option>&ndash;&ndash;numeric-version</option></term>
	<indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
354
355
356
357
	<listitem>
	  <para>Print GHC's numeric version number only.</para>
	</listitem>
      </varlistentry>
358
359

      <varlistentry>
360
361
	<term><option>&ndash;&ndash;print-libdir</option></term>
	<indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
362
363
364
365
	<listitem>
	  <para>Print the path to GHC's library directory.  This is
	  the top of the directory tree containing GHC's libraries,
	  interfaces, and include files (usually something like
366
	  <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
367
368
369
370
371
372
373
	  is the value of
	  <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
	  </indexterm>in the package configuration file (see <xref
	  linkend="packages">).</para>
	</listitem>
      </varlistentry>

374
375
376
    </variablelist>
  </sect1>

377
  <sect1 id="make-mode">
378
    <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
379

380
    <indexterm><primary><option>&ndash;&ndash;make</option></primary>
381
382
383
384
    </indexterm>
    <indexterm><primary>separate compilation</primary>
    </indexterm>
    
385
    <para>When given the <option>&ndash;&ndash;make</option> option, GHC will
386
387
388
389
390
391
392
    build a multi-module Haskell program by following dependencies
    from a single root module (usually <literal>Main</literal>).  For
    example, if your <literal>Main</literal> module is in a file
    called <filename>Main.hs</filename>, you could compile and link
    the program like this:</para>

<screen>
393
ghc &ndash;&ndash;make Main.hs
394
395
396
397
398
399
400
401
402
</screen>

    <para>The command line must contain one source file or module
    name; GHC will figure out all the modules in the program by
    following the imports from this initial module.  It will then
    attempt to compile each module which is out of date, and finally
    if the top module is <literal>Main</literal>, the program
    will also be linked into an executable.</para>

403
    <para>The main advantages to using <literal>ghc &ndash;&ndash;make</literal>
404
405
406
407
408
409
410
    over traditional <literal>Makefile</literal>s are:</para>

    <itemizedlist>
      <listitem>
	<para>GHC doesn't have to be restarted for each compilation,
	which means it can cache information between compilations.
	Compiling a muli-module program with <literal>ghc
411
	&ndash;&ndash;make</literal> can be up to twice as fast as running
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
	<literal>ghc</literal> individually on each source
	file.</para>
      </listitem>
      <listitem>
	<para>You don't have to write a
	<literal>Makefile</literal>.</para>
      </listitem>
      <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
      </indexterm>
      <listitem>
	<para>GHC re-calculates the dependencies each time it is
	invoked, so the dependencies never get out of sync with the
	source.</para>
      </listitem>
    </itemizedlist>

    <para>Any of the command-line options described in the rest of
429
    this chapter can be used with <option>&ndash;&ndash;make</option>, but note
430
431
432
433
434
435
436
437
438
    that any options you give on the command line will apply to all
    the source files compiled, so if you want any options to apply to
    a single source file only, you'll need to use an
    <literal>OPTIONS</literal> pragma (see <xref
    linkend="source-file-options">).</para>

    <para>If the program needs to be linked with additional objects
    (say, some auxilliary C code), these can be specified on the
    command line as usual.</para>
439
440
441
442
443
444
445

    <para>Note that GHC can only follow dependencies if it has the
    source file available, so if your program includes a module for
    which there is no source file, even if you have an object and an
    interface file for the module, then GHC will complain.  The
    exception to this rule is for package modules, which may or may
    not have source files.</para>
446
447
448
449
450
451

    <para>The source files for the program don't all need to be in the
    same directory; the <option>-i</option> option can be used to add
    directories to the search path (see <xref
    linkend="options-finding-imports">).</para>

452
453
454
  </sect1>
  
  <Sect1 id="options-order">
455
    <title>GHC without <option>&ndash;&ndash;make</option></title>
456

457
    <para>Without <option>&ndash;&ndash;make</option>, GHC will compile one or
458
    more source files given on the command line.</para>
459

460
    <para>The first phase to run is determined by each input-file
461
462
463
    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>
rrt's avatar
rrt committed
464

465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
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
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
    <informaltable>
      <tgroup cols="4">
	<colspec align="left">
	<colspec align="left">
	<colspec align="left">
	<colspec align="left">

	<thead>
	  <row>
	    <entry>Phase of the compilation system</entry>
	    <entry>Suffix saying &ldquo;start here&rdquo;</entry>
	    <entry>Flag saying &ldquo;stop after&rdquo;</entry>
	    <entry>(suffix of) output file</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>literate pre-processor</entry>
	    <entry><literal>.lhs</literal></entry>
	    <entry>-</entry>
	    <entry><literal>.hs</literal></entry>
	  </row>

	  <row>
	    <entry>C pre-processor (opt.)
           </entry> 
	    <entry><literal>.hs</literal> (with
	    <option>-cpp</option>)</entry>
	    <entry><option>-E</option></entry>
	    <entry><literal>.hspp</literal></entry>
	  </row>
	  
	  <row>
	    <entry>Haskell compiler</entry>
	    <entry><literal>.hs</literal></entry>
	    <entry><option>-C</option>, <option>-S</option></entry>
	    <entry><literal>.hc</literal>, <literal>.s</literal></entry>
	  </row>

	  <row>
	    <entry>C compiler (opt.)</entry>
	    <entry><literal>.hc</literal> or <literal>.c</literal></entry>
	    <entry><option>-S</option></entry>
	    <entry><literal>.s</literal></entry>
	  </row>

	  <row>
	    <entry>assembler</entry>
	    <entry><literal>.s</literal></entry>
	    <entry><option>-c</option></entry>
	    <entry><literal>.o</literal></entry>
	  </row>
	  
	  <row>
	    <entry>linker</entry>
	    <entry><replaceable>other</replaceable></entry>
	    <entry>-</entry>
	    <entry><filename>a.out</filename></entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <indexterm><primary><option>-C</option></primary></indexterm>
    <indexterm><primary><option>-E</option></primary></indexterm>
    <indexterm><primary><option>-S</option></primary></indexterm>
    <indexterm><primary><option>-c</option></primary></indexterm>

    <para>Thus, a common invocation would be: <literal>ghc -c
    Foo.hs</literal></para>

    <para>Note: What the Haskell compiler proper produces depends on
    whether a native-code generator<indexterm><primary>native-code
    generator</primary></indexterm> is used (producing assembly
    language) or not (producing C).  See <xref
    linkend="options-codegen"> for more details.</para>

    <para>Note: C pre-processing is optional, the
    <option>-ccp</option><indexterm><primary><option>-cpp</option></primary>
      </indexterm>flag turns it on.  See <xref
    linkend="c-pre-processor"> for more details.</para>

    <para>Note: The option <option>-E</option><IndexTerm><Primary>-E
548
549
    option</Primary></IndexTerm> runs just the pre-processing passes
    of the compiler, dumping the result in a file.  Note that this
550
551
    differs from the previous behaviour of dumping the file to
    standard output.</para>
552
  </sect1>
rrt's avatar
rrt committed
553

554
555
556
557
558
559
560
561
562
  <sect1 id="options-output">
    <title>Re-directing the compilation output(s)</title>

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


    <variablelist>
      <varlistentry>
563
564
	<term><option>-o</option></term>
	<indexterm><primary><option>-o</option></primary></indexterm>
565
566
	<listitem>
	  <para>GHC's compiled output normally goes into a
567
          <filename>.hc</filename>, <filename>.o</filename>, etc.,
568
569
570
          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
571
          last-run phase to file <filename>foo</filename>.</para>
572
573

	  <para>Note: this &ldquo;feature&rdquo; can be
574
          counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
575
          will put the intermediate C code in the file
576
          <filename>foo.o</filename>, name notwithstanding!</para>
577
578
579
580
581
582
583
584
585
586

	  <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>
587
588
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
589

590
      <varlistentry>
591
592
	<term><option>-odir</option></term>
	<indexterm><primary><option>-odir</option></primary></indexterm>
593
594
	<listitem>
	  <para>The <option>-o</option> option isn't of much use if
595
          you have <emphasis>several</emphasis> input files&hellip;
596
597
598
599
600
601
          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 using the
          <option>-odir &lt;dir&gt;</option><IndexTerm><Primary>-odir
          &lt;dir&gt; option</Primary></IndexTerm> (the &ldquo;Oh,
          dear&rdquo; option).  For example:</para>
rrt's avatar
rrt committed
602
603
604
605
606

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

607
608
609
          <para>The output files, <filename>Foo.o</filename>,
          <filename>Bar.o</filename>, and
          <filename>Bumble.o</filename> would be put into a
610
          subdirectory named after the architecture of the executing
611
612
          machine (<filename>sun4</filename>,
          <filename>mips</filename>, etc).  The directory must already
613
614
615
          exist; it won't be created.</para>

          <para>Note that the <option>-odir</option> option does
616
          <emphasis>not</emphasis> affect where the interface files
617
          are put.  In the above example, they would still be put in
618
619
620
          <filename>parse/Foo.hi</filename>,
          <filename>parse/Bar.hi</filename>, and
          <filename>gurgle/Bumble.hi</filename>.</para>
621
622
623
	</listitem>
      </varlistentry>

624
625
626
627
628
629
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
      <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>directory</replaceable></term>
	<indexterm><primary><option>-hidir</option></primary>
	</indexterm>
	<listitem>
	  <para>Redirects all generated interface files into
	  <replaceable>directory</replaceable>, instead of the default
	  which is to place the interface file in the same directory
	  as the source file.</para>
	</listitem>
      </varlistentry>

659
      <varlistentry>
660
661
662
663
664
665
	<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>
666
	<listitem>
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
	  <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>
683
684
685
686

	  <para>The <option>-hisuf</option>/<option>-osuf</option>
          game is useful if you want to compile a program with both
          GHC and HBC (say) in the same directory.  Let HBC use the
687
          standard <filename>.hi</filename>/<filename>.o</filename>
688
          suffixes; add <option>-hisuf g&lowbar;hi -osuf
689
          g&lowbar;o</option> to your <command>make</command> rule for
690
691
692
693
694
          GHC compiling&hellip;</para>
	</listitem>
      </varlistentry>
    </variablelist>
	
695
696
697
698
699
700
701
702
703
    <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>

704

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

      <variablelist>
	<varlistentry>
711
	  <term><option>-keep-hc-files</option></term>
712
	  <indexterm>
713
	    <primary><option>-keep-hc-files</option></primary>
714
715
716
717
718
719
	  </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
720
	    may need to use <option>-fvia-C</option> to force them
721
722
723
724
725
	    to be produced).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
726
	  <term><option>-keep-s-files</option></term>
727
	  <indexterm>
728
	    <primary><option>-keep-s-files</option></primary>
729
730
731
732
733
734
735
	  </indexterm>
	  <listitem>
	    <para>Keep intermediate <literal>.s</literal> files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
736
	  <term><option>-keep-raw-s-files</option></term>
737
	  <indexterm>
738
	    <primary><option>-keep-raw-s-files</option></primary>
739
740
741
742
743
744
745
746
747
748
749
	  </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>
750
	  <term><option>-keep-tmp-files</option></term>
751
	  <indexterm>
752
	    <primary><option>-keep-tmp-files</option></primary>
753
754
	  </indexterm>
	  <indexterm>
755
	    <primary>temporary files</primary>
756
757
758
759
760
761
762
	    <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
763
	    <option>-v</option> will show you what temporary files
764
765
766
767
768
	    were generated along the way.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
rrt's avatar
rrt committed
769

770
771
    <sect2 id="temp-files">
      <title>Redirecting temporary files</title>
rrt's avatar
rrt committed
772

773
774
775
776
      <indexterm>
	<primary>temporary files</primary>
	<secondary>redirecting</secondary>
      </indexterm>
rrt's avatar
rrt committed
777

778
779
      <variablelist>
	<varlistentry>
780
781
	  <term><option>-tmpdir</option></term>
	  <indexterm><primary><option>-tmpdir</option></primary></indexterm>
782
783
	  <listitem>
	    <para>If you have trouble because of running out of space
784
            in <filename>/tmp</filename> (or wherever your
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
            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>
    </sect2>
rrt's avatar
rrt committed
809

810
  </sect1>
rrt's avatar
rrt committed
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
  <sect1 id="options-sanity">
    <title>Warnings and sanity-checking</title>

    <indexterm><primary>sanity-checking options</primary></indexterm>
    <indexterm><primary>warnings</primary></indexterm>


    <para>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:
    <option>-fwarn-overlpapping-patterns</option>,
    <option>-fwarn-deprecations</option>,
    <option>-fwarn-duplicate-exports</option>,
    <option>-fwarn-missing-fields</option>, and
    <option>-fwarn-missing-methods</option>.  The following flags are
    simple ways to select standard &ldquo;packages&rdquo; of warnings:
    </para>

    <VariableList>

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
	  <IndexTerm><Primary>-W option</Primary></IndexTerm>
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
	  <option>-fwarn-unused-matches</option>,
841
842
	  <option>-fwarn-unused-imports</option>,
	  <option>-fwarn-misc</option>, and
843
844
845
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
846

847
848
849
      <varlistentry>
	<term><option>-w</option>:</term>
	<listitem>
850
	  <IndexTerm><Primary><option>-w</option></Primary></IndexTerm>
851
852
853
	  <para>Turns off all warnings, including the standard ones.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
854

855
856
857
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
858
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
859
860
861
	  <para>Turns on all warning options.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
862

863
    </variablelist>
rrt's avatar
rrt committed
864

865
866
867
    <para>The full set of warning options is described below.  To turn
    off any warning, simply give the corresponding
    <option>-fno-warn-...</option> option on the command line.</para>
rrt's avatar
rrt committed
868

869
    <variablelist>
rrt's avatar
rrt committed
870

871
872
873
874
875
876
877
878
879
880
881
882
      <varlistentry>
	<term><option>-fwarn-deprecations</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-deprecations</option></primary>
	  </indexterm>
	  <indexterm><primary>deprecations</primary></indexterm>
	  <para>Causes a warning to be emitted when a deprecated
	  function or type is used.  Entities can be marked as
	  deprecated using a pragma, see <xref
	  linkend="deprecated-pragma">.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
883

884
885
886
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
887
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
888
889
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
890

891
892
893
894
895
	  <para>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>
rrt's avatar
rrt committed
896

897
898
899
900
901
902
903
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
904
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
905
906
907
908
909
910
911
912
913
914
915
916
917
	  <indexterm><primary>shadowing</primary>
	    <secondary>interface files</secondary></indexterm>

	  <para>Causes the compiler to emit a warning when a module or
	  interface file in the current directory is shadowing one
	  with the same module name in a library or other
	  directory.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-incomplete-patterns</option>:</term>
	<listitem>
918
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
	  <indexterm><primary>incomplete patterns, warning</primary></indexterm>
	  <indexterm><primary>patterns, incomplete</primary></indexterm>

	  <para>Similarly for incomplete patterns, the function
          <function>g</function> below will fail when applied to
          non-empty lists, so the compiler will emit a warning about
          this when <option>-fwarn-incomplete-patterns</option> is
          enabled.</para>

<programlisting>
g [] = 2
</programlisting>

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

939
940
941
942
943
944
945
946
947
948
949
      <varlistentry>
	<term><option>-fwarn-misc</option>:</term>
	<indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
	<listitem>
	  <para>Turns on warnings for various harmless but untidy
	  things.  This currently includes: importing a type with
	  <literal>(..)</literal> when the export is abstract, and
	  listing duplicate class assertions in a qualified type.</para>
	</listitem>
      </varlistentry>

950
951
952
      <varlistentry>
	<term><option>-fwarn-missing-fields</option>:</term>
	<listitem>
953
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
954
955
956
957
958
959
960
961
962
963
964
965
966
967
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>

	  <para>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>
	<term><option>-fwarn-missing-methods</option>:</term>
	<listitem>
968
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
969
970
971
972
973
974
975
976
977
978
979
980
981
	  <indexterm><primary>missing methods, warning</primary></indexterm>
	  <indexterm><primary>methods, missing</primary></indexterm>

	  <para>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>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
982
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
983
984
985
986
987
988
989
990
991
992
993
994
	  <indexterm><primary>type signatures, missing</primary></indexterm>

	  <para>If you would like GHC to check that every top-level
          function/value has a type signature, use the
          <option>-fwarn-missing-signatures</option> option.  This
          option is off by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-name-shadowing</option>:</term>
	<listitem>
995
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
	  <indexterm><primary>shadowing, warning</primary></indexterm>
	  
	  <para>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>will</emphasis> complain about cyclic recursive
          definitions.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-overlapping-patterns</option>:</term>
1013
	<indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
1014
1015
1016
1017
1018
1019
1020
	<indexterm><primary>overlapping patterns, warning</primary></indexterm>
	<indexterm><primary>patterns, overlapping</primary></indexterm>
	<listitem>
	  <para>By default, the compiler will warn you if a set of
          patterns are overlapping, i.e.,</para>

<programlisting>
rrt's avatar
rrt committed
1021
1022
1023
1024
f :: String -&#62; Int
f []     = 0
f (_:xs) = 1
f "2"    = 2
1025
</programlisting>
rrt's avatar
rrt committed
1026

1027
1028
1029
1030
1031
1032
	  <para>where the last pattern match in <Function>f</Function>
          won't ever be reached, as the 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>
rrt's avatar
rrt committed
1033

1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
      <varlistentry>
	<term><option>-fwarn-simple-patterns</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
	  </indexterm>
	  <para>Causes the compiler to warn about lambda-bound
	  patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
	  Normally, these aren't treated as incomplete patterns by
	  <option>-fwarn-incomplete-patterns</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1045

1046
1047
1048
      <varlistentry>
	<term><option>-fwarn-type-defaults</option>:</term>
	<listitem>
1049
	  <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
	  <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
	  <para>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 1.4 caused the
          otherwise unconstrained value <Constant>1</Constant> to be
          given 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>
rrt's avatar
rrt committed
1065

1066
1067
1068
      <varlistentry>
	<term><option>-fwarn-unused-binds</option>:</term>
	<listitem>
1069
	  <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
1070
1071
1072
1073
1074
1075
1076
	  <indexterm><primary>unused binds, warning</primary></indexterm>
	  <indexterm><primary>binds, unused</primary></indexterm>
	  <para>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>
rrt's avatar
rrt committed
1077

1078
1079
1080
      <varlistentry>
	<term><option>-fwarn-unused-imports</option>:</term>
	<listitem>
1081
	  <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
1082
1083
	  <indexterm><primary>unused imports, warning</primary></indexterm>
	  <indexterm><primary>imports, unused</primary></indexterm>
rrt's avatar
rrt committed
1084

1085
1086
1087
1088
	  <para>Report any objects that are explicitly imported but
	  never used.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1089

1090
1091
1092
      <varlistentry>
	<term><option>-fwarn-unused-matches</option>:</term>
	<listitem>
1093
	  <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
	  <indexterm><primary>unused matches, warning</primary></indexterm>
	  <indexterm><primary>matches, unused</primary></indexterm>

	  <para>Report all unused variables which arise from pattern
          matches, including patterns consisting of a single variable.
          For instance <literal>f x y = []</literal> would report
          <VarName>x</VarName> and <VarName>y</VarName> as unused.  To
          eliminate the warning, all unused variables can be replaced
          with wildcards.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1105

1106
    </VariableList>
rrt's avatar
rrt committed
1107

1108
    <para>If you're feeling really paranoid, the
1109
1110
1111
1112
1113
    <option>-dcore-lint</option>
    option<indexterm><primary><option>-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>
rrt's avatar
rrt committed
1114

1115
  </sect1>
rrt's avatar
rrt committed
1116

1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
  &separate;
  &packages;

  <sect1 id="options-optimise">
    <title>Optimisation (code improvement)</title>

    <indexterm><primary>optimisation</primary></indexterm>
    <indexterm><primary>improvement, code</primary></indexterm>

    <para>The <option>-O*</option> options specify convenient
    &ldquo;packages&rdquo; of optimisation flags; the
    <option>-f*</option> options described later on specify
    <emphasis>individual</emphasis> optimisations to be turned on/off;
    the <option>-m*</option> options specify
    <emphasis>machine-specific</emphasis> optimisations to be turned
    on/off.</para>

    <sect2 id="optimise-pkgs">
      <title><option>-O*</option>: convenient &ldquo;packages&rdquo; of optimisation flags.</title>

      <para>There are <emphasis>many</emphasis> options that affect
      the quality of code produced by GHC.  Most people only have a
      general goal, something like &ldquo;Compile quickly&rdquo; or
      &ldquo;Make my program run like greased lightning.&rdquo; The
      following &ldquo;packages&rdquo; of optimisations (or lack
      thereof) should suffice.</para>

      <para>Once you choose a <option>-O*</option>
      &ldquo;package,&rdquo; stick with it&mdash;don't chop and
      change.  Modules' interfaces <emphasis>will</emphasis> change
      with a shift to a new <option>-O*</option> option, and you may
      have to recompile a large chunk of all importing modules before
      your program can again be run safely (see <XRef
      LinkEnd="recomp">).</para>
rrt's avatar
rrt committed
1151

1152
      <variablelist>
rrt's avatar
rrt committed
1153

1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
	<varlistentry>
	  <term>No <option>-O*</option>-type option specified:</term>
	  <indexterm><primary>-O* not specified</primary></indexterm>
	  <listitem>
	    <para>This is taken to mean: &ldquo;Please compile
            quickly; I'm not over-bothered about compiled-code
            quality.&rdquo; So, for example: <command>ghc -c
            Foo.hs</command></para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1164

1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
	<varlistentry>
	  <term><option>-O0</option>:</term>
	  <indexterm><primary><option>-O0</option></primary></indexterm>
	  <listitem>
	    <para>Means &ldquo;turn off all optimisation&rdquo;,
	    reverting to the same settings as if no
	    <option>-O</option> options had been specified.  Saying
	    <option>-O0</option> can be useful if
	    eg. <command>make</command> has inserted a
	    <option>-O</option> on the command line already.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1177

1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
	<varlistentry>
	  <term><option>-O</option> or <option>-O1</option>:</term>
	  <indexterm><primary>-O option</primary></indexterm>
	  <indexterm><primary>-O1 option</primary></indexterm>
	  <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
	  <listitem>
	    <para>Means: &ldquo;Generate good-quality code without
            taking too long about it.&rdquo; Thus, for example:
            <command>ghc -c -O Main.lhs</command></para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1189

1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
	<varlistentry>
	  <term><option>-O2</option>:</term>
	  <indexterm><primary>-O2 option</primary></indexterm>
	  <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
	  <listitem>
	    <para>Means: &ldquo;Apply every non-dangerous
            optimisation, even if it means significantly longer
            compile times.&rdquo;</para>

	    <para>The avoided &ldquo;dangerous&rdquo; optimisations
            are those that can make runtime or space
            <emphasis>worse</emphasis> if you're unlucky.  They are
            normally turned on or off individually.</para>

	    <para>At the moment, <option>-O2</option> is
            <emphasis>unlikely</emphasis> to produce better code than
            <option>-O</option>.</para>
	  </listitem>
	</varlistentry>
1209

1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
	<varlistentry>
	  <term><option>-Ofile &lt;file&gt;</option>:</term>
	  <indexterm><primary>-Ofile &lt;file&gt; option</primary></indexterm>
	  <indexterm><primary>optimising, customised</primary></indexterm>
	  <listitem>
	    <para>(NOTE: not supported yet in GHC 5.x.  Please ask if
	    you're interested in this.)</para>
	    
	    <para>For those who need <emphasis>absolute</emphasis>
            control over <emphasis>exactly</emphasis> what options are
            used (e.g., compiler writers, sometimes :-), a list of
            options can be put in a file and then slurped in with
            <option>-Ofile</option>.</para>

	    <para>In that file, comments are of the
            <literal>&num;</literal>-to-end-of-line variety; blank
            lines and most whitespace is ignored.</para>

	    <para>Please ask if you are baffled and would like an
	    example of <option>-Ofile</option>!</para>
	  </listitem>
	</varlistentry>
      </variablelist>
1233

1234
1235
1236
      <para>We don't use a <option>-O*</option> flag for day-to-day
      work.  We use <option>-O</option> to get respectable speed;
      e.g., when we want to measure something.  When we want to go for
1237
1238
      broke, we tend to use <option>-O -fvia-C</option> (and we go for
      lots of coffee breaks).</para>
rrt's avatar
rrt committed
1239

1240
1241
1242
1243
      <para>The easiest way to see what <option>-O</option> (etc.)
      &ldquo;really mean&rdquo; is to run with <option>-v</option>,
      then stand back in amazement.</para>
    </sect2>
rrt's avatar
rrt committed
1244

1245
1246
    <sect2 id="options-f">
      <title><option>-f*</option>: platform-independent flags</title>
rrt's avatar
rrt committed
1247

1248
1249
      <indexterm><primary>-f* options (GHC)</primary></indexterm>
      <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
rrt's avatar
rrt committed
1250

1251
1252
1253
1254
1255
1256
      <para>These flags turn on and off individual optimisations.
      They are normally set via the <option>-O</option> options
      described above, and as such, you shouldn't need to set any of
      them explicitly (indeed, doing so could lead to unexpected
      results).  However, there are one or two that may be of
      interest:</para>
rrt's avatar
rrt committed
1257

1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
      <variablelist>
	<varlistentry>
	  <term><option>-fexcess-precision</option>:</term>
	  <listitem>
	    <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
	    <para>When this option is given, intermediate floating
	    point values can have a <emphasis>greater</emphasis>
	    precision/range than the final type.  Generally this is a
	    good thing, but some programs may rely on the exact
	    precision/range of
	    <literal>Float</literal>/<literal>Double</literal> values
	    and should not use this option for their compilation.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1272

1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
	<varlistentry>
	  <term><option>-fignore-asserts</option>:</term>
	  <listitem>
	    <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
	    <para>Causes GHC to ignore uses of the function
	    <literal>Exception.assert</literal> in source code (in
	    other words, rewriting <literal>Exception.assert p
	    e</literal> to <literal>e</literal> (see <xref
	    linkend="sec-assertions">).  This flag is turned on by
	    <option>-O</option>.
	    </para>
	  </listitem>
	</varlistentry>

1287
1288
1289
1290
1291
1292
1293
1294
1295
	<varlistentry>
	  <term><option>-fno-strictness</option></term>
	  <indexterm><primary><option>-fno-strictness</option></primary>
	  </indexterm>
	  <listitem>
	    <para>Turns off the strictness analyser; sometimes it eats
	    too many cycles.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1296

1297
1298
1299
1300
1301
1302
1303
1304
1305
	<varlistentry>
	  <term><option>-fno-cpr-analyse</option></term>
	  <indexterm><primary><option>-fno-cpr-analyse</option></primary>
	  </indexterm>
	  <listitem>
	    <para>Turns off the CPR (constructed product result)
	    analysis; it is somewhat experimental.</para>
	  </listitem>
	</varlistentry>
1306

1307
1308
1309
1310
1311
1312
	<varlistentry>
	  <term><option>-funbox-strict-fields</option>:</term>
	  <listitem>
	    <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
	    <indexterm><primary>strict constructor fields</primary></indexterm>
	    <indexterm><primary>constructor fields, strict</primary></indexterm>
1313

1314
1315
1316
	    <para>This option causes all constructor fields which are
            marked strict (i.e. &ldquo;!&rdquo;) to be unboxed or
            unpacked if possible.  For example:</para>
1317

1318
1319
1320
<ProgramListing>
data T = T !Float !Float
</ProgramListing>
rrt's avatar
rrt committed
1321

1322
1323
1324
1325
1326
1327
1328
1329
	    <para>will create a constructor <literal>T</literal>
            containing two unboxed floats if the
            <option>-funbox-strict-fields</option> flag is given.
            This may not always be an optimisation: if the
            <Function>T</Function> constructor is scrutinised and the
            floats passed to a non-strict function for example, they
            will have to be reboxed (this is done automatically by the
            compiler).</para>
rrt's avatar
rrt committed
1330

1331
1332
1333
1334
	    <para>This option should only be used in conjunction with
            <option>-O</option>, in order to expose unfoldings to the
            compiler so the reboxing can be removed as often as
            possible.  For example:</para>
rrt's avatar
rrt committed
1335

1336
1337
1338
1339
<ProgramListing>
f :: T -&#62; Float
f (T f1 f2) = f1 + f2
</ProgramListing>
rrt's avatar
rrt committed
1340

1341
1342
1343
1344
	    <para>The compiler will avoid reboxing
            <Function>f1</Function> and <Function>f2</Function> by
            inlining <Function>+</Function> on floats, but only when
            <option>-O</option> is on.</para>
rrt's avatar
rrt committed
1345

1346
1347
	    <para>Any single-constructor data is eligible for
	    unpacking; for example</para>
rrt's avatar
rrt committed
1348

1349
1350
1351
<ProgramListing>
data T = T !(Int,Int)
</ProgramListing>
rrt's avatar
rrt committed
1352

1353
1354
1355
	    <para>will store the two <literal>Int</literal>s directly
            in the <Function>T</Function> constructor, by flattening
            the pair.  Multi-level unpacking is also supported:</para>
rrt's avatar
rrt committed
1356

1357
1358
1359
1360
<ProgramListing>
data T = T !S
data S = S !Int !Int
</ProgramListing>
rrt's avatar
rrt committed
1361

1362
1363
1364
1365
	    <para>will store two unboxed <literal>Int&num;</literal>s
	    directly in the <Function>T</Function> constructor.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1366

1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
	<varlistentry>
	  <term><option>-funfolding-update-in-place&lt;n&gt;</option></term>
	  <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
	  <listitem>
	    <para>Switches on an experimental "optimisation".
            Switching it on makes the compiler a little keener to
            inline a function that returns a constructor, if the
            context is that of a thunk.
<ProgramListing>
   x = plusInt a b
</ProgramListing>
            If we inlined plusInt we might get an opportunity to use
            update-in-place for the thunk 'x'.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1382

1383
1384
1385
1386
1387
1388
1389
	<varlistentry>
	  <term><option>-funfolding-creation-threshold&lt;n&gt;</option>:</term>
	  <listitem>
	    <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
	    <indexterm><primary>inlining, controlling</primary></indexterm>
	    <indexterm><primary>unfolding, controlling</primary></indexterm>
	    
1390
1391
1392
1393
1394
1395
1396
	    <para>(Default: 45) Governs the maximum size that GHC will 
            allow a function unfolding to be.   (An unfolding has a
            &ldquo;size&rdquo; that reflects the cost in terms of
            &ldquo;code bloat&rdquo; of expanding that unfolding at
            at a call site. A bigger function would be assigned a
            bigger cost.) </para>

1397
1398
1399
1400
	    <para> Consequences: (a) nothing larger than this will be
	    inlined (unless it has an INLINE pragma); (b) nothing
	    larger than this will be spewed into an interface
	    file. </para>
1401
1402
1403


            <para> Increasing this figure is more likely to result in longer
1404
1405
1406
1407
            compile times than faster code.  The next option is more
            useful:</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1408

1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
	<varlistentry>
	  <term><option>-funfolding-use-threshold&lt;n&gt;</option>:</term>
	  <listitem>
	    <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
	    <indexterm><primary>inlining, controlling</primary></indexterm>
	    <indexterm><primary>unfolding, controlling</primary></indexterm>

	    <para>(Default: 8) This is the magic cut-off figure for
            unfolding: below this size, a function definition will be
            unfolded at the call-site, any bigger and it won't.  The
            size computed for a function depends on two things: the
            actual size of the expression minus any discounts that
            apply (see <option>-funfolding-con-discount</option>).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
1425

1426
    </sect2>
1427
    
1428
  </sect1>
1429
1430
1431
1432
  
  &phases;  
  
  <sect1 id="sec-using-concurrent">
1433
<title>Using Concurrent Haskell</title>
rrt's avatar
rrt committed
1434

1435
	     <indexterm><primary>Concurrent Haskell&mdash;use</primary></indexterm>
rrt's avatar
rrt committed
1436

1437
<para>
1438
1439
1440
1441
1442
GHC supports Concurrent Haskell by default, without requiring a
special option or libraries compiled in a certain way.  To get access
to the support libraries for Concurrent Haskell, just import
<literal>Control.Concurrent</literal> (details are in the accompanying
library documentation).</para>
rrt's avatar
rrt committed
1443

1444
<para>
1445
1446
RTS options are provided for modifying the behaviour of the threaded
runtime system.  See <XRef LinkEnd="parallel-rts-opts">.
1447
</para>
1448

1449
<para>
1450
1451
Concurrent Haskell is described in more detail in the documentation
for the <literal>Control.Concurrent</literal> module.
1452
</para>
1453

1454
</Sect1>
rrt's avatar
rrt committed
1455

1456
1457
<Sect1 id="sec-using-parallel">
<title>Using Parallel Haskell</title>
rrt's avatar
rrt committed
1458

1459
<para>
1460
<indexterm><primary>Parallel Haskell&mdash;use</primary></indexterm>
1461
</para>
rrt's avatar
rrt committed
1462

1463
<para>
1464
&lsqb;You won't be able to execute parallel Haskell programs unless PVM3
1465
1466
(Parallel Virtual Machine, version 3) is installed at your site.&rsqb;
</Para>
rrt's avatar
rrt committed
1467

1468
<para>
1469
To compile a Haskell program for parallel execution under PVM, use the
1470
1471
1472
1473
1474
<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
option</Primary></IndexTerm> both when compiling <Emphasis>and
linking</Emphasis>.  You will probably want to <Literal>import
Parallel</Literal> into your Haskell modules.
</Para>
rrt's avatar
rrt committed
1475

1476
1477
1478
<para>
To run your parallel program, once PVM is going, just invoke it
&ldquo;as normal&rdquo;.  The main extra RTS option is
1479
<Option>-qp&lt;n&gt;</Option>, to say how many PVM
1480
1481
1482
&ldquo;processors&rdquo; your program to run on.  (For more details of
all relevant RTS options, please see <XRef
LinkEnd="parallel-rts-opts">.)
1483
</para>
rrt's avatar
rrt committed
1484

1485
<para>
1486
1487
1488
In truth, running Parallel Haskell programs and getting information
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
1489
</para>
rrt's avatar
rrt committed
1490

1491
1492
<Sect2 id="pvm-dummies">
<Title>Dummy's guide to using PVM</Title>
1493

1494
<para>
1495
1496
1497
1498
1499
<indexterm><primary>PVM, how to use</primary></indexterm>
<indexterm><primary>Parallel Haskell&mdash;PVM use</primary></indexterm>
Before you can run a parallel program under PVM, you must set the
required environment variables (PVM's idea, not ours); something like,
probably in your <filename>.cshrc</filename> or equivalent:
rrt's avatar
rrt committed
1500
1501

<ProgramListing>
1502
1503
1504
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
rrt's avatar
rrt committed
1505
1506
</ProgramListing>

1507
</para>
rrt's avatar
rrt committed
1508

1509
<para>
rrt's avatar
rrt committed
1510
Creating and/or controlling your &ldquo;parallel machine&rdquo; is a purely-PVM
1511
1512
1513
business; nothing specific to Parallel Haskell. The following paragraphs
describe how to configure your parallel machine interactively.
</Para>
rrt's avatar
rrt committed
1514

1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
<Para>
If you use parallel Haskell regularly on the same machine configuration it
is a good idea to maintain a file with all machine names and to make the
environment variable PVM_HOST_FILE point to this file. Then you can avoid
the interactive operations described below by just saying
</Para>

<ProgramListing>
pvm $PVM_HOST_FILE
</ProgramListing>

<Para>
You use the <Command>pvm</Command><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
rrt's avatar
rrt committed
1528
machine.  You can then do various things to control/monitor your
rrt's avatar
rrt committed
1529
&ldquo;parallel machine;&rdquo; the most useful being:
1530
</para>
rrt's avatar
rrt committed
1531

1532
<para>
rrt's avatar
rrt committed
1533
1534
1535
1536
1537
<InformalTable>
<TGroup Cols=2>
<ColSpec Align="Left">
<TBody>

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
<row>
<entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></entry>
<entry>exit <command>pvm</command>, leaving it running</entry>
</row>

<row>
<entry><command>halt</command></entry>
<entry>kill off this &ldquo;parallel machine&rdquo; &amp; exit</entry>
</row>

<row>
<entry><command>add &lt;host&gt;</command></entry>
<entry>add <command>&lt;host&gt;</command> as a processor</entry>
</row>

<row>
<entry><command>delete &lt;host&gt;</command></entry>
<entry>delete <command>&lt;host&gt;</command></entry>
</row>

<row>
<entry><command>reset</command></entry>
<entry>kill what's going, but leave PVM up</entry>
</row>

<row>
<entry><command>conf</command></entry>
<entry>list the current configuration</entry>
</row>

<row>
<entry><command>ps</command></entry>
<entry>report processes' status</entry>
</row>

<row>
<entry><command>pstat &lt;pid&gt;</command></entry>
<entry>status of a particular process</entry>
</row>
rrt's avatar
rrt committed
1577
1578
1579
1580

</TBody>
</TGroup>
</InformalTable>
1581
</para>
rrt's avatar
rrt committed
1582

1583
<para>
1584
The PVM documentation can tell you much, much more about <command>pvm</command>!
1585
</para>
rrt's avatar
rrt committed
1586

1587
</sect2>
rrt's avatar
rrt committed
1588

1589
1590
<Sect2 id="par-profiles">
<Title>Parallelism profiles</Title>
rrt's avatar
rrt committed
1591

1592
1593
1594
1595
1596
<para>
<indexterm><primary>parallelism profiles</primary></indexterm>
<indexterm><primary>profiles, parallelism</primary></indexterm>
<indexterm><primary>visualisation tools</primary></indexterm>
</para>
rrt's avatar
rrt committed
1597