using.xml 71 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
<chapter id="using-ghc">
3
  <title>Using GHC</title>
rrt's avatar
rrt committed
4

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

8
9
10
11
12
13
14
15
16
  <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>
17
      <title>command-line arguments</title>
18
19
20
21
22
23
      
      <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
24

25
<screen>
rrt's avatar
rrt committed
26
ghc [argument...]
27
</screen>
rrt's avatar
rrt committed
28

29
      <para>command-line arguments are either options or file names.</para>
30

31
      <para>command-line options begin with <literal>-</literal>.
32
33
34
35
36
37
38
39
40
      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
41

42
43
    <sect2 id="source-file-options">
      <title>command line options in source files</title>
44
45
46
47
48
49
50
51
52
53
    
      <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
54
      <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
55
      pragma</primary></indexterm>:</para>
rrt's avatar
rrt committed
56

57
<programlisting>
58
{-# OPTIONS_GHC -fglasgow-exts #-}
59
60
module X where
...
61
</programlisting>
62
      
63
      <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
64
65
      the top of your source files, upto the first
      (non-literate,non-empty) line not containing
66
      <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
67
68
69
70
      pragmas are recognised.  Do not put comments before, or on the same line
	as, the <literal>OPTIONS_GHC</literal> pragma.</para>

      <para>Note that your command shell does not
71
      get to the source file options, they are just included literally
72
      in the array of command-line arguments the compiler
73
      maintains internally, so you'll be desperately disappointed if
74
      you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para>
75

76
      <para>NOTE: the contents of OPTIONS_GHC are prepended to the
77
      command-line options, so you <emphasis>do</emphasis> have the
78
      ability to override OPTIONS_GHC settings via the command
79
80
81
82
      line.</para>

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

89
90
    <sect2>
      <title>Setting options in GHCi</title>
rrt's avatar
rrt committed
91

92
      <para>Options may also be modified from within GHCi, using the
93
      <literal>:set</literal> command.  See <xref linkend="ghci-set"/>
94
95
96
97
98
      for more details.</para>
    </sect2>
  </sect1>
    
  <sect1 id="static-dynamic-flags">
99
    <title>Static, Dynamic, and Mode options</title>
100
101
102
103
    <indexterm><primary>static</primary><secondary>options</secondary>
    </indexterm>
    <indexterm><primary>dynamic</primary><secondary>options</secondary>
    </indexterm>
104
105
    <indexterm><primary>mode</primary><secondary>options</secondary>
    </indexterm>
106
107

    <para>Each of GHC's command line options is classified as either
108
109
110
111
112
113
114
115
116
    <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
      <firstterm>mode</firstterm>:</para>

    <variablelist>
      <varlistentry>
	<term>Mode flags</term>
	<listitem>
	  <para>For example, <option>--make</option> or <option>-E</option>.
	    There may be only a single mode flag on the command line.  The
117
	    available modes are listed in <xref linkend="modes"/>.</para>
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Dynamic Flags</term>
	<listitem>
	  <para>Most non-mode flags fall into this category.  A dynamic flag
	    may be used on the command line, in a
	    <literal>GHC_OPTIONS</literal> pragma in a source file, or set
	    using <literal>:set</literal> in GHCi.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Static Flags</term>
	<listitem>
	  <para>A few flags are "static", which means they can only be used on
	    the command-line, and remain in force over the entire GHC/GHCi
	    run.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <para>The flag reference tables (<xref
140
    linkend="flag-reference"/>) lists the status of each flag.</para>
141
  </sect1>
rrt's avatar
rrt committed
142

143
144
  <sect1 id="file-suffixes">
    <title>Meaningful file suffixes</title>
rrt's avatar
rrt committed
145

146
147
    <indexterm><primary>suffixes, file</primary></indexterm>
    <indexterm><primary>file suffixes for GHC</primary></indexterm>
rrt's avatar
rrt committed
148

149
150
151
    <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
152

153
    <variablelist>
rrt's avatar
rrt committed
154

155
      <varlistentry>
156
	<term><filename>.hs</filename></term>
157
	<listitem>
158
	  <para>A Haskell module.</para>
159
160
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
161

162
      <varlistentry>
163
164
165
166
	<term>
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	</term>
167
	<listitem>
168
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
	</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
216

217
218
219
220
221
222
223
224
225
226
  <sect1 id="modes">
    <title>Modes of operation</title>

    <para>GHC's behaviour is firstly controlled by a mode flag.  Only
    one of these flags may be given, but it does not necessarily need
    to be the first option on the command-line.  The available modes
    are:</para>

    <variablelist>
      <varlistentry>
227
228
	<term>
	  <cmdsynopsis><command>ghc</command>
229
	    <arg choice='plain'>&ndash;&ndash;interactive</arg>
230
231
232
233
	  </cmdsynopsis>
          <indexterm><primary>interactive mode</primary></indexterm>
          <indexterm><primary>ghci</primary></indexterm>
	</term>
234
235
236
	<listitem>
	  <para>Interactive mode, which is also available as
	  <command>ghci</command>.  Interactive mode is described in
237
	  more detail in <xref linkend="ghci"/>.</para>
238
239
240
241
	</listitem>
      </varlistentry>
      
      <varlistentry>
242
243
	<term>
	  <cmdsynopsis><command>ghc</command>
244
	    <arg choice='plain'>&ndash;&ndash;make</arg>
245
246
247
248
	  </cmdsynopsis>
          <indexterm><primary>make mode</primary></indexterm>
          <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
	</term>
249
250
251
252
253
254
	<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>.  Make mode is described in <xref
255
	  linkend="make-mode"/>.</para>
256
257
258
259
	</listitem>
      </varlistentry>

      <varlistentry>
260
261
	<term>
	  <cmdsynopsis><command>ghc</command>
262
	    <arg choice='plain'>&ndash;e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
263
264
265
          </cmdsynopsis>
          <indexterm><primary>eval mode</primary></indexterm>
	</term>
266
267
268
269
	<listitem>
	  <para>Expression-evaluation mode.  This is very similar to
	  interactive mode, except that there is a single expression
	  to evaluate (<replaceable>expr</replaceable>) which is given
270
	  on the command line.  See <xref linkend="eval-mode"/> for
271
272
273
274
275
	  more details.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
276
277
	<term>
          <cmdsynopsis>
278
279
280
281
282
283
284
	    <command>ghc</command>
	    <group>
	      <arg>-E</arg>
	      <arg>-C</arg>
	      <arg>-S</arg>
	      <arg>-c</arg>
	    </group>
285
286
287
288
289
290
	  </cmdsynopsis>
	  <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>
        </term>
291
292
293
294
295
296
297
	<listitem>
	  <para>This is the traditional batch-compiler mode, in which
	  GHC can compile source files one at a time, or link objects
	  together into an executable.  This mode also applies if
	  there is no other mode flag specified on the command line,
	  in which case it means that the specified files should be
	  compiled and then linked to form a program. See <xref
298
	  linkend="options-order"/>.</para>
299
300
301
302
	</listitem>
      </varlistentry>

      <varlistentry>
303
304
305
306
307
308
309
	<term>
          <cmdsynopsis>
            <command>ghc</command>
	    <arg choice='plain'>&ndash;M</arg>
          </cmdsynopsis>
          <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
310
311
312
313
	<listitem>
	  <para>Dependency-generation mode.  In this mode, GHC can be
	  used to generate dependency information suitable for use in
	  a <literal>Makefile</literal>.  See <xref
314
	  linkend="sec-makefile-dependencies"/>.</para>
315
316
317
318
	</listitem>
      </varlistentry>

      <varlistentry>
319
320
321
322
323
324
325
	<term>
          <cmdsynopsis>
            <command>ghc</command>
	    <arg choice='plain'>&ndash;&ndash;mk-dll</arg>
          </cmdsynopsis>
	  <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
326
327
	<listitem>
	  <para>DLL-creation mode (Windows only).  See <xref
328
	  linkend="win32-dlls-create"/>.</para>
329
330
331
332
333
334
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2 id="make-mode">
      <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
335
336
      <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
      <indexterm><primary>separate compilation</primary></indexterm>
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
      
      <para>When given the <option>&ndash;&ndash;make</option> option,
      GHC will 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>
ghc &ndash;&ndash;make Main.hs
</screen>

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

      <para>The main advantages to using <literal>ghc
      &ndash;&ndash;make</literal> 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.
ross's avatar
ross committed
365
	  Compiling a multi-module program with <literal>ghc
366
367
368
369
370
	  &ndash;&ndash;make</literal> can be up to twice as fast as
	  running <literal>ghc</literal> individually on each source
	  file.</para>
	</listitem>
	<listitem>
371
	  <para>You don't have to write a <literal>Makefile</literal>.</para>
372
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
373
374
375
376
377
378
379
380
381
382
383
384
385
	</listitem>
	<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
      this chapter can be used with
      <option>&ndash;&ndash;make</option>, but note 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
386
      file only, you'll need to use an <literal>OPTIONS_GHC</literal>
387
      pragma (see <xref linkend="source-file-options"/>).</para>
388
389

      <para>If the program needs to be linked with additional objects
ross's avatar
ross committed
390
      (say, some auxiliary C code), then the object files can be
391
392
393
394
395
396
397
398
399
400
401
402
403
      given on the command line and GHC will include them when linking
      the executable.</para>
      
      <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>

      <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
404
      linkend="search-path"/>).</para>
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
    </sect2>
  
    <sect2 id="eval-mode">
      <title>Expression evaluation mode</title>

      <para>This mode is very similar to interactive mode, except that
      there is a single expression to evaluate which is specified on
      the command line as an argument to the <option>-e</option>
      option:</para>

<screen>
ghc -e <replaceable>expr</replaceable>
</screen>

      <para>Haskell source files may be named on the command line, and
      they will be loaded exactly as in interactive mode.  The
      expression is evaluated in the context of the loaded
      modules.</para>

      <para>For example, to load and run a Haskell program containing
      a module <literal>Main</literal>, we might say</para>

<screen>
ghc -e Main.main Main.hs
</screen>
      
      <para>or we can just use this mode to evaluate expressions in
      the context of the <literal>Prelude</literal>:</para>

<screen>
$ ghc -e "interact (unlines.map reverse.lines)"
hello
olleh
</screen>
    </sect2>

    <sect2 id="options-order">
      <title>Batch compiler mode</title>
      
444
      <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
445
446
447
448
449
450
451
452
453
      given on the command line.</para>
      
      <para>The first phase to run is determined by each 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>
      
      <informaltable>
	<tgroup cols="4">
454
455
456
457
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
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
	  
	  <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: </para>

<screen>
ghc -c Foo.hs</screen>
      
      <para>to compile the Haskell source file
      <filename>Foo.hs</filename> to an object file
      <filename>Foo.o</filename>.</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
532
      linkend="options-codegen"/> for more details.</para>
533
534
535

      <para>Note: C pre-processing is optional, the
      <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
536
      flag turns it on.  See <xref linkend="c-pre-processor"/> for more
537
538
      details.</para>
      
539
540
      <para>Note: The option <option>-E</option><indexterm><primary>-E
      option</primary></indexterm> runs just the pre-processing passes
541
542
543
      of the compiler, dumping the result in a file.  Note that this
      differs from the previous behaviour of dumping the file to
      standard output.</para>
544
545
546
547
548
549
550
551
552
553

      <sect3 id="overriding-suffixes">
	<title>Overriding the default behaviour for a file</title>

	<para>As described above, the way in which a file is processed by GHC
	  depends on its suffix.  This behaviour can be overriden using the
	  <option>-x</option> option:</para>

	<variablelist>
	  <varlistentry>
554
555
556
	    <term><option>-x</option> <replaceable>suffix</replaceable>
	    	      <indexterm><primary><option>-x</option></primary>
	      </indexterm></term>
557
558
559
560
561
562
563
564
565
566
567
	      <listitem>
		<para>Causes all files following this option on the command
		  line to be processed as if they had the suffix
		  <replaceable>suffix</replaceable>.  For example, to compile a
		  Haskell module in the file <literal>M.my-hs</literal>,
		  use <literal>ghc -c -x hs M.my-hs</literal>.</para>
	      </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>

568
569
570
    </sect2>
  </sect1>

571
572
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
573

574
575
    <indexterm><primary>help options</primary></indexterm>
    <indexterm><primary>verbosity options</primary></indexterm>
576
577
578

    <variablelist>
      <varlistentry>
579
580
581
582
583
584
585
586
	<term>
          <option>&ndash;&ndash;help</option>
          <indexterm><primary><option>&ndash;&ndash;help</option></primary></indexterm>
        </term>
	<term>
          <option>-?</option>
          <indexterm><primary><option>-?</option></primary></indexterm>
        </term>
587
588
589
590
591
	<listitem>
	  <para>Cause GHC to spew a long usage message to standard
          output and then exit.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
592

593
      <varlistentry>
594
595
596
597
	<term>
          <option>-v</option>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
598
599
	<listitem>
	  <para>The <option>-v</option> option makes GHC
600
          <emphasis>verbose</emphasis>: it reports its version number
601
602
603
604
605
606
607
608
609
610
611
612
613
          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>
614
615
616
617
	<term>
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
618
619
620
621
622
623
624
625
626
	<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>
627
	      <term><option>-v0</option></term>
628
629
630
631
632
633
634
	      <listitem>
		<para>Disable all non-essential messages (this is the
		default).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
635
	      <term><option>-v1</option></term>
636
637
638
	      <listitem>
		<para>Minimal verbosity: print one line per
		compilation (this is the default when
639
640
		<option>&ndash;&ndash;make</option> or
		<option>&ndash;&ndash;interactive</option> is on).</para>
641
642
643
644
	      </listitem>
	    </varlistentry>

	    <varlistentry>
645
	      <term><option>-v2</option></term>
646
647
648
649
650
651
652
653
	      <listitem>
		<para>Print the name of each compilation phase as it
		is executed. (equivalent to
		<option>-dshow-passes</option>).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
654
	      <term><option>-v3</option></term>
655
656
657
658
659
660
661
662
	      <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>
663
	      <term><option>-v4</option></term>
664
665
666
667
668
669
670
671
672
673
674
675
	      <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>
676
677
678
679
680
681
682
683
	<term>
          <option>-V</option>
          <indexterm><primary><option>-V</option></primary></indexterm>
        </term>
	<term>
          <option>&ndash;&ndash;version</option>
          <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
        </term>
684
685
686
687
	<listitem>
	  <para>Print a one-line string including GHC's version number.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
688

689
      <varlistentry>
690
691
692
693
	<term>
          <option>&ndash;&ndash;numeric-version</option>
          <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
        </term>
694
695
696
697
	<listitem>
	  <para>Print GHC's numeric version number only.</para>
	</listitem>
      </varlistentry>
698
699

      <varlistentry>
700
701
702
703
	<term>
          <option>&ndash;&ndash;print-libdir</option>
          <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
        </term>
704
705
706
707
	<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
708
	  <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
709
710
711
	  is the value of
	  <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
	  </indexterm>in the package configuration file (see <xref
712
	  linkend="packages"/>).</para>
713
714
715
	</listitem>
      </varlistentry>

716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
      <varlistentry>
	<term><option>-ferror-spans</option>
          <indexterm><primary><option>-ferror-spans</option></primary>
	  </indexterm>
        </term>
	<listitem>
	  <para>Causes GHC to emit the full source span of the
	  syntactic entity relating to an error message.  Normally, GHC
	  emits the source location of the start of the syntactic
	  entity only.</para>

	  <para>For example:</para>

<screen>test.hs:3:6: parse error on input `where'</screen>

	  <para>becomes:</para>

<screen>test296.hs:3:6-10: parse error on input `where'</screen>

	  <para>And multi-line spans are possible too:</para>

<screen>test.hs:(5,4)-(6,7):
    Conflicting definitions for `a'
    Bound at: test.hs:5:4
              test.hs:6:7
    In the binding group for: a, b, a</screen>

	  <para>Note that line numbers start counting at one, but
	  column numbers start at zero.  This choice was made to
	  follow existing convention (i.e. this is how Emacs does
	  it).</para>
	</listitem>
      </varlistentry>
749
750
751
752
753
754
755
756
757
758
759
760
761

      <varlistentry>
        <term><option>-Rghc-timing</option>
        <indexterm><primary><option>-Rghc-timing</option></primary></indexterm>
        </term>
        <listitem>
          <para>Prints a one-line summary of timing statistics for the
          GHC run.  This option is equivalent to
          <literal>+RTS&nbsp;-tstderr</literal>, see <xref
          linkend="rts-options-gc" />.
          </para>
        </listitem>
      </varlistentry>
762
763
764
    </variablelist>
  </sect1>

765
  &separate;
rrt's avatar
rrt committed
766

767
768
769
770
771
772
773
774
775
776
777
778
  <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:
779
    <option>-fwarn-overlapping-patterns</option>,
780
781
782
783
784
785
786
    <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>

787
    <variablelist>
788
789
790
791

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
792
	  <indexterm><primary>-W option</primary></indexterm>
793
794
795
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
	  <option>-fwarn-unused-matches</option>,
796
797
	  <option>-fwarn-unused-imports</option>,
	  <option>-fwarn-misc</option>, and
798
799
800
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
801

802
803
804
      <varlistentry>
	<term><option>-w</option>:</term>
	<listitem>
805
	  <indexterm><primary><option>-w</option></primary></indexterm>
806
807
808
	  <para>Turns off all warnings, including the standard ones.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
809

810
811
812
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
813
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
814
815
816
	  <para>Turns on all warning options.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
817

818
819
820
821
822
823
824
825
826
      <varlistentry>
	<term><option>-Werror</option>:</term>
	<listitem>
	  <indexterm><primary><option>-Werror</option></primary></indexterm>
	  <para>Makes any warning into a fatal error. Useful so that you don't 
	    miss warnings when doing batch compilation. </para>
	</listitem>
      </varlistentry>

827
    </variablelist>
rrt's avatar
rrt committed
828

829
830
831
    <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
832

833
    <variablelist>
rrt's avatar
rrt committed
834

835
836
837
838
839
840
841
842
843
      <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
844
	  linkend="deprecated-pragma"/>.</para>
845
846
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
847

848
849
850
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
851
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
852
853
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
854

855
856
857
858
859
	  <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
860

861
862
863
864
865
866
867
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
868
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
869
870
871
872
873
874
875
876
877
878
879
880
881
	  <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>
882
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
	  <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>

903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
      <varlistentry>
	<term><option>-fwarn-incomplete-record-updates</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-incomplete-record-updates</option></primary></indexterm>
	  <indexterm><primary>incomplete record updates, warning</primary></indexterm>
	  <indexterm><primary>record updates, incomplete</primary></indexterm>

	  <para>The function
          <function>f</function> below will fail when applied to
          <literal>Bar</literal>, so the compiler will emit a warning about
          this when <option>-fwarn-incomplete-record-updates</option> is
          enabled.</para>

<programlisting>
data Foo = Foo { x :: Int }
         | Bar

f :: Foo -> Foo
f foo = foo { x = 6 }
</programlisting>

	  <para>This option isn't enabled be default because it can be
          very noisy, and it often doesn't indicate a bug in the
          program.</para>
	</listitem>
      </varlistentry>

930
      <varlistentry>
931
932
933
934
	<term>
          <option>-fwarn-misc</option>:
          <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
        </term>
935
936
937
938
939
940
941
942
	<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>

943
      <varlistentry>
944
945
	<term>
          <option>-fwarn-missing-fields</option>:
946
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
947
948
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>
949
950
        </term>
	<listitem>
951
952
953
954
955
956
957
958
959
960
961
962

	  <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>
963
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
964
965
966
967
968
969
970
	  <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>
971
972
973
974
975
976
977
978
979
980
981
982
	  <para>The warning is suppressed if the method name
	  begins with an underscore.  Here's an example where this is useful:
	    <programlisting>
	      class C a where
	        _simpleFn :: a -> String
	        complexFn :: a -> a -> String
	        complexFn x y = ... _simpleFn ...
	      </programlisting>
	    The idea is that: (a) users of the class will only call <literal>complexFn</literal>; 
	    never <literal>_simpleFn</literal>; and (b)
	    instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>.
	    </para>
983
984
985
986
987
988
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
989
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
990
991
992
993
994
995
996
997
998
999
1000
1001
	  <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>
1002
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
	  <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>

1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
      <varlistentry>
	<term><option>-fwarn-orphans</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm>
	  <indexterm><primary>orphan instances, warning</primary></indexterm>
	  <indexterm><primary>orphan rules, warning</primary></indexterm>
	  
	  <para>This option causes a warning to be emitted whenever the 
	    module contains an "orphan" instance declaration or rewrite rule.
	    An instance declartion is an orphan if it appears in a module in
	    which neither the class nor the type being instanced are declared
	    in the same module.  A rule is an orphan if it is a rule for a
	    function declared in another module.  A module containing any
	  orphans is called an orphan module.</para>
	  <para>The trouble with orphans is that GHC must pro-actively read the interface
	    files for all orphan modules, just in case their instances or rules
	    play a role, whether or not the module's interface would otherwise 
	    be of any use.  Other things being equal, avoid orphan modules.</para>
	</listitem>
      </varlistentry>

1039
      <varlistentry>
1040
1041
1042
1043
1044
1045
	<term>
          <option>-fwarn-overlapping-patterns</option>:
          <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
          <indexterm><primary>overlapping patterns, warning</primary></indexterm>
          <indexterm><primary>patterns, overlapping</primary></indexterm>
        </term>
1046
1047
1048
1049
1050
	<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
1051
1052
1053
1054
f :: String -&#62; Int
f []     = 0
f (_:xs) = 1
f "2"    = 2
1055
</programlisting>
rrt's avatar
rrt committed
1056

1057
	  <para>where the last pattern match in <function>f</function>
1058
1059
1060
1061
1062
          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
1063

1064
1065
1066
1067
1068
1069
1070
1071
1072
      <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>
1073
1074
1075
1076
1077
1078
	  <para>``Lambda-bound patterns'' includes all places where there is a single pattern,
	    including list comprehensions and do-notation.  In these cases, a pattern-match 
	    failure is quite legitimate, and triggers filtering (list comprehensions) or
	    the monad <literal>fail</literal> operation (monads). For example:
	    <programlisting>
	      f :: [Maybe a] -> [a]
1079
	      f xs = [y | Just y &lt;- xs]
1080
1081
1082
1083
1084
1085
1086
	      </programlisting>
	    Switching on <option>-fwarn-simple-patterns</option> will elicit warnings about
	    these probably-innocent cases, which is why the flag is off by default. </para>
	  <para> The <literal>deriving( Read )</literal> mechanism produces monadic code with
	    pattern matches, so you will also get misleading warnings about the compiler-generated
	    code.  (This is arguably a Bad Thing, but it's awkward to fix.)</para>

1087
1088
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1089

1090
1091
1092
      <varlistentry>
	<term><option>-fwarn-type-defaults</option>:</term>
	<listitem>
1093
	  <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
1094
1095
1096
1097
1098
1099
	  <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
1100
          otherwise unconstrained value <constant>1</constant> to be
1101
1102
1103
1104
1105
1106
1107
1108
          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
1109

1110
1111
1112
      <varlistentry>
	<term><option>-fwarn-unused-binds</option>:</term>
	<listitem>
1113
	  <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
1114
1115
1116
1117
1118
	  <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>
1119
1120
1121
1122
1123
1124
1125
	  <para>A definition is regarded as "used" if (a) it is exported, or (b) it is
	    mentioned in the right hand side of another definition that is used, or (c) the 
	    function it defines begins with an underscore.  The last case provides a 
	    way to suppress unused-binding warnings selectively.  </para>
	  <para> Notice that a variable
	    is reported as unused even if it appears in the right-hand side of another
	    unused binding. </para>
1126
1127
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1128

1129
1130
1131
      <varlistentry>
	<term><option>-fwarn-unused-imports</option>:</term>
	<listitem>
1132
	  <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
1133
1134
	  <indexterm><primary>unused imports, warning</primary></indexterm>
	  <indexterm><primary>imports, unused</primary></indexterm>
rrt's avatar
rrt committed
1135

1136
1137
1138
1139
	  <para>Report any modules that are explicitly imported but
	  never used.  However, the form <literal>import M()</literal> is
	  never reported as an unused import, because it is a useful idiom
	  for importing instance declarations, which are anonymous in Haskell.</para>
1140
1141
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1142

1143
1144
1145
      <varlistentry>
	<term><option>-fwarn-unused-matches</option>:</term>
	<listitem>
1146
	  <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
1147
1148
1149
1150
1151
1152
	  <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
1153
          <varname>x</varname> and <varname>y</varname> as unused.  The
1154
1155
1156
1157
1158
          warning is suppressed if the variable name begins with an underscore, thus:
	    <programlisting>
	       f _x = True
	    </programlisting>
          </para>
1159
1160
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1161

1162
    </variablelist>
rrt's avatar
rrt committed
1163

1164
    <para>If you're feeling really paranoid, the
1165
1166
1167
1168
1169
    <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
1170

1171
  </sect1>
rrt's avatar
rrt committed
1172

1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
  &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>

1199
1200
1201
1202
1203
      <para>Note that higher optimisation levels cause more
      cross-module optimisation to be performed, which can have an
      impact on how much of your program needs to be recompiled when
      you change something.  This is one reaosn to stick to
      no-optimisation when developing code.</para>
rrt's avatar
rrt committed
1204

1205
      <variablelist>
rrt's avatar
rrt committed
1206

1207
	<varlistentry>
1208
1209
1210
1211
	  <term>
            No <option>-O*</option>-type option specified:
            <indexterm><primary>-O* not specified</primary></indexterm>
          </term>
1212
1213
1214
1215
1216
1217
1218
	  <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
1219

1220
	<varlistentry>
1221
1222
1223
1224
	  <term>
            <option>-O0</option>:
            <indexterm><primary><option>-O0</option></primary></indexterm>
          </term>
1225
1226
1227
1228
1229
1230
1231
1232
1233
	  <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
1234

1235
	<varlistentry>
1236
1237
1238
1239
1240
1241
	  <term>
            <option>-O</option> or <option>-O1</option>:
            <indexterm><primary>-O option</primary></indexterm>
            <indexterm><primary>-O1 option</primary></indexterm>
            <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
          </term>
1242
1243
1244
1245
	  <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>
1246
1247
1248
1249

	    <para><option>-O</option> currently also implies
	    <option>-fvia-C</option>.  This may change in the
	    future.</para>
1250
1251
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1252

1253
	<varlistentry>
1254
1255
1256
1257
1258
	  <term>
            <option>-O2</option>:
            <indexterm><primary>-O2 option</primary></indexterm>
            <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
          </term>
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
	  <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>
1274

1275
	<varlistentry>
1276
1277
1278
1279
1280
	  <term>
            <option>-Ofile &lt;file&gt;</option>:
            <indexterm><primary>-Ofile &lt;file&gt; option</primary></indexterm>
            <indexterm><primary>optimising, customised</primary></indexterm>
          </term>
1281
	  <listitem>
1282
	    <para>(NOTE: not supported since GHC 4.x.  Please ask if
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
	    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>
1300

1301
1302
1303
      <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
1304
      broke, we tend to use <option>-O2 -fvia-C</option> (and we go for
1305
      lots of coffee breaks).</para>
rrt's avatar
rrt committed
1306

1307
1308
1309
1310
      <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
1311

1312
1313
    <sect2 id="options-f">
      <title><option>-f*</option>: platform-independent flags</title>
rrt's avatar
rrt committed
1314

1315
1316
      <indexterm><primary>-f* options (GHC)</primary></indexterm>
      <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
rrt's avatar
rrt committed
1317

1318
1319
1320
1321
1322
1323
      <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
1324

1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
      <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
1339

1340
1341
1342
1343
1344
1345
1346
1347
	<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
1348
	    linkend="sec-assertions"/>).  This flag is turned on by
1349
1350
1351
1352
1353
	    <option>-O</option>.
	    </para>
	  </listitem>
	</varlistentry>

1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
	<varlistentry>
	  <term>
            <option>-fno-cse</option>
            <indexterm><primary><option>-fno-cse</option></primary></indexterm>
          </term>
	  <listitem>
	    <para>Turns off the common-sub-expression elimination optimisation.
	      Can be useful if you have some <literal>unsafePerformIO</literal>
	    expressions that you don't want commoned-up.</para>
	  </listitem>
	</varlistentry>

1366
	<varlistentry>
1367
1368
1369
1370
	  <term>
            <option>-fno-strictness</option>
            <indexterm><primary><option>-fno-strictness</option></primary></indexterm>
          </term>
1371
1372
1373
1374
1375
	  <listitem>
	    <para>Turns off the strictness analyser; sometimes it eats
	    too many cycles.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1376

1377
	<varlistentry>
1378
	  <term>
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
            <option>-fno-full-laziness</option>
            <indexterm><primary><option>-fno-full-laziness</option></primary></indexterm>
          </term>
	  <listitem>
	    <para>Turns off the full laziness optimisation (also known as
	      let-floating).  Full laziness increases sharing, which can lead
	      to increased memory residency.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <option>-fno-state-hack</option>
            <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
1393
          </term>
1394
	  <listitem>
1395
1396
1397
1398
1399
	    <para>Turn off the "state hack" whereby any lambda with a
	      <literal>State#</literal> token as argument is considered to be
	      single-entry, hence it is considered OK to inline things inside
	      it.  This can improve performance of IO and ST monad code, but it
	    runs the risk of reducing sharing.</para> 
1400
1401
	  </listitem>
	</varlistentry>
1402

1403
	<varlistentry>
1404
1405
	  <term>
            <option>-funbox-strict-fields</option>:
1406
1407
1408
	    <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
	    <indexterm><primary>strict constructor fields</primary></indexterm>
	    <indexterm><primary>constructor fields, strict</primary></indexterm>
1409
1410
          </term>
	  <listitem>
1411
1412
	    <para>This option causes all constructor fields which are
            marked strict (i.e. &ldquo;!&rdquo;) to be unboxed or
1413
1414
1415
            unpacked if possible.  It is equivalent to adding an
            <literal>UNPACK</literal> pragma to every strict
            constructor field (see <xref
1416
            linkend="unpack-pragma"/>).</para>
1417
1418
1419
1420
1421

	    <para>This option is a bit of a sledgehammer: it might
	    sometimes make things worse.  Selectively unboxing fields
	    by using <literal>UNPACK</literal> pragmas might be
	    better.</para>
1422
1423
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1424

1425
	<varlistentry>
1426
1427
1428
1429
	  <term>
            <option>-funfolding-update-in-place&lt;n&gt;</option>
            <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
          </term>
1430
1431
1432
1433
1434
	  <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.
1435
<programlisting>
1436
   x = plusInt a b
1437
</programlisting>
1438
1439
1440
1441
            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
1442

1443
	<varlistentry>
1444
1445
	  <term>
            <option>-funfolding-creation-threshold&lt;n&gt;</option>:
1446
1447
1448
	    <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
	    <indexterm><primary>inlining, controlling</primary></indexterm>
	    <indexterm><primary>unfolding, controlling</primary></indexterm>
1449
1450
          </term>
	  <listitem>
1451
1452
1453
1454
1455
1456
1457
	    <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>

1458
1459
1460
1461
	    <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>
1462
1463
1464


            <para> Increasing this figure is more likely to result in longer
1465
1466
1467
1468
            compile times than faster code.  The next option is more
            useful:</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1469

1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
	<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>
1486

1487
    </sect2>
1488
    
1489
  </sect1>
1490
1491
1492
1493
  
  &phases;  
  
  <sect1 id="sec-using-concurrent">
1494
1495
    <title>Using Concurrent Haskell</title>
    <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
rrt's avatar
rrt committed
1496

1497
1498
1499
1500
1501
    <para>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
      <ulink
	url="../libraries/base/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>.  More information on Concurrent Haskell is provided in the documentation for that module.</para>
rrt's avatar
rrt committed
1502

1503
1504
    <para>The following RTS option(s) affect the behaviour of Concurrent
      Haskell programs:<indexterm><primary>RTS options, concurrent</primary></indexterm></para>
rrt's avatar
rrt committed
1505

1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
    <variablelist>
      <varlistentry>
	<term><option>-C<replaceable>s</replaceable></option></term>
	<listitem>
	  <para><indexterm><primary><option>-C<replaceable>s</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
	    Sets the context switch interval to <replaceable>s</replaceable>
	    seconds.  A context switch will occur at the next heap block
	    allocation after the timer expires (a heap block allocation occurs
	    every 4k of allocation).  With <option>-C0</option> or
	    <option>-C</option>, context switches will occur as often as
	    possible (at every heap block allocation).  By default, context
	    switches occur every 20ms.  Note that GHC's internal timer ticks
	    every 20ms, and the context switch timer is always a multiple of
	    this timer, so 20ms is the maximum granularity available for timed
	    context switches.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
rrt's avatar
rrt committed
1525

1526
1527
<sect1 id="sec-using-parallel">
<title>Using parallel Haskell</title>
rrt's avatar
rrt committed
1528

1529
<para>
1530
1531 <