using.xml 69.3 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>
Ian Lynagh's avatar
Ian Lynagh committed
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

Ian Lynagh's avatar
Ian Lynagh committed
29
      <para>Command-line arguments are either options or file names.</para>
30

Ian Lynagh's avatar
Ian Lynagh committed
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
    <sect2 id="source-file-options">
Ian Lynagh's avatar
Ian Lynagh committed
43
      <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
77
78
      <para>NOTE: the contents of OPTIONS_GHC are appended to the
      command-line options, so options given in the source file
      override those given on the command-line.</para>
79
80
81

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

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

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

Ian Lynagh's avatar
Ian Lynagh committed
106
107
    <para>Each of GHC's command line options is classified as
    <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
108
109
110
111
112
113
114
      <firstterm>mode</firstterm>:</para>

    <variablelist>
      <varlistentry>
	<term>Mode flags</term>
	<listitem>
	  <para>For example, <option>--make</option> or <option>-E</option>.
Ian Lynagh's avatar
Ian Lynagh committed
115
	    There may only be a single mode flag on the command line.  The
116
	    available modes are listed in <xref linkend="modes"/>.</para>
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
	</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
139
    linkend="flag-reference"/>) lists the status of each flag.</para>
140
141
142
143
144

    <para>There are a few flags that are static except that they can
    also be used with GHCi's <literal>:set</literal> command; these
    are listed as &ldquo;static/<literal>:set</literal>&rdquo; in the
    table.</para> 
145
  </sect1>
rrt's avatar
rrt committed
146

147
148
  <sect1 id="file-suffixes">
    <title>Meaningful file suffixes</title>
rrt's avatar
rrt committed
149

150
151
    <indexterm><primary>suffixes, file</primary></indexterm>
    <indexterm><primary>file suffixes for GHC</primary></indexterm>
rrt's avatar
rrt committed
152

153
154
155
    <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
156

157
    <variablelist>
rrt's avatar
rrt committed
158

159
      <varlistentry>
160
	<term><filename>.hs</filename></term>
161
	<listitem>
162
	  <para>A Haskell module.</para>
163
164
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
165

166
      <varlistentry>
167
168
169
170
	<term>
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	</term>
171
	<listitem>
172
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
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
216
217
218
219
	</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
220

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

      <varlistentry>
262
	<term>
263
264
	  <cmdsynopsis><command>ghc -e</command>
	     <arg choice='plain'><replaceable>expr</replaceable></arg>
265
266
267
          </cmdsynopsis>
          <indexterm><primary>eval mode</primary></indexterm>
	</term>
268
269
270
271
	<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
272
	  on the command line.  See <xref linkend="eval-mode"/> for
273
274
275
276
277
	  more details.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
278
279
	<term>
          <cmdsynopsis>
280
281
282
283
	    <command>ghc -E</command>
	    <command>ghc -c</command>
	    <command>ghc -S</command>
	    <command>ghc -c</command>
284
285
286
287
288
289
	  </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>
290
291
292
293
294
295
296
	<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
297
	  linkend="options-order"/>.</para>
298
299
300
301
	</listitem>
      </varlistentry>

      <varlistentry>
302
303
	<term>
          <cmdsynopsis>
304
            <command>ghc -M</command>
305
306
307
          </cmdsynopsis>
          <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
308
309
310
311
	<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
312
	  linkend="makefile-dependencies"/>.</para>
313
314
315
316
	</listitem>
      </varlistentry>

      <varlistentry>
317
318
	<term>
          <cmdsynopsis>
319
            <command>ghc --mk-dll</command>
320
          </cmdsynopsis>
321
	  <indexterm><primary>DLL-creation mode</primary></indexterm>
322
        </term>
323
324
	<listitem>
	  <para>DLL-creation mode (Windows only).  See <xref
325
	  linkend="win32-dlls-create"/>.</para>
326
327
	</listitem>
      </varlistentry>
328
329
330
331
332
333
334
335
336
337
338
339
340
341

      <varlistentry>
	<term>
	  <cmdsynopsis>
          <command>ghc --help</command> <command>ghc -?</command>
	    </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;help</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Cause GHC to spew a long usage message to standard
          output and then exit.</para>
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
342
343
344
345
346
347
348
349
350
351
352
353
      <varlistentry>
	<term>
          <cmdsynopsis>
            <command>ghc --supported-languages</command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;supported-languages</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Print the supported language extensions.</para>
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
354
355
356
357
358
359
360
361
362
363
364
365
      <varlistentry>
	<term>
          <cmdsynopsis>
            <command>ghc --info</command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;info</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Print information about the compiler.</para>
	</listitem>
      </varlistentry>

366
367
368
      <varlistentry>
	<term>
          <cmdsynopsis>
369
370
371
            <command>ghc --version</command>
            <command>ghc -V</command>
          </cmdsynopsis>
372
373
374
375
376
377
378
379
380
381
382
          <indexterm><primary><option>-V</option></primary></indexterm>
          <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Print a one-line string including GHC's version number.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
          <cmdsynopsis>
383
384
            <command>ghc --numeric-version</command>
          </cmdsynopsis>
385
386
387
388
389
390
391
392
393
394
          <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Print GHC's numeric version number only.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <cmdsynopsis>
395
396
            <command>ghc --print-libdir</command>
          </cmdsynopsis>
397
398
399
400
401
402
403
404
          <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
        </term>
	<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
	  <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
	  is the value of
Ian Lynagh's avatar
Ian Lynagh committed
405
406
407
	  <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
      in the package configuration file
      (see <xref linkend="packages"/>).</para>
408
409
410
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
411
412
413
414
415
416
417
418
419
420
421
422
423
424
      <varlistentry>
	<term>
	  <cmdsynopsis>
            <command>ghc --print-docdir</command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;print-docdir</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Print the path to GHC's documentation directory. Note that
      some distributions do no include the documentation, in which case
      this directory may be empty or may not exist.</para>
	</listitem>
      </varlistentry>

425
426
427
428
    </variablelist>

    <sect2 id="make-mode">
      <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
429
430
      <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
      <indexterm><primary>separate compilation</primary></indexterm>
431
432
433
      
      <para>When given the <option>&ndash;&ndash;make</option> option,
      GHC will build a multi-module Haskell program by following
Ian Lynagh's avatar
Ian Lynagh committed
434
      dependencies from one or more root modules (usually just
435
436
437
438
439
440
441
442
443
444
445
446
447
      <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
Ian Lynagh's avatar
Ian Lynagh committed
448
      date, and finally, if there is a <literal>Main</literal> module,
449
450
451
452
453
454
455
456
457
458
      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
459
	  Compiling a multi-module program with <literal>ghc
460
461
462
463
464
	  &ndash;&ndash;make</literal> can be up to twice as fast as
	  running <literal>ghc</literal> individually on each source
	  file.</para>
	</listitem>
	<listitem>
465
	  <para>You don't have to write a <literal>Makefile</literal>.</para>
466
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
467
468
469
470
471
472
473
474
475
476
477
478
479
	</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
480
      file only, you'll need to use an <literal>OPTIONS_GHC</literal>
481
      pragma (see <xref linkend="source-file-options"/>).</para>
482
483

      <para>If the program needs to be linked with additional objects
ross's avatar
ross committed
484
      (say, some auxiliary C code), then the object files can be
485
486
487
488
489
490
491
492
493
494
495
496
497
      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
498
      linkend="search-path"/>).</para>
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
    </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>
      
538
      <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
539
540
541
542
      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
Ian Lynagh's avatar
Ian Lynagh committed
543
      relevant flag is present, then go all the way through to linking.
544
545
546
547
      This table summarises:</para>
      
      <informaltable>
	<tgroup cols="4">
548
549
550
551
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
	  
	  <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
626
      linkend="options-codegen"/> for more details.</para>
627
628
629

      <para>Note: C pre-processing is optional, the
      <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
630
      flag turns it on.  See <xref linkend="c-pre-processor"/> for more
631
632
      details.</para>
      
633
634
      <para>Note: The option <option>-E</option><indexterm><primary>-E
      option</primary></indexterm> runs just the pre-processing passes
635
      of the compiler, dumping the result in a file.</para>
636
637
638
639
640
641
642
643
644
645

      <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>
646
647
648
	    <term><option>-x</option> <replaceable>suffix</replaceable>
	    	      <indexterm><primary><option>-x</option></primary>
	      </indexterm></term>
649
650
651
652
653
654
655
656
657
658
659
	      <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>

660
661
662
    </sect2>
  </sect1>

663
664
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
665

666
667
    <indexterm><primary>help options</primary></indexterm>
    <indexterm><primary>verbosity options</primary></indexterm>
668

669
670
    <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
    and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
671
    <variablelist>
672
673
674
675
676
677
678
679
680
681
682
683
      <varlistentry>
	<term>
          <option>-n</option>
          <indexterm><primary><option>-n</option></primary></indexterm>
        </term>
	<listitem>
	  <para>Does a dry-run, i.e. GHC goes through all the motions
          of compiling as normal, but does not actually run any
          external commands.</para>
	</listitem>
      </varlistentry>

684
      <varlistentry>
685
686
687
688
	<term>
          <option>-v</option>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
689
690
	<listitem>
	  <para>The <option>-v</option> option makes GHC
691
          <emphasis>verbose</emphasis>: it reports its version number
692
693
694
695
696
697
698
699
700
701
702
703
704
          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>
705
706
707
708
	<term>
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
709
710
711
712
713
714
715
716
717
	<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>
718
	      <term><option>-v0</option></term>
719
720
721
722
723
724
725
	      <listitem>
		<para>Disable all non-essential messages (this is the
		default).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
726
	      <term><option>-v1</option></term>
727
728
729
	      <listitem>
		<para>Minimal verbosity: print one line per
		compilation (this is the default when
730
731
		<option>&ndash;&ndash;make</option> or
		<option>&ndash;&ndash;interactive</option> is on).</para>
732
733
734
735
	      </listitem>
	    </varlistentry>

	    <varlistentry>
736
	      <term><option>-v2</option></term>
737
738
739
740
741
742
743
744
	      <listitem>
		<para>Print the name of each compilation phase as it
		is executed. (equivalent to
		<option>-dshow-passes</option>).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
745
	      <term><option>-v3</option></term>
746
747
748
749
750
751
752
753
	      <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>
754
	      <term><option>-v4</option></term>
755
756
757
758
759
760
761
762
763
764
765
	      <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>
      
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
      <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>
799

800
801
802
803
804
805
806
807
808
809
810
811
812
813
      <varlistentry>
        <term><option>-H</option><replaceable>size</replaceable>
        <indexterm><primary><option>-H</option></primary></indexterm>
        </term>
        <listitem>
          <para>Set the minimum size of the heap to
          <replaceable>size</replaceable>.
          This option is equivalent to
          <literal>+RTS&nbsp;-H<replaceable>size</replaceable></literal>,
          see <xref linkend="rts-options-gc" />.
          </para>
        </listitem>
      </varlistentry>

814
815
816
817
818
819
820
821
822
823
824
825
      <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>
826
827
828
    </variablelist>
  </sect1>

829
  &separate;
rrt's avatar
rrt committed
830

831
832
833
834
835
836
837
838
839
840
841
842
  <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:
843
    <option>-fwarn-overlapping-patterns</option>,
844
845
846
847
848
849
850
    <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>

851
    <variablelist>
852
853
854
855

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
856
	  <indexterm><primary>-W option</primary></indexterm>
857
858
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
859
	  <option>-fwarn-dodgy-imports</option>,
860
	  <option>-fwarn-unused-matches</option>,
Ian Lynagh's avatar
Ian Lynagh committed
861
	  <option>-fwarn-unused-imports</option>, and
862
863
864
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
865

866
867
868
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
869
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
870
871
872
	  <para>Turns on all warning options that indicate potentially
	  suspicious code.  The warnings that are
	  <emphasis>not</emphasis> enabled by <option>-Wall</option>
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
	  are
            <option>-fwarn-simple-patterns</option>,
            <option>-fwarn-tabs</option>,
            <option>-fwarn-incomplete-record-updates</option>,
            <option>-fwarn-monomorphism-restriction</option>, and
            <option>-fwarn-implicit-prelude</option>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-w</option>:</term>
	<listitem>
	  <indexterm><primary><option>-w</option></primary></indexterm>
	  <para>Turns off all warnings, including the standard ones and
      those that <literal>-Wall</literal> doesn't enable.</para>
888
889
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
890

891
892
893
894
895
896
897
898
899
      <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>

900
    </variablelist>
rrt's avatar
rrt committed
901

902
903
904
    <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
905

906
    <variablelist>
rrt's avatar
rrt committed
907

908
909
910
911
912
913
914
915
916
      <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
917
	  linkend="deprecated-pragma"/>.</para>
918
919
920
921
922
923
924
925
926
927
928
929
930
931

	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-dodgy-imports</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
	  </indexterm>
	  <para>Causes a warning to be emitted when a a datatype
      <literal>T</literal> is imported
      with all constructors, i.e. <literal>T(..)</literal>, but has been
      exported abstractly, i.e. <literal>T</literal>.</para>
932
933
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
934

935
936
937
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
938
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
939
940
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
941

942
943
944
945
946
	  <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
947

948
949
950
951
952
953
954
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
955
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
956
957
958
959
960
961
962
963
964
965
	  <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>

966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
      <varlistentry>
        <term><option>-fwarn-implicit-prelude</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
          <indexterm><primary>implicit prelude, warning</primary></indexterm>
          <para>Have the compiler warn if the Prelude is implicitly
          imported.  This happens unless either the Prelude module is
          explicitly imported with an <literal>import ... Prelude ...</literal>
          line, or this implicit import is disabled (either by
          <option>-fno-implicit-prelude</option> or a
          <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>

          <para>Note that no warning is given for syntax that implicitly
          refers to the Prelude, even if <option>-fno-implicit-prelude</option>
          would change whether it refers to the Prelude.
          For example, no warning is given when
          <literal>368</literal> means
          <literal>Prelude.fromInteger (368::Prelude.Integer)</literal>
          (where <literal>Prelude</literal> refers to the actual Prelude module,
          regardless of the imports of the module being compiled).</para>

          <para>This warning is off by default.</para>
        </listitem>
      </varlistentry>

991
992
993
      <varlistentry>
	<term><option>-fwarn-incomplete-patterns</option>:</term>
	<listitem>
994
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
	  <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>

1008
	  <para>This option isn't enabled by default because it can be
1009
1010
1011
1012
1013
1014
          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>

1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
      <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>

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

1042
      <varlistentry>
1043
1044
	<term>
          <option>-fwarn-missing-fields</option>:
1045
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
1046
1047
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>
1048
1049
        </term>
	<listitem>
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061

	  <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>
1062
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
1063
1064
1065
1066
1067
1068
1069
	  <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>
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
	  <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>
1082
1083
1084
1085
1086
1087
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
1088
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
1089
1090
1091
1092
	  <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
1093
1094
          <option>-fwarn-missing-signatures</option> option.  As part of
	    the warning GHC also reports the inferred type.  The
1095
1096
1097
1098
1099
1100
1101
          option is off by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-name-shadowing</option>:</term>
	<listitem>
1102
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
1103
1104
1105
1106
1107
1108
	  <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.,
1109
1110
          in the inadvertent capture of what would be a recursive call in
          <literal>f = ... let f = id in ... f ...</literal>.</para>
1111
1112
1113
	</listitem>
      </varlistentry>

1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
      <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>

1135
      <varlistentry>
1136
1137
1138
1139
1140
1141
	<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>
1142
1143
	<listitem>
	  <para>By default, the compiler will warn you if a set of
1144
          patterns are overlapping, e.g.,</para>
1145
1146

<programlisting>
rrt's avatar
rrt committed
1147
1148
1149
1150
f :: String -&#62; Int
f []     = 0
f (_:xs) = 1
f "2"    = 2
1151
</programlisting>
rrt's avatar
rrt committed
1152

1153
	  <para>where the last pattern match in <function>f</function>
1154
1155
1156
1157
1158
          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
1159

1160
1161
1162
1163
1164
1165
1166
1167
1168
      <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>
1169
	  <para>&ldquo;Lambda-bound patterns&rdquo; includes all places where there is a single pattern,
1170
1171
1172
1173
1174
	    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]
1175
	      f xs = [y | Just y &lt;- xs]
1176
1177
1178
	      </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>
1179
1180
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1181

1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
      <varlistentry>
	<term><option>-fwarn-tabs</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-tabs</option></primary></indexterm>
	  <indexterm><primary>tabs, warning</primary></indexterm>
	  <para>Have the compiler warn if there are tabs in your source
          file.</para>

	  <para>This warning is off by default.</para>
	</listitem>
      </varlistentry>

1194
1195
1196
      <varlistentry>
	<term><option>-fwarn-type-defaults</option>:</term>
	<listitem>
1197
	  <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
1198
1199
1200
1201
1202
	  <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,
1203
          e.g., the &lsquo;default default&rsquo; for Haskell 1.4 caused the
1204
          otherwise unconstrained value <constant>1</constant> to be
1205
1206
1207
1208
1209
1210
1211
1212
          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
1213

1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
      <varlistentry>
	<term><option>-fwarn-monomorphism-restriction</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm>
	  <indexterm><primary>monomorphism restriction, warning</primary></indexterm>
	  <para>Have the compiler warn/inform you where in your source
          the Haskell Monomorphism Restriction is applied.  If applied silently
	  the MR can give rise to unexpected behaviour, so it can be helpful
	  to have an explicit warning that it is being applied.</para>

1224
	  <para>This warning is off by default.</para>
1225
1226
1227
	</listitem>
      </varlistentry>

1228
1229
1230
      <varlistentry>
	<term><option>-fwarn-unused-binds</option>:</term>
	<listitem>
1231
	  <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
1232
1233
1234
1235
1236
	  <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>
1237
1238
1239
1240
1241
1242
1243
	  <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>
1244
1245
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1246

1247
1248
1249
      <varlistentry>
	<term><option>-fwarn-unused-imports</option>:</term>
	<listitem>
1250
	  <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
1251
1252
	  <indexterm><primary>unused imports, warning</primary></indexterm>
	  <indexterm><primary>imports, unused</primary></indexterm>
rrt's avatar
rrt committed
1253

1254
1255
1256
1257
	  <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>
1258
1259
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1260

1261
1262
1263
      <varlistentry>
	<term><option>-fwarn-unused-matches</option>:</term>
	<listitem>
1264
	  <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
1265
1266
1267
1268
1269
1270
	  <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
1271
          <varname>x</varname> and <varname>y</varname> as unused.  The
1272
1273
1274
1275
1276
          warning is suppressed if the variable name begins with an underscore, thus:
	    <programlisting>
	       f _x = True
	    </programlisting>
          </para>
1277
1278
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1279

1280
    </variablelist>
rrt's avatar
rrt committed
1281

1282
    <para>If you're feeling really paranoid, the
1283
1284
1285
1286
1287
    <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
1288

1289
  </sect1>
rrt's avatar
rrt committed
1290

1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
  &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>

1317
1318
1319
      <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
Simon Marlow's avatar
typo    
Simon Marlow committed
1320
      you change something.  This is one reason to stick to
1321
      no-optimisation when developing code.</para>
rrt's avatar
rrt committed
1322

1323
      <variablelist>
rrt's avatar
rrt committed
1324

1325
	<varlistentry>
1326
1327
1328
1329
	  <term>
            No <option>-O*</option>-type option specified:
            <indexterm><primary>-O* not specified</primary></indexterm>
          </term>
1330
1331
1332
1333
1334
1335
1336
	  <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
1337

1338
	<varlistentry>
1339
1340
1341
1342
	  <term>
            <option>-O0</option>:
            <indexterm><primary><option>-O0</option></primary></indexterm>
          </term>
1343
1344
1345
1346
1347
1348
1349
1350
1351
	  <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
1352

1353
	<varlistentry>
1354
1355
1356
1357
1358
1359
	  <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>
1360
1361
1362
1363
1364
1365
	  <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
1366

1367
	<varlistentry>
1368
1369
1370
1371
1372
	  <term>
            <option>-O2</option>:
            <indexterm><primary>-O2 option</primary></indexterm>
            <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
          </term>
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
	  <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>
1388

1389
	<varlistentry>
1390
1391
1392
1393
1394
	  <term>
            <option>-Ofile &lt;file&gt;</option>:
            <indexterm><primary>-Ofile &lt;file&gt; option</primary></indexterm>
            <indexterm><primary>optimising, customised</primary></indexterm>
          </term>
1395
	  <listitem>
1396
	    <para>(NOTE: not supported since GHC 4.x.  Please ask if
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
	    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>
1414

1415
1416
1417
      <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
1418
      broke, we tend to use <option>-O2 -fvia-C</option> (and we go for
1419
      lots of coffee breaks).</para>
rrt's avatar
rrt committed
1420

1421
1422
1423
1424
      <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
1425

1426
1427
    <sect2 id="options-f">
      <title><option>-f*</option>: platform-independent flags</title>
rrt's avatar
rrt committed
1428

1429
1430
      <indexterm><primary>-f* options (GHC)</primary></indexterm>
      <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
rrt's avatar
rrt committed
1431

1432
1433
1434
1435
1436
1437
      <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
1438

1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
      <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
1453

1454
1455
1456
1457
1458
1459
1460
1461
	<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
1462
	    linkend="assertions"/>).  This flag is turned on by
1463
1464
1465
1466
1467
	    <option>-O</option>.
	    </para>
	  </listitem>
	</varlistentry>

1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
	<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>

1480
	<varlistentry>
1481
1482
1483
1484
	  <term>
            <option>-fno-strictness</option>
            <indexterm><primary><option>-fno-strictness</option></primary></indexterm>
          </term>
1485
1486
1487
1488
1489
	  <listitem>
	    <para>Turns off the strictness analyser; sometimes it eats
	    too many cycles.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1490

1491
	<varlistentry>
1492
	  <term>
1493
1494
1495
1496
1497
1498
1499
            <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>
Simon Marlow's avatar
Simon Marlow committed
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509

            <para>NOTE: GHC doesn't implement complete full-laziness.
            When optimisation in on, and
            <option>-fno-full-laziness</option> is not given, some
            transformations that increase sharing are performed, such
            as extracting repeated computations from a loop.  These
            are the same transformations that a fully lazy
            implementation would do, the difference is that GHC
            doesn't consistently apply full-laziness, so don't rely on
            it.</para>
1510
1511
1512
1513
1514
1515
1516
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <option>-fno-state-hack</option>
            <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
1517
          </term>
1518
	  <listitem>
1519
1520
1521
1522
1523
	    <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> 
1524
1525
	  </listitem>
	</varlistentry>
1526

1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
	<varlistentry>
	  <term>
            <option>-fno-state-hack</option>
            <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
          </term>
	  <listitem>
	    <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> 
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <option>-fomit-interface-pragmas</option>
	    <indexterm><primary><option>-fomit-interface-pragmas</option></primary></indexterm>
          </term>
	  <listitem>
	    <para>Tells GHC to omit all inessential information from the interface file
	      generated for the module being compiled (say M).  This means that a module
	      importing M will see only the <emphasis>types</emphasis> of the functions that M exports, but not
	      their unfoldings, strictness info, etc.  Hence, for example,
	      no function exported by M will be inlined
	      into an importing module.  The benefit is that modules that import M will
	      need to be recompiled less often (only when M's exports change their type,
	      not when they change their implementation).
	      </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <option>-fignore-interface-pragmas</option>
	    <indexterm><primary><option>-fignore-interface-pragmas</option></primary></indexterm>
          </term>
	  <listitem>