using.xml 87.6 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
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
  <sect1>
    <title>Getting started: compiling programs</title>

    <para>
      In this chapter you'll find a complete reference to the GHC
      command-line syntax, including all 400+ flags.  It's a large and
      complex system, and there are lots of details, so it can be
      quite hard to figure out how to get started.  With that in mind,
      this introductory section provides a quick introduction to the
      basic usage of GHC for compiling a Haskell program, before the
      following sections dive into the full syntax.
    </para>

    <para>
      Let's create a Hello World program, and compile and run it.
      First, create a file <filename>hello.hs</filename> containing
      the Haskell code:
    </para>

<programlisting>
main = putStrLn "Hello, World!"
</programlisting>

    <para>To compile the program, use GHC like this:</para>

<screen>
$ ghc hello.hs</screen>

     <para>(where <literal>$</literal> represents the prompt: don't
       type it).  GHC will compile the source
       file <filename>hello.hs</filename>, producing
       an <firstterm>object
       file</firstterm> <filename>hello.o</filename> and
       an <firstterm>interface
       file</firstterm> <filename>hello.hi</filename>, and then it
       will link the object file to the libraries that come with GHC
       to produce an executable called <filename>hello</filename> on
       Unix/Linux/Mac, or <filename>hello.exe</filename> on
       Windows.</para>

    <para>
      By default GHC will be very quiet about what it is doing, only
      printing error messages.  If you want to see in more detail
      what's going on behind the scenes, add <option>-v</option> to
      the command line.
    </para>

    <para>
      Then we can run the program like this:
    </para>

<screen>
$ ./hello
Hello World!</screen>

    <para>
      If your program contains multiple modules, then you only need to
      tell GHC the name of the source file containing
      the <filename>Main</filename> module, and GHC will examine
      the <literal>import</literal> declarations to find the other
      modules that make up the program and find their source files.
      This means that, with the exception of
      the <literal>Main</literal> module, every source file should be
      named after the module name that it contains (with dots replaced
      by directory separators).  For example, the
      module <literal>Data.Person</literal> would be in the
      file <filename>Data/Person.hs</filename> on Unix/Linux/Mac,
      or <filename>Data\Person.hs</filename> on Windows.
    </para>
  </sect1>

79
80
  <sect1>
    <title>Options overview</title>
daniel.is.fischer's avatar
daniel.is.fischer committed
81

82
83
84
85
86
87
    <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
88
      <title>Command-line arguments</title>
daniel.is.fischer's avatar
daniel.is.fischer committed
89

90
91
92
      <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
93

94
      <para>An invocation of GHC takes the following form:</para>
rrt's avatar
rrt committed
95

96
<screen>
rrt's avatar
rrt committed
97
ghc [argument...]
98
</screen>
rrt's avatar
rrt committed
99

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

Ian Lynagh's avatar
Ian Lynagh committed
102
      <para>Command-line options begin with <literal>-</literal>.
103
104
105
106
107
108
109
110
111
      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
112

113
    <sect2 id="source-file-options">
Ian Lynagh's avatar
Ian Lynagh committed
114
      <title>Command line options in source files</title>
daniel.is.fischer's avatar
daniel.is.fischer committed
115

116
117
118
119
      <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
120
121
122
      tight. For instance, if a Haskell source file deliberately
	uses name shadowing, it should be compiled with  the
      <option>-fno-warn-name-shadowing</option> option.  Rather than maintaining
123
124
      the list of per-file options in a <filename>Makefile</filename>,
      it is possible to do this directly in the source file using the
125
      <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
126
      pragma</primary></indexterm>:</para>
rrt's avatar
rrt committed
127

128
<programlisting>
129
{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
130
131
module X where
...
132
</programlisting>
daniel.is.fischer's avatar
daniel.is.fischer committed
133

134
135
136
137
138
      <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
      (see <xref linkend="pragmas"/>).</para>

      <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
      (see <xref linkend="static-dynamic-flags"/>).</para>
139
140

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

146
147
148
      <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>
149
150
151

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

158
159
    <sect2>
      <title>Setting options in GHCi</title>
rrt's avatar
rrt committed
160

161
      <para>Options may also be modified from within GHCi, using the
162
      <literal>:set</literal> command.  See <xref linkend="ghci-set"/>
163
164
165
      for more details.</para>
    </sect2>
  </sect1>
daniel.is.fischer's avatar
daniel.is.fischer committed
166

167
  <sect1 id="static-dynamic-flags">
168
    <title>Static, Dynamic, and Mode options</title>
169
170
171
172
    <indexterm><primary>static</primary><secondary>options</secondary>
    </indexterm>
    <indexterm><primary>dynamic</primary><secondary>options</secondary>
    </indexterm>
173
174
    <indexterm><primary>mode</primary><secondary>options</secondary>
    </indexterm>
175

Ian Lynagh's avatar
Ian Lynagh committed
176
177
    <para>Each of GHC's command line options is classified as
    <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
178
179
180
181
182
183
      <firstterm>mode</firstterm>:</para>

    <variablelist>
      <varlistentry>
	<term>Mode flags</term>
	<listitem>
184
	  <para>For example, <option>&ndash;&ndash;make</option> or <option>-E</option>.
Ian Lynagh's avatar
Ian Lynagh committed
185
	    There may only be a single mode flag on the command line.  The
186
	    available modes are listed in <xref linkend="modes"/>.</para>
187
188
189
190
191
192
193
	</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
Simon Marlow's avatar
Simon Marlow committed
194
	    <literal>OPTIONS_GHC</literal> pragma in a source file, or set
195
196
197
198
199
200
201
202
203
204
205
206
	    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>
daniel.is.fischer's avatar
daniel.is.fischer committed
207

208
    <para>The flag reference tables (<xref
209
    linkend="flag-reference"/>) lists the status of each flag.</para>
210
211
212
213

    <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
daniel.is.fischer's avatar
daniel.is.fischer committed
214
    table.</para>
215
  </sect1>
rrt's avatar
rrt committed
216

217
218
  <sect1 id="file-suffixes">
    <title>Meaningful file suffixes</title>
rrt's avatar
rrt committed
219

220
221
    <indexterm><primary>suffixes, file</primary></indexterm>
    <indexterm><primary>file suffixes for GHC</primary></indexterm>
rrt's avatar
rrt committed
222

223
224
225
    <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
226

227
    <variablelist>
rrt's avatar
rrt committed
228

229
      <varlistentry>
230
	<term><filename>.hs</filename></term>
231
	<listitem>
232
	  <para>A Haskell module.</para>
233
234
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
235

236
      <varlistentry>
237
238
239
240
	<term>
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
	</term>
241
	<listitem>
242
	  <para>A &ldquo;literate Haskell&rdquo; module.</para>
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
	</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>
daniel.is.fischer's avatar
daniel.is.fischer committed
269

270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
      <varlistentry>
	<term><filename>.ll</filename></term>
	<listitem>
	  <para>An llvm-intermediate-language source file, usually
          produced by the compiler.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>.bc</filename></term>
	<listitem>
	  <para>An llvm-intermediate-language bitcode file, usually
          produced by the compiler.</para>
	</listitem>
      </varlistentry>

286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
      <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
306

307
308
309
  <sect1 id="modes">
    <title>Modes of operation</title>

310
311
312
313
314
315
316
317
318
319
320
321
322
323
    <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.
    </para>

    <para>
      If no mode flag is present, then GHC will enter make mode
      (<xref linkend="make-mode" />) if there are any Haskell source
      files given on the command line, or else it will link the
      objects named on the command line to produce an executable.
    </para>

    <para>The available mode flags are:</para>
324
325
326

    <variablelist>
      <varlistentry>
327
	<term>
328
	  <cmdsynopsis><command>ghc --interactive</command>
329
330
331
332
	  </cmdsynopsis>
          <indexterm><primary>interactive mode</primary></indexterm>
          <indexterm><primary>ghci</primary></indexterm>
	</term>
333
334
335
	<listitem>
	  <para>Interactive mode, which is also available as
	  <command>ghci</command>.  Interactive mode is described in
336
	  more detail in <xref linkend="ghci"/>.</para>
337
338
	</listitem>
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
339

340
      <varlistentry>
341
	<term>
342
	  <cmdsynopsis><command>ghc &ndash;&ndash;make</command>
343
344
345
346
	  </cmdsynopsis>
          <indexterm><primary>make mode</primary></indexterm>
          <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
	</term>
347
348
349
350
351
352
	<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
353
	  linkend="make-mode"/>.</para>
354
355
356
357
358
359

          <para>
            This mode is the default if there are any Haskell
            source files mentioned on the command line, and in this case
            the <option>&ndash;&ndash;make</option> option can be omitted.
          </para>
360
361
362
363
	</listitem>
      </varlistentry>

      <varlistentry>
364
	<term>
365
366
	  <cmdsynopsis><command>ghc -e</command>
	     <arg choice='plain'><replaceable>expr</replaceable></arg>
367
368
369
          </cmdsynopsis>
          <indexterm><primary>eval mode</primary></indexterm>
	</term>
370
371
372
373
	<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
374
	  on the command line.  See <xref linkend="eval-mode"/> for
375
376
377
	  more details.</para>
	</listitem>
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
378

379
      <varlistentry>
380
381
	<term>
          <cmdsynopsis>
382
383
384
385
	    <command>ghc -E</command>
	    <command>ghc -c</command>
	    <command>ghc -S</command>
	    <command>ghc -c</command>
386
387
388
389
390
391
	  </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>
392
393
394
395
396
397
398
	<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
399
	  linkend="options-order"/>.</para>
400
401
402
403
	</listitem>
      </varlistentry>

      <varlistentry>
404
405
	<term>
          <cmdsynopsis>
406
            <command>ghc -M</command>
407
408
409
          </cmdsynopsis>
          <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
410
411
412
413
	<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
414
	  linkend="makefile-dependencies"/>.</para>
415
416
417
418
	</listitem>
      </varlistentry>

      <varlistentry>
419
420
	<term>
          <cmdsynopsis>
421
            <command>ghc --mk-dll</command>
422
          </cmdsynopsis>
423
	  <indexterm><primary>DLL-creation mode</primary></indexterm>
424
        </term>
425
426
	<listitem>
	  <para>DLL-creation mode (Windows only).  See <xref
427
	  linkend="win32-dlls-create"/>.</para>
428
429
	</listitem>
      </varlistentry>
430
431
432
433
434
435
436
437
438
439
440
441
442
443

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

444
445
446
447
448
449
450
451
452
453
454
455
456
457
      <varlistentry>
	<term>
          <cmdsynopsis>
            <command>ghc --show-iface <replaceable>file</replaceable></command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;--show-iface</option></primary></indexterm>
        </term>
	<listitem>
	      <para>Read the interface in
	      <replaceable>file</replaceable> and dump it as text to
	      <literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para>
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
458
459
460
      <varlistentry>
	<term>
          <cmdsynopsis>
Ian Lynagh's avatar
Ian Lynagh committed
461
            <command>ghc --supported-extensions</command>
Ian Lynagh's avatar
Ian Lynagh committed
462
463
            <command>ghc --supported-languages</command>
          </cmdsynopsis>
Ian Lynagh's avatar
Ian Lynagh committed
464
          <indexterm><primary><option>&ndash;&ndash;supported-extensions</option></primary><primary><option>&ndash;&ndash;supported-languages</option></primary></indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
465
466
467
468
469
470
        </term>
	<listitem>
	  <para>Print the supported language extensions.</para>
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
471
472
473
474
475
476
477
478
479
480
481
482
      <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>

483
484
485
      <varlistentry>
	<term>
          <cmdsynopsis>
486
487
488
            <command>ghc --version</command>
            <command>ghc -V</command>
          </cmdsynopsis>
489
490
491
492
493
494
495
496
497
498
499
          <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>
500
501
            <command>ghc --numeric-version</command>
          </cmdsynopsis>
502
503
504
505
506
507
508
509
510
511
          <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>
512
513
            <command>ghc --print-libdir</command>
          </cmdsynopsis>
514
515
516
517
518
519
520
521
          <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
522
523
524
	  <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
      in the package configuration file
      (see <xref linkend="packages"/>).</para>
525
526
527
	</listitem>
      </varlistentry>

528
529
530
531
    </variablelist>

    <sect2 id="make-mode">
      <title>Using <command>ghc</command> <option>&ndash;&ndash;make</option></title>
532
533
      <indexterm><primary><option>&ndash;&ndash;make</option></primary></indexterm>
      <indexterm><primary>separate compilation</primary></indexterm>
daniel.is.fischer's avatar
daniel.is.fischer committed
534

535
      <para>In this mode, GHC will build a multi-module Haskell program by following
Ian Lynagh's avatar
Ian Lynagh committed
536
      dependencies from one or more root modules (usually just
537
538
539
540
541
542
543
544
545
      <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>

546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
      <para>
        In fact, GHC enters make mode automatically if there are any
        Haskell source files on the command line and no other mode is
        specified, so in this case we could just type
      </para>

<screen>
ghc Main.hs
</screen>

      <para>Any number of source file names or module names may be
      specified; 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>
562
563
564
565
566
567
568
569
570

      <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
571
	  Compiling a multi-module program with <literal>ghc
572
573
574
575
576
	  &ndash;&ndash;make</literal> can be up to twice as fast as
	  running <literal>ghc</literal> individually on each source
	  file.</para>
	</listitem>
	<listitem>
577
	  <para>You don't have to write a <literal>Makefile</literal>.</para>
578
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
579
580
581
582
583
584
585
	</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>
daniel.is.fischer's avatar
daniel.is.fischer committed
586

587
588
589
590
591
      <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
592
      file only, you'll need to use an <literal>OPTIONS_GHC</literal>
593
      pragma (see <xref linkend="source-file-options"/>).</para>
594
595

      <para>If the program needs to be linked with additional objects
ross's avatar
ross committed
596
      (say, some auxiliary C code), then the object files can be
597
598
      given on the command line and GHC will include them when linking
      the executable.</para>
daniel.is.fischer's avatar
daniel.is.fischer committed
599

600
601
602
603
604
605
606
607
608
609
      <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
610
      linkend="search-path"/>).</para>
611
    </sect2>
daniel.is.fischer's avatar
daniel.is.fischer committed
612

613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
    <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
636

637
638
639
640
641
642
643
644
645
646
647
648
      <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
649

650
      <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
651
      given on the command line.</para>
daniel.is.fischer's avatar
daniel.is.fischer committed
652

653
654
      <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
655
      relevant flag is present, then go all the way through to linking.
656
      This table summarises:</para>
daniel.is.fischer's avatar
daniel.is.fischer committed
657

658
659
      <informaltable>
	<tgroup cols="4">
660
661
662
663
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
	  <colspec align="left"/>
daniel.is.fischer's avatar
daniel.is.fischer committed
664

665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
	  <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
680

681
682
683
684
685
686
687
	    <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
688

689
690
691
692
693
694
	    <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
695

696
697
698
699
700
701
	    <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
702

703
704
705
706
707
708
	    <row>
	      <entry>assembler</entry>
	      <entry><literal>.s</literal></entry>
	      <entry><option>-c</option></entry>
	      <entry><literal>.o</literal></entry>
	    </row>
daniel.is.fischer's avatar
daniel.is.fischer committed
709

710
711
712
713
714
715
716
717
718
	    <row>
	      <entry>linker</entry>
	      <entry><replaceable>other</replaceable></entry>
	      <entry>-</entry>
	      <entry><filename>a.out</filename></entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
daniel.is.fischer's avatar
daniel.is.fischer committed
719

720
721
722
723
      <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
724

725
726
727
728
      <para>Thus, a common invocation would be: </para>

<screen>
ghc -c Foo.hs</screen>
daniel.is.fischer's avatar
daniel.is.fischer committed
729

730
731
732
733
      <para>to compile the Haskell source file
      <filename>Foo.hs</filename> to an object file
      <filename>Foo.o</filename>.</para>

dterei's avatar
dterei committed
734
735
736
      <para>Note: What the Haskell compiler proper produces depends on what
      backend code generator is used. See <xref linkend="code-generators"/>
      for more details.</para>
737
738
739

      <para>Note: C pre-processing is optional, the
      <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
740
      flag turns it on.  See <xref linkend="c-pre-processor"/> for more
741
      details.</para>
daniel.is.fischer's avatar
daniel.is.fischer committed
742

743
744
      <para>Note: The option <option>-E</option><indexterm><primary>-E
      option</primary></indexterm> runs just the pre-processing passes
745
      of the compiler, dumping the result in a file.</para>
746
747
748
749
750

      <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
751
	  depends on its suffix.  This behaviour can be overridden using the
752
753
754
755
	  <option>-x</option> option:</para>

	<variablelist>
	  <varlistentry>
756
757
758
	    <term><option>-x</option> <replaceable>suffix</replaceable>
	    	      <indexterm><primary><option>-x</option></primary>
	      </indexterm></term>
759
760
761
762
763
764
765
766
767
768
769
	      <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>

770
771
772
    </sect2>
  </sect1>

773
774
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
775

776
777
    <indexterm><primary>help options</primary></indexterm>
    <indexterm><primary>verbosity options</primary></indexterm>
778

779
780
    <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>
781
782
    <variablelist>
      <varlistentry>
783
784
785
786
	<term>
          <option>-v</option>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
787
788
	<listitem>
	  <para>The <option>-v</option> option makes GHC
789
          <emphasis>verbose</emphasis>: it reports its version number
790
791
792
793
794
795
796
797
798
799
800
          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>
daniel.is.fischer's avatar
daniel.is.fischer committed
801

802
      <varlistentry>
803
804
805
806
	<term>
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
807
808
809
810
811
812
	<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>
daniel.is.fischer's avatar
daniel.is.fischer committed
813

814
815
	  <variablelist>
	    <varlistentry>
816
	      <term><option>-v0</option></term>
817
818
819
820
821
822
823
	      <listitem>
		<para>Disable all non-essential messages (this is the
		default).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
824
	      <term><option>-v1</option></term>
825
826
827
	      <listitem>
		<para>Minimal verbosity: print one line per
		compilation (this is the default when
828
829
		<option>&ndash;&ndash;make</option> or
		<option>&ndash;&ndash;interactive</option> is on).</para>
830
831
832
833
	      </listitem>
	    </varlistentry>

	    <varlistentry>
834
	      <term><option>-v2</option></term>
835
836
837
838
839
840
841
842
	      <listitem>
		<para>Print the name of each compilation phase as it
		is executed. (equivalent to
		<option>-dshow-passes</option>).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
843
	      <term><option>-v3</option></term>
844
845
846
847
848
849
850
851
	      <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>
852
	      <term><option>-v4</option></term>
853
854
855
856
857
858
859
860
861
862
	      <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
863

864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
      <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>
897

898
899
900
901
902
903
904
905
906
907
908
909
910
911
      <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>

912
913
914
915
916
917
918
919
920
921
922
923
      <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>
924
925
926
    </variablelist>
  </sect1>

927
  &separate;
rrt's avatar
rrt committed
928

929
930
931
932
933
934
935
936
937
938
939
940
  <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:
941
    <option>-fwarn-overlapping-patterns</option>,
Ian Lynagh's avatar
Ian Lynagh committed
942
    <option>-fwarn-warnings-deprecations</option>,
943
    <option>-fwarn-deprecated-flags</option>,
944
    <option>-fwarn-duplicate-exports</option>,
945
    <option>-fwarn-missing-fields</option>,
946
    <option>-fwarn-missing-methods</option>,
947
948
    <option>-fwarn-lazy-unlifted-bindings</option>,
    <option>-fwarn-wrong-do-bind</option>, and
949
950
    <option>-fwarn-dodgy-foreign-imports</option>.  The following
    flags are
951
952
953
    simple ways to select standard &ldquo;packages&rdquo; of warnings:
    </para>

954
    <variablelist>
955
956
957
958

      <varlistentry>
	<term><option>-W</option>:</term>
	<listitem>
959
	  <indexterm><primary>-W option</primary></indexterm>
960
961
	  <para>Provides the standard warnings plus
	  <option>-fwarn-incomplete-patterns</option>,
962
	  <option>-fwarn-dodgy-exports</option>,
963
	  <option>-fwarn-dodgy-imports</option>,
964
	  <option>-fwarn-unused-matches</option>,
Ian Lynagh's avatar
Ian Lynagh committed
965
	  <option>-fwarn-unused-imports</option>, and
966
967
968
	  <option>-fwarn-unused-binds</option>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
969

970
971
972
      <varlistentry>
	<term><option>-Wall</option>:</term>
	<listitem>
973
	  <indexterm><primary><option>-Wall</option></primary></indexterm>
974
975
976
	  <para>Turns on all warning options that indicate potentially
	  suspicious code.  The warnings that are
	  <emphasis>not</emphasis> enabled by <option>-Wall</option>
977
978
	  are
            <option>-fwarn-tabs</option>,
979
            <option>-fwarn-incomplete-uni-patterns</option>,
980
            <option>-fwarn-incomplete-record-updates</option>,
981
            <option>-fwarn-monomorphism-restriction</option>,
982
983
            <option>-fwarn-unrecognised-pragmas</option>,
            <option>-fwarn-auto-orphans</option>,
984
985
986
987
988
989
990
991
992
993
            <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>
994
995
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
996

997
998
999
1000
      <varlistentry>
	<term><option>-Werror</option>:</term>
	<listitem>
	  <indexterm><primary><option>-Werror</option></primary></indexterm>
daniel.is.fischer's avatar
daniel.is.fischer committed
1001
	  <para>Makes any warning into a fatal error. Useful so that you don't
1002
1003
1004
1005
	    miss warnings when doing batch compilation. </para>
	</listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
      <varlistentry>
	<term><option>-Wwarn</option>:</term>
	<listitem>
	  <indexterm><primary><option>-Wwarn</option></primary></indexterm>
	  <para>Warnings are treated only as warnings, not as errors. This is
	    the default, but can be useful to negate a
        <option>-Werror</option> flag.</para>
	</listitem>
      </varlistentry>

1016
    </variablelist>
rrt's avatar
rrt committed
1017

1018
1019
1020
    <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
1021

1022
    <variablelist>
rrt's avatar
rrt committed
1023

1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
      <varlistentry>
	<term><option>-fwarn-unrecognised-pragmas</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-unrecognised-pragmas</option></primary>
	  </indexterm>
	  <indexterm><primary>warnings</primary></indexterm>
	  <indexterm><primary>pragmas</primary></indexterm>
	  <para>Causes a warning to be emitted when a
	  pragma that GHC doesn't recognise is used. As well as pragmas
      that GHC itself uses, GHC also recognises pragmas known to be used
      by other tools, e.g. <literal>OPTIONS_HUGS</literal> and
      <literal>DERIVE</literal>.</para>

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

1041
      <varlistentry>
Ian Lynagh's avatar
Ian Lynagh committed
1042
	<term><option>-fwarn-warnings-deprecations</option>:</term>
1043
	<listitem>
Ian Lynagh's avatar
Ian Lynagh committed
1044
	  <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
1045
	  </indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
1046
	  <indexterm><primary>warnings</primary></indexterm>
1047
	  <indexterm><primary>deprecations</primary></indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
1048
1049
1050
1051
	  <para>Causes a warning to be emitted when a
	  module, function or type with a WARNING or DEPRECATED pragma
      is used. See <xref linkend="warning-deprecated-pragma"/> for more
      details on the pragmas.</para>
1052
1053
1054
1055
1056

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

1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
      <varlistentry>
	<term><option>-fwarn-deprecated-flags</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-deprecated-flags</option></primary>
	  </indexterm>
	  <indexterm><primary>deprecated-flags</primary></indexterm>
	  <para>Causes a warning to be emitted when a deprecated
	  commandline flag is used.</para>

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

1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
      <varlistentry>
	<term><option>-fwarn-dodgy-foreign-imports</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-dodgy-foreign-imports</option></primary>
	  </indexterm>
	  <para>Causes a warning to be emitted for foreign imports of
	  the following form:</para>
<programlisting>
foreign import "f" f :: FunPtr t
</programlisting>
          <para>on the grounds that it probably should be</para>
<programlisting>
foreign import "&amp;f" f :: FunPtr t
</programlisting>
          <para>The first form declares that `f` is a (pure) C
          function that takes no arguments and returns a pointer to a
          C function with type `t`, whereas the second form declares
          that `f` itself is a C function with type `t`.  The first
          declaration is usually a mistake, and one that is hard to
          debug because it results in a crash, hence this
          warning.</para>
	</listitem>
      </varlistentry>

1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
      <varlistentry>
	<term><option>-fwarn-dodgy-exports</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-dodgy-exports</option></primary>
	  </indexterm>
	  <para>Causes a warning to be emitted when a datatype
      <literal>T</literal> is exported
      with all constructors, i.e. <literal>T(..)</literal>, but is it
      just a type synonym.</para>
	  <para>Also causes a warning to be emitted when a module is
      re-exported, but that module exports nothing.</para>
	</listitem>
      </varlistentry>

1108
1109
1110
1111
1112
      <varlistentry>
	<term><option>-fwarn-dodgy-imports</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
	  </indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
1113
	  <para>Causes a warning to be emitted when a datatype
1114
1115
1116
      <literal>T</literal> is imported
      with all constructors, i.e. <literal>T(..)</literal>, but has been
      exported abstractly, i.e. <literal>T</literal>.</para>
1117
1118
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1119

1120
1121
1122
1123
1124
1125
1126
1127
1128
      <varlistentry>
	<term><option>-fwarn-lazy-unlifted-bindings</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary>
	  </indexterm>
	  <para>Causes a warning to be emitted when an unlifted type
      is bound in a way that looks lazy, e.g.
      <literal>where (I# x) = ...</literal>. Use
      <literal>where !(I# x) = ...</literal> instead. This will be an
1129
      error, rather than a warning, in GHC 7.2.
1130
1131
1132
1133
      </para>
	</listitem>
      </varlistentry>

1134
1135
1136
      <varlistentry>
	<term><option>-fwarn-duplicate-exports</option>:</term>
	<listitem>
1137
	  <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
1138
1139
	  <indexterm><primary>duplicate exports, warning</primary></indexterm>
	  <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
1140

1141
1142
1143
1144
1145
	  <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
1146

1147
1148
1149
1150
1151
1152
1153
	  <para>This option is on by default.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-hi-shadowing</option>:</term>
	<listitem>
1154
	  <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
	  <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>

1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
      <varlistentry>
        <term><option>-fwarn-identities</option>:</term>
	<listitem>
          <indexterm><primary><option>-fwarn-identities</option></primary></indexterm>
          <para>Causes the compiler to emit a warning when a Prelude numeric
            conversion converts a type T to the same type T; such calls
            are probably no-ops and can be omitted.  The functions checked for
            are: <literal>toInteger</literal>,
            <literal>toRational</literal>,
            <literal>fromIntegral</literal>,
            and <literal>realToFrac</literal>.
          </para>
	</listitem>
      </varlistentry>

1180
1181
1182
1183
1184
1185
1186
1187
1188
      <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
1189
          <option>-XNoImplicitPrelude</option> or a
1190
1191
1192
          <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>

          <para>Note that no warning is given for syntax that implicitly
1193
          refers to the Prelude, even if <option>-XNoImplicitPrelude</option>
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
          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>

1205
      <varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
1206
	<term><option>-fwarn-incomplete-patterns</option>,
1207
              <option>-fwarn-incomplete-uni-patterns</option>:
daniel.is.fischer's avatar
daniel.is.fischer committed
1208
        </term>
1209
	<listitem>
1210
	  <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
1211
	  <indexterm><primary><option>-fwarn-incomplete-uni-patterns</option></primary></indexterm>
1212
1213
1214
	  <indexterm><primary>incomplete patterns, warning</primary></indexterm>
	  <indexterm><primary>patterns, incomplete</primary></indexterm>

daniel.is.fischer's avatar
daniel.is.fischer committed
1215
          <para>The option <option>-fwarn-incomplete-patterns</option> warns
1216
            about places where
daniel.is.fischer's avatar
daniel.is.fischer committed
1217
	    a pattern-match might fail at runtime.
1218
1219
          The function
          <function>g</function> below will fail when applied to
1220
1221
          non-empty lists, so the compiler will emit a warning about
          this when <option>-fwarn-incomplete-patterns</option> is
1222
          enabled.
1223
1224
1225
<programlisting>
g [] = 2
</programlisting>
1226
	  This option isn't enabled by default because it can be
1227
1228
          a bit noisy, and it doesn't always indicate a bug in the
          program.  However, it's generally considered good practice
daniel.is.fischer's avatar
daniel.is.fischer committed
1229
          to cover all the cases in your functions, and it is switched
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
          on by <option>-W</option>.</para>

          <para>The flag <option>-fwarn-incomplete-uni-patterns</option> is
          similar, except that it
          applies only to lambda-expressions and pattern bindings, constructs
	  that only allow a single pattern:
<programlisting>
h = \[] -> 2
Just k = f y
</programlisting>
          </para>
1241
1242
1243
	</listitem>
      </varlistentry>

1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
      <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>

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

1271
      <varlistentry>
1272
1273
	<term>
          <option>-fwarn-missing-fields</option>:
1274
	  <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
1275
1276
	  <indexterm><primary>missing fields, warning</primary></indexterm>
	  <indexterm><primary>fields, missing</primary></indexterm>
1277
1278
        </term>
	<listitem>
1279
1280
1281
1282
1283
1284
1285
1286
1287

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

1288
1289
1290
1291
1292
1293
1294
1295
1296
      <varlistentry>
	<term>
          <option>-fwarn-missing-import-lists</option>:
	  <indexterm><primary><option>-fwarn-import-lists</option></primary></indexterm>
	  <indexterm><primary>missing import lists, warning</primary></indexterm>
	  <indexterm><primary>import lists, missing</primary></indexterm>
        </term>
	<listitem>

daniel.is.fischer's avatar
daniel.is.fischer committed
1297
	  <para>This flag warns if you use an unqualified
1298
            <literal>import</literal> declaration
daniel.is.fischer's avatar
daniel.is.fischer committed
1299
	    that does not explicitly list the entities brought into scope. For
1300
	    example
Ian Lynagh's avatar
Ian Lynagh committed
1301
      </para>
1302
1303
1304
1305
1306
1307
<programlisting>
module M where
  import X( f )
  import Y
  import qualified Z
  p x = f x x
Ian Lynagh's avatar
Ian Lynagh committed
1308
1309
</programlisting>
        <para>
1310
1311
1312
1313
1314
1315
1316
          The <option>-fwarn-import-lists</option> flag will warn about the import
	  of <literal>Y</literal> but not <literal>X</literal>
	  If module <literal>Y</literal> is later changed to export (say) <literal>f</literal>,
          then the reference to <literal>f</literal> in <literal>M</literal> will become
	  ambiguous.  No warning is produced for the import of <literal>Z</literal>
	  because extending <literal>Z</literal>'s exports would be unlikely to produce
	  ambiguity in <literal>M</literal>.
Ian Lynagh's avatar
Ian Lynagh committed
1317
        </para>
1318
1319
1320
	</listitem>
      </varlistentry>

1321
1322
1323
      <varlistentry>
	<term><option>-fwarn-missing-methods</option>:</term>
	<listitem>
1324
	  <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
1325
1326
1327
1328
1329
1330
1331
	  <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>
1332
1333
1334
1335
1336
1337
1338
1339
	  <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>
daniel.is.fischer's avatar
daniel.is.fischer committed
1340
	    The idea is that: (a) users of the class will only call <literal>complexFn</literal>;
1341
1342
1343
	    never <literal>_simpleFn</literal>; and (b)
	    instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>.
	    </para>
1344
1345
1346
1347
1348
1349
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-signatures</option>:</term>
	<listitem>
1350
	  <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
1351
1352
1353
1354
	  <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
1355
1356
          <option>-fwarn-missing-signatures</option> option.  As part of
	    the warning GHC also reports the inferred type.  The
1357
          option is off by default.</para>
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-missing-local-sigs</option>:</term>
	<listitem>
	  <indexterm><primary><option>-fwarn-missing-local-sigs</option></primary></indexterm>
	  <indexterm><primary>type signatures, missing</primary></indexterm>

	  <para>If you use the
          <option>-fwarn-missing-local-sigs</option> flag GHC will warn
          you about any polymorphic local bindings. As part of
	    the warning GHC also reports the inferred type. The
          option is off by default.</para>
1372
1373
1374
1375
1376
1377
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-fwarn-name-shadowing</option>:</term>
	<listitem>
1378
	  <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
1379
	  <indexterm><primary>shadowing, warning</primary></indexterm>
daniel.is.fischer's avatar
daniel.is.fischer committed
1380

1381
1382
1383
1384
	  <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.,