using.xml 69.7 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
157
158
159
	<term>
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	</term>
160
161
162
163
	<listitem>
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
164

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
      <varlistentry>
	<term><filename>.hs</filename></term>
	<listitem>
	  <para>A not-so-literate Haskell module.</para>
	</listitem>
      </varlistentry>

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

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

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

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

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

  </sect1>
rrt's avatar
rrt committed
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
372
	  <para>You don't have to write a<literal>Makefile</literal>.</para>
          <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
    </variablelist>
  </sect1>

752
  &separate;
rrt's avatar
rrt committed
753

754
755
756
757
758
759
760
761
762
763
764
765
  <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:
766
    <option>-fwarn-overlapping-patterns</option>,
767
768
769
770
771
772
773
    <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>

774
    <variablelist>
775
776
777
778

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
779
	  <indexterm><primary>-W option</primary></indexterm>
780
781
782
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
	  <option>-fwarn-unused-matches</option>,
783
784
	  <option>-fwarn-unused-imports</option>,
	  <option>-fwarn-misc</option>, and
785
786
787
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
788

789
790
791
      <varlistentry>
	<term><option>-w</option>:</term>
	<listitem>
792
	  <indexterm><primary><option>-w</option></primary></indexterm>
793
794
795
	  <para>Turns off all warnings, including the standard ones.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
796

797
798
799
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
800
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
801
802
803
	  <para>Turns on all warning options.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
804

805
806
807
808
809
810
811
812
813
      <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>

814
    </variablelist>
rrt's avatar
rrt committed
815

816
817
818
    <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
819

820
    <variablelist>
rrt's avatar
rrt committed
821

822
823
824
825
826
827
828
829
830
      <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
831
	  linkend="deprecated-pragma"/>.</para>
832
833
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
834

835
836
837
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
838
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
839
840
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
841

842
843
844
845
846
	  <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
847

848
849
850
851
852
853
854
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
855
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
856
857
858
859
860
861
862
863
864
865
866
867
868
	  <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>
869
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
	  <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>

890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
      <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>

917
      <varlistentry>
918
919
920
921
	<term>
          <option>-fwarn-misc</option>:
          <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
        </term>
922
923
924
925
926
927
928
929
	<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>

930
      <varlistentry>
931
932
	<term>
          <option>-fwarn-missing-fields</option>:
933
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
934
935
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>
936
937
        </term>
	<listitem>
938
939
940
941
942
943
944
945
946
947
948
949

	  <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>
950
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
951
952
953
954
955
956
957
	  <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>
958
959
960
961
962
963
964
965
966
967
968
969
	  <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>
970
971
972
973
974
975
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
976
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
977
978
979
980
981
982
983
984
985
986
987
988
	  <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>
989
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
990
991
992
993
994
995
996
997
998
999
1000
	  <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
For faster browsing, not all history is shown. View entire blame