using.xml 67.1 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
99
100
101
102
103
104
105
106
107
      for more details.</para>
    </sect2>
  </sect1>
    
  <sect1 id="static-dynamic-flags">
    <title>Static vs. Dynamic options</title>
    <indexterm><primary>static</primary><secondary>options</secondary>
    </indexterm>
    <indexterm><primary>dynamic</primary><secondary>options</secondary>
    </indexterm>

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

112
113
    <para>As a rule of thumb, options which relate to filenames are
    static, and the rest are dynamic. The flag reference tables (<xref
114
    linkend="flag-reference"/>) lists the status of each flag.</para>
115
  </sect1>
rrt's avatar
rrt committed
116

117
118
  <sect1 id="file-suffixes">
    <title>Meaningful file suffixes</title>
rrt's avatar
rrt committed
119

120
121
    <indexterm><primary>suffixes, file</primary></indexterm>
    <indexterm><primary>file suffixes for GHC</primary></indexterm>
rrt's avatar
rrt committed
122

123
124
125
    <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
126

127
    <variablelist>
rrt's avatar
rrt committed
128

129
      <varlistentry>
130
131
132
133
	<term>
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	</term>
134
135
136
137
	<listitem>
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
138

139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
      <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
190

191
192
193
194
195
196
197
198
199
200
  <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>
201
202
	<term>
	  <cmdsynopsis><command>ghc</command>
203
	    <arg choice='plain'>&ndash;&ndash;interactive</arg>
204
205
206
207
	  </cmdsynopsis>
          <indexterm><primary>interactive mode</primary></indexterm>
          <indexterm><primary>ghci</primary></indexterm>
	</term>
208
209
210
	<listitem>
	  <para>Interactive mode, which is also available as
	  <command>ghci</command>.  Interactive mode is described in
211
	  more detail in <xref linkend="ghci"/>.</para>
212
213
214
215
	</listitem>
      </varlistentry>
      
      <varlistentry>
216
217
	<term>
	  <cmdsynopsis><command>ghc</command>
218
	    <arg choice='plain'>&ndash;&ndash;make</arg>
219
220
221
222
	  </cmdsynopsis>
          <indexterm><primary>make mode</primary></indexterm>
          <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
	</term>
223
224
225
226
227
228
	<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
229
	  linkend="make-mode"/>.</para>
230
231
232
233
	</listitem>
      </varlistentry>

      <varlistentry>
234
235
	<term>
	  <cmdsynopsis><command>ghc</command>
236
	    <arg choice='plain'>&ndash;e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
237
238
239
          </cmdsynopsis>
          <indexterm><primary>eval mode</primary></indexterm>
	</term>
240
241
242
243
	<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
244
	  on the command line.  See <xref linkend="eval-mode"/> for
245
246
247
248
249
	  more details.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
250
251
	<term>
          <cmdsynopsis>
252
253
254
255
256
257
258
	    <command>ghc</command>
	    <group>
	      <arg>-E</arg>
	      <arg>-C</arg>
	      <arg>-S</arg>
	      <arg>-c</arg>
	    </group>
259
260
261
262
263
264
	  </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>
265
266
267
268
269
270
271
	<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
272
	  linkend="options-order"/>.</para>
273
274
275
276
	</listitem>
      </varlistentry>

      <varlistentry>
277
278
279
280
281
282
283
	<term>
          <cmdsynopsis>
            <command>ghc</command>
	    <arg choice='plain'>&ndash;M</arg>
          </cmdsynopsis>
          <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
284
285
286
287
	<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
288
	  linkend="sec-makefile-dependencies"/>.</para>
289
290
291
292
	</listitem>
      </varlistentry>

      <varlistentry>
293
294
295
296
297
298
299
	<term>
          <cmdsynopsis>
            <command>ghc</command>
	    <arg choice='plain'>&ndash;&ndash;mk-dll</arg>
          </cmdsynopsis>
	  <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
300
301
	<listitem>
	  <para>DLL-creation mode (Windows only).  See <xref
302
	  linkend="win32-dlls-create"/>.</para>
303
304
305
306
307
308
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2 id="make-mode">
      <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
309
310
      <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
      <indexterm><primary>separate compilation</primary></indexterm>
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
      
      <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
339
	  Compiling a multi-module program with <literal>ghc
340
341
342
343
344
	  &ndash;&ndash;make</literal> can be up to twice as fast as
	  running <literal>ghc</literal> individually on each source
	  file.</para>
	</listitem>
	<listitem>
345
346
	  <para>You don't have to write a<literal>Makefile</literal>.</para>
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
347
348
349
350
351
352
353
354
355
356
357
358
359
	</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
360
      file only, you'll need to use an <literal>OPTIONS_GHC</literal>
361
      pragma (see <xref linkend="source-file-options"/>).</para>
362
363

      <para>If the program needs to be linked with additional objects
ross's avatar
ross committed
364
      (say, some auxiliary C code), then the object files can be
365
366
367
368
369
370
371
372
373
374
375
376
377
      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
378
      linkend="search-path"/>).</para>
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
    </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>
      
418
      <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
419
420
421
422
423
424
425
426
427
      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">
428
429
430
431
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
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
	  
	  <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
506
      linkend="options-codegen"/> for more details.</para>
507
508
509

      <para>Note: C pre-processing is optional, the
      <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
510
      flag turns it on.  See <xref linkend="c-pre-processor"/> for more
511
512
      details.</para>
      
513
514
      <para>Note: The option <option>-E</option><indexterm><primary>-E
      option</primary></indexterm> runs just the pre-processing passes
515
516
517
518
519
520
      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>
    </sect2>
  </sect1>

521
522
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
523

524
525
    <indexterm><primary>help options</primary></indexterm>
    <indexterm><primary>verbosity options</primary></indexterm>
526
527
528

    <variablelist>
      <varlistentry>
529
530
531
532
533
534
535
536
	<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>
537
538
539
540
541
	<listitem>
	  <para>Cause GHC to spew a long usage message to standard
          output and then exit.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
542

543
      <varlistentry>
544
545
546
547
	<term>
          <option>-v</option>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
548
549
	<listitem>
	  <para>The <option>-v</option> option makes GHC
550
          <emphasis>verbose</emphasis>: it reports its version number
551
552
553
554
555
556
557
558
559
560
561
562
563
          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>
564
565
566
567
	<term>
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
568
569
570
571
572
573
574
575
576
	<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>
577
	      <term><option>-v0</option></term>
578
579
580
581
582
583
584
	      <listitem>
		<para>Disable all non-essential messages (this is the
		default).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
585
	      <term><option>-v1</option></term>
586
587
588
	      <listitem>
		<para>Minimal verbosity: print one line per
		compilation (this is the default when
589
590
		<option>&ndash;&ndash;make</option> or
		<option>&ndash;&ndash;interactive</option> is on).</para>
591
592
593
594
	      </listitem>
	    </varlistentry>

	    <varlistentry>
595
	      <term><option>-v2</option></term>
596
597
598
599
600
601
602
603
	      <listitem>
		<para>Print the name of each compilation phase as it
		is executed. (equivalent to
		<option>-dshow-passes</option>).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
604
	      <term><option>-v3</option></term>
605
606
607
608
609
610
611
612
	      <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>
613
	      <term><option>-v4</option></term>
614
615
616
617
618
619
620
621
622
623
624
625
	      <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>
626
627
628
629
630
631
632
633
	<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>
634
635
636
637
	<listitem>
	  <para>Print a one-line string including GHC's version number.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
638

639
      <varlistentry>
640
641
642
643
	<term>
          <option>&ndash;&ndash;numeric-version</option>
          <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
        </term>
644
645
646
647
	<listitem>
	  <para>Print GHC's numeric version number only.</para>
	</listitem>
      </varlistentry>
648
649

      <varlistentry>
650
651
652
653
	<term>
          <option>&ndash;&ndash;print-libdir</option>
          <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
        </term>
654
655
656
657
	<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
658
	  <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
659
660
661
	  is the value of
	  <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
	  </indexterm>in the package configuration file (see <xref
662
	  linkend="packages"/>).</para>
663
664
665
	</listitem>
      </varlistentry>

666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
      <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>
699
700
701
    </variablelist>
  </sect1>

702
  &separate;
rrt's avatar
rrt committed
703

704
705
706
707
708
709
710
711
712
713
714
715
  <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:
716
    <option>-fwarn-overlapping-patterns</option>,
717
718
719
720
721
722
723
    <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>

724
    <variablelist>
725
726
727
728

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
729
	  <indexterm><primary>-W option</primary></indexterm>
730
731
732
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
	  <option>-fwarn-unused-matches</option>,
733
734
	  <option>-fwarn-unused-imports</option>,
	  <option>-fwarn-misc</option>, and
735
736
737
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
738

739
740
741
      <varlistentry>
	<term><option>-w</option>:</term>
	<listitem>
742
	  <indexterm><primary><option>-w</option></primary></indexterm>
743
744
745
	  <para>Turns off all warnings, including the standard ones.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
746

747
748
749
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
750
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
751
752
753
	  <para>Turns on all warning options.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
754

755
756
757
758
759
760
761
762
763
      <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>

764
    </variablelist>
rrt's avatar
rrt committed
765

766
767
768
    <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
769

770
    <variablelist>
rrt's avatar
rrt committed
771

772
773
774
775
776
777
778
779
780
      <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
781
	  linkend="deprecated-pragma"/>.</para>
782
783
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
784

785
786
787
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
788
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
789
790
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
791

792
793
794
795
796
	  <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
797

798
799
800
801
802
803
804
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
805
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
806
807
808
809
810
811
812
813
814
815
816
817
818
	  <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>
819
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
	  <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>

840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
      <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>

867
      <varlistentry>
868
869
870
871
	<term>
          <option>-fwarn-misc</option>:
          <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
        </term>
872
873
874
875
876
877
878
879
	<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>

880
      <varlistentry>
881
882
	<term>
          <option>-fwarn-missing-fields</option>:
883
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
884
885
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>
886
887
        </term>
	<listitem>
888
889
890
891
892
893
894
895
896
897
898
899

	  <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>
900
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
901
902
903
904
905
906
907
	  <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>
908
909
910
911
912
913
914
915
916
917
918
919
	  <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>
920
921
922
923
924
925
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
926
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
927
928
929
930
931
932
933
934
935
936
937
938
	  <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>
939
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
	  <indexterm><primary>shadowing, warning</primary></indexterm>
	  
	  <para>This option causes a warning to be emitted whenever an
          inner-scope value has the same name as an outer-scope value,
          i.e. the inner value shadows the outer one.  This can catch
          typographical errors that turn into hard-to-find bugs, e.g.,
          in the inadvertent cyclic definition <literal>let x = ... x
          ... in</literal>.</para>

	  <para>Consequently, this option does
          <emphasis>will</emphasis> complain about cyclic recursive
          definitions.</para>
	</listitem>
      </varlistentry>

955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
      <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>

976
      <varlistentry>
977
978
979
980
981
982
	<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>
983
984
985
986
987
	<listitem>
	  <para>By default, the compiler will warn you if a set of
          patterns are overlapping, i.e.,</para>

<programlisting>
rrt's avatar
rrt committed
988
989
990
991
f :: String -&#62; Int
f []     = 0
f (_:xs) = 1
f "2"    = 2
992
</programlisting>
rrt's avatar
rrt committed
993

994
	  <para>where the last pattern match in <function>f</function>
995
996
997
998
999
          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
1000