using.xml 110 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
  <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>
34
35
$ ghc hello.hs
</screen>
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

     <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
62
63
Hello World!
</screen>
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

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

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

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

92
93
94
      <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
95

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

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

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

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

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

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

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

136
137
138
139
140
      <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>
141
142

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

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

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

160
161
    <sect2>
      <title>Setting options in GHCi</title>
rrt's avatar
rrt committed
162

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

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

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

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

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

    <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
216
    table.</para>
217
  </sect1>
rrt's avatar
rrt committed
218

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

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

225
226
227
    <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
228

229
    <variablelist>
rrt's avatar
rrt committed
230

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

238
      <varlistentry>
dterei's avatar
dterei committed
239
        <term>
240
241
          <filename>.lhs</filename>
          <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
dterei's avatar
dterei committed
242
243
244
245
        </term>
        <listitem>
          <para>A &ldquo;literate Haskell&rdquo; module.</para>
        </listitem>
246
247
248
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
249
250
251
252
253
        <term><filename>.hi</filename></term>
        <listitem>
          <para>A Haskell interface file, probably
          compiler-generated.</para>
        </listitem>
254
255
256
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
257
258
259
260
261
        <term><filename>.hc</filename></term>
        <listitem>
          <para>Intermediate C file produced by the Haskell
          compiler.</para>
        </listitem>
262
263
264
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
265
266
267
268
269
        <term><filename>.c</filename></term>
        <listitem>
          <para>A C&nbsp;file not produced by the Haskell
          compiler.</para>
        </listitem>
270
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
271

272
      <varlistentry>
dterei's avatar
dterei committed
273
274
275
        <term><filename>.ll</filename></term>
        <listitem>
          <para>An llvm-intermediate-language source file, usually
276
          produced by the compiler.</para>
dterei's avatar
dterei committed
277
        </listitem>
278
279
280
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
281
282
283
        <term><filename>.bc</filename></term>
        <listitem>
          <para>An llvm-intermediate-language bitcode file, usually
284
          produced by the compiler.</para>
dterei's avatar
dterei committed
285
        </listitem>
286
287
      </varlistentry>

288
      <varlistentry>
dterei's avatar
dterei committed
289
290
291
        <term><filename>.s</filename></term>
        <listitem>
          <para>An assembly-language source file, usually produced by
292
          the compiler.</para>
dterei's avatar
dterei committed
293
        </listitem>
294
295
296
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
297
298
299
300
        <term><filename>.o</filename></term>
        <listitem>
          <para>An object file, produced by an assembler.</para>
        </listitem>
301
302
303
304
305
306
307
      </varlistentry>
    </variablelist>

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

  </sect1>
rrt's avatar
rrt committed
308

309
310
311
  <sect1 id="modes">
    <title>Modes of operation</title>

312
313
314
315
316
317
318
319
320
321
322
323
324
325
    <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>
326
327
328

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

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

          <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>
dterei's avatar
dterei committed
362
        </listitem>
363
364
365
      </varlistentry>

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

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

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

      <varlistentry>
dterei's avatar
dterei committed
421
        <term>
422
          <cmdsynopsis>
423
            <command>ghc --mk-dll</command>
424
          </cmdsynopsis>
dterei's avatar
dterei committed
425
          <indexterm><primary>DLL-creation mode</primary></indexterm>
426
        </term>
dterei's avatar
dterei committed
427
428
429
430
        <listitem>
          <para>DLL-creation mode (Windows only).  See <xref
          linkend="win32-dlls-create"/>.</para>
        </listitem>
431
      </varlistentry>
432
433

      <varlistentry>
dterei's avatar
dterei committed
434
435
        <term>
          <cmdsynopsis>
436
          <command>ghc --help</command> <command>ghc -?</command>
dterei's avatar
dterei committed
437
            </cmdsynopsis>
438
439
          <indexterm><primary><option>&ndash;&ndash;help</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
440
441
        <listitem>
          <para>Cause GHC to spew a long usage message to standard
442
          output and then exit.</para>
dterei's avatar
dterei committed
443
        </listitem>
444
445
      </varlistentry>

446
      <varlistentry>
dterei's avatar
dterei committed
447
        <term>
448
449
450
451
452
          <cmdsynopsis>
            <command>ghc --show-iface <replaceable>file</replaceable></command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;--show-iface</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
453
454
455
456
457
        <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>
458
459
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
460
      <varlistentry>
dterei's avatar
dterei committed
461
        <term>
Ian Lynagh's avatar
Ian Lynagh committed
462
          <cmdsynopsis>
Ian Lynagh's avatar
Ian Lynagh committed
463
            <command>ghc --supported-extensions</command>
Ian Lynagh's avatar
Ian Lynagh committed
464
465
            <command>ghc --supported-languages</command>
          </cmdsynopsis>
Ian Lynagh's avatar
Ian Lynagh committed
466
          <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
467
        </term>
dterei's avatar
dterei committed
468
469
470
        <listitem>
          <para>Print the supported language extensions.</para>
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
471
472
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
473
      <varlistentry>
dterei's avatar
dterei committed
474
        <term>
Ian Lynagh's avatar
Ian Lynagh committed
475
476
477
478
479
          <cmdsynopsis>
            <command>ghc --info</command>
          </cmdsynopsis>
          <indexterm><primary><option>&ndash;&ndash;info</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
480
481
482
        <listitem>
          <para>Print information about the compiler.</para>
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
483
484
      </varlistentry>

485
      <varlistentry>
dterei's avatar
dterei committed
486
        <term>
487
          <cmdsynopsis>
488
489
490
            <command>ghc --version</command>
            <command>ghc -V</command>
          </cmdsynopsis>
491
492
493
          <indexterm><primary><option>-V</option></primary></indexterm>
          <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
494
495
496
        <listitem>
          <para>Print a one-line string including GHC's version number.</para>
        </listitem>
497
498
499
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
500
        <term>
501
          <cmdsynopsis>
502
503
            <command>ghc --numeric-version</command>
          </cmdsynopsis>
504
505
          <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
506
507
508
        <listitem>
          <para>Print GHC's numeric version number only.</para>
        </listitem>
509
510
511
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
512
513
        <term>
          <cmdsynopsis>
514
515
            <command>ghc --print-libdir</command>
          </cmdsynopsis>
516
517
          <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
518
519
520
521
522
523
524
        <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
          <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
525
526
      in the package configuration file
      (see <xref linkend="packages"/>).</para>
dterei's avatar
dterei committed
527
        </listitem>
528
529
      </varlistentry>

530
531
532
533
    </variablelist>

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

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

548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
      <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>
564
565
566
567
568
569

      <para>The main advantages to using <literal>ghc
      &ndash;&ndash;make</literal> over traditional
      <literal>Makefile</literal>s are:</para>

      <itemizedlist>
dterei's avatar
dterei committed
570
571
572
573
574
575
576
577
578
579
        <listitem>
          <para>GHC doesn't have to be restarted for each compilation,
          which means it can cache information between compilations.
          Compiling a multi-module program with <literal>ghc
          &ndash;&ndash;make</literal> can be up to twice as fast as
          running <literal>ghc</literal> individually on each source
          file.</para>
        </listitem>
        <listitem>
          <para>You don't have to write a <literal>Makefile</literal>.</para>
580
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
dterei's avatar
dterei committed
581
582
583
584
585
586
        </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>
587
      </itemizedlist>
daniel.is.fischer's avatar
daniel.is.fischer committed
588

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

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

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

615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
    <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
638

639
640
641
642
643
644
645
646
647
648
649
650
      <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
651

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

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

660
      <informaltable>
dterei's avatar
dterei committed
661
662
663
664
665
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
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
        <tgroup cols="4">
          <colspec align="left"/>
          <colspec align="left"/>
          <colspec align="left"/>
          <colspec align="left"/>

          <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>
720
      </informaltable>
daniel.is.fischer's avatar
daniel.is.fischer committed
721

722
723
724
725
      <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
726

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

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

733
734
735
736
      <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
737
738
739
      <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>
740
741
742

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

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

      <sect3 id="overriding-suffixes">
dterei's avatar
dterei committed
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
        <title>Overriding the default behaviour for a file</title>

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

        <variablelist>
          <varlistentry>
            <term><option>-x</option> <replaceable>suffix</replaceable>
                      <indexterm><primary><option>-x</option></primary>
              </indexterm></term>
              <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>
771
772
      </sect3>

773
774
775
    </sect2>
  </sect1>

776
777
  <sect1 id="options-help">
    <title>Help and verbosity options</title>
778

779
780
    <indexterm><primary>help options</primary></indexterm>
    <indexterm><primary>verbosity options</primary></indexterm>
781

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

dterei's avatar
dterei committed
798
          <para>Please, oh please, use the <option>-v</option> option
799
800
801
          when reporting bugs!  Knowing that you ran the right bits in
          the right order is always the first thing we want to
          verify.</para>
dterei's avatar
dterei committed
802
        </listitem>
803
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
804

805
      <varlistentry>
dterei's avatar
dterei committed
806
        <term>
807
808
809
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
        <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>
              <term><option>-v0</option></term>
              <listitem>
                <para>Disable all non-essential messages (this is the
                default).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>-v1</option></term>
              <listitem>
                <para>Minimal verbosity: print one line per
                compilation (this is the default when
                <option>&ndash;&ndash;make</option> or
                <option>&ndash;&ndash;interactive</option> is on).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>-v2</option></term>
              <listitem>
                <para>Print the name of each compilation phase as it
                is executed. (equivalent to
                <option>-dshow-passes</option>).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>-v3</option></term>
              <listitem>
                <para>The same as <option>-v2</option>, except that in
849
850
                addition the full command line (if appropriate) for
                each compilation phase is also printed.</para>
dterei's avatar
dterei committed
851
852
853
854
855
856
857
858
859
860
861
862
863
864
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>-v4</option></term>
              <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>
865
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
866

867
      <varlistentry>
dterei's avatar
dterei committed
868
        <term><option>-ferror-spans</option>
869
          <indexterm><primary><option>-ferror-spans</option></primary>
dterei's avatar
dterei committed
870
          </indexterm>
871
        </term>
dterei's avatar
dterei committed
872
873
874
875
876
        <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>
877

dterei's avatar
dterei committed
878
          <para>For example:</para>
879

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

dterei's avatar
dterei committed
884
          <para>becomes:</para>
885

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

dterei's avatar
dterei committed
890
          <para>And multi-line spans are possible too:</para>
891

892
893
<screen>
test.hs:(5,4)-(6,7):
894
895
896
    Conflicting definitions for `a'
    Bound at: test.hs:5:4
              test.hs:6:7
897
898
    In the binding group for: a, b, a
</screen>
899

dterei's avatar
dterei committed
900
901
902
903
904
          <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>
905
      </varlistentry>
906

907
908
909
910
911
912
913
914
915
916
917
918
919
920
      <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>

921
922
923
924
925
926
927
928
929
930
931
932
      <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>
933
934
935
    </variablelist>
  </sect1>

936
  &separate;
rrt's avatar
rrt committed
937

938
939
940
941
942
943
944
945
946
947
948
949
  <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:
950
    <option>-fwarn-overlapping-patterns</option>,
Ian Lynagh's avatar
Ian Lynagh committed
951
    <option>-fwarn-warnings-deprecations</option>,
952
    <option>-fwarn-deprecated-flags</option>,
953
    <option>-fwarn-duplicate-exports</option>,
954
    <option>-fwarn-missing-fields</option>,
955
    <option>-fwarn-missing-methods</option>,
956
    <option>-fwarn-lazy-unlifted-bindings</option>,
957
958
    <option>-fwarn-wrong-do-bind</option>,
    <option>-fwarn-unsupported-calling-conventions</option>, and
959
960
    <option>-fwarn-dodgy-foreign-imports</option>.  The following
    flags are
961
962
963
    simple ways to select standard &ldquo;packages&rdquo; of warnings:
    </para>

964
    <variablelist>
965
966

      <varlistentry>
dterei's avatar
dterei committed
967
968
969
970
971
972
973
974
975
976
977
        <term><option>-W</option>:</term>
        <listitem>
          <indexterm><primary>-W option</primary></indexterm>
          <para>Provides the standard warnings plus
          <option>-fwarn-incomplete-patterns</option>,
          <option>-fwarn-dodgy-exports</option>,
          <option>-fwarn-dodgy-imports</option>,
          <option>-fwarn-unused-matches</option>,
          <option>-fwarn-unused-imports</option>, and
          <option>-fwarn-unused-binds</option>.</para>
        </listitem>
978
      </varlistentry>
rrt's avatar
rrt committed
979

980
      <varlistentry>
dterei's avatar
dterei committed
981
982
983
984
985
986
987
        <term><option>-Wall</option>:</term>
        <listitem>
          <indexterm><primary><option>-Wall</option></primary></indexterm>
          <para>Turns on all warning options that indicate potentially
          suspicious code.  The warnings that are
          <emphasis>not</emphasis> enabled by <option>-Wall</option>
          are
988
            <option>-fwarn-tabs</option>,
989
            <option>-fwarn-incomplete-uni-patterns</option>,
990
            <option>-fwarn-incomplete-record-updates</option>,
991
            <option>-fwarn-monomorphism-restriction</option>,
992
            <option>-fwarn-auto-orphans</option>,
993
994
995
            <option>-fwarn-implicit-prelude</option>,
            <option>-fwarn-missing-local-sigs</option>,
            <option>-fwarn-missing-import-lists</option>.</para>
dterei's avatar
dterei committed
996
        </listitem>
997
998
999
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
1000
1001
1002
1003
        <term><option>-w</option>:</term>
        <listitem>
          <indexterm><primary><option>-w</option></primary></indexterm>
          <para>Turns off all warnings, including the standard ones and
1004
      those that <literal>-Wall</literal> doesn't enable.</para>
dterei's avatar
dterei committed
1005
        </listitem>
1006
      </varlistentry>
rrt's avatar
rrt committed
1007

1008
      <varlistentry>
dterei's avatar
dterei committed
1009
1010
1011
1012
1013
1014
        <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>
1015
1016
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
1017
      <varlistentry>
dterei's avatar
dterei committed
1018
1019
1020
1021
1022
        <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
Ian Lynagh's avatar
Ian Lynagh committed
1023
        <option>-Werror</option> flag.</para>
dterei's avatar
dterei committed
1024
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
1025
1026
      </varlistentry>

1027
    </variablelist>
rrt's avatar
rrt committed
1028

1029
1030
1031
    <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
1032

1033
    <variablelist>
rrt's avatar
rrt committed
1034

1035
      <varlistentry>
dterei's avatar
dterei committed
1036
1037
1038
1039
1040
1041
        <term><option>-fdefer-type-errors</option>:</term>
        <listitem>
          <indexterm><primary><option>-fdefer-type-errors</option></primary>
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
            <para>Defer as many type errors as possible until runtime.  
1042
1043
1044
            At compile time you get a warning (instead of an error).  At 
            runtime, if you use a value that depends on a type error, you 
            get a runtime error; but you can run any type-correct parts of your code 
1045
            just fine.  See <xref linkend="defer-type-errors"/></para>
dterei's avatar
dterei committed
1046
        </listitem>
1047
1048
1049
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
1050
1051
1052
1053
1054
1055
        <term><option>-fhelpful-errors</option>:</term>
        <listitem>
          <indexterm><primary><option>-fhelpful-errors</option></primary>
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
            <para>When a name or package is not found in scope, make
1056
            suggestions for the name or package you might have meant instead.</para>
dterei's avatar
dterei committed
1057
1058
          <para>This option is on by default.</para>
        </listitem>
1059
1060
      </varlistentry>

1061
      <varlistentry>
dterei's avatar
dterei committed
1062
1063
1064
1065
1066
1067
1068
1069
        <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
1070
1071
1072
1073
      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>

dterei's avatar
dterei committed
1074
1075
          <para>This option is on by default.</para>
        </listitem>
1076
1077
      </varlistentry>

1078
      <varlistentry>
dterei's avatar
dterei committed
1079
1080
1081
1082
1083
1084
1085
1086
        <term><option>-fwarn-warnings-deprecations</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
          <indexterm><primary>deprecations</primary></indexterm>
          <para>Causes a warning to be emitted when a
          module, function or type with a WARNING or DEPRECATED pragma
Ian Lynagh's avatar
Ian Lynagh committed
1087
1088
      is used. See <xref linkend="warning-deprecated-pragma"/> for more
      details on the pragmas.</para>
1089

dterei's avatar
dterei committed
1090
1091
          <para>This option is on by default.</para>
        </listitem>
1092
1093
      </varlistentry>

1094
      <varlistentry>
dterei's avatar
dterei committed
1095
1096
1097
1098
1099
1100
1101
        <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>
1102

dterei's avatar
dterei committed
1103
1104
          <para>This option is on by default.</para>
        </listitem>
1105
1106
      </varlistentry>

1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
      <varlistentry>
        <term><option>-fwarn-unsupported-calling-conventions</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-unsupported-calling-conventions</option></primary>
          </indexterm>
          <para>Causes a warning to be emitted for foreign declarations
          that use unsupported calling conventions. In particular,
          if the <literal>stdcall</literal> calling convention is used
          on an architecture other than i386 then it will be treated
          as <literal>ccall</literal>.</para>
        </listitem>
      </varlistentry>

1120
      <varlistentry>
dterei's avatar
dterei committed
1121
1122
1123
1124
1125
1126
        <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>
1127

1128
1129
1130
<programlisting>
foreign import "f" f :: FunPtr t
</programlisting>
1131

1132
          <para>on the grounds that it probably should be</para>
1133

1134
1135
1136
<programlisting>
foreign import "&amp;f" f :: FunPtr t
</programlisting>
1137

1138
1139
1140
1141
1142
1143
1144
          <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>
dterei's avatar
dterei committed
1145
        </listitem>
1146
1147
      </varlistentry>

1148
      <varlistentry>
dterei's avatar
dterei committed
1149
1150
1151
1152
1153
        <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
1154
1155
1156
      <literal>T</literal> is exported
      with all constructors, i.e. <literal>T(..)</literal>, but is it
      just a type synonym.</para>
dterei's avatar
dterei committed
1157
          <para>Also causes a warning to be emitted when a module is
1158
      re-exported, but that module exports nothing.</para>
dterei's avatar
dterei committed
1159
        </listitem>
1160
1161
      </varlistentry>

1162
      <varlistentry>
dterei's avatar
dterei committed
1163
1164
1165
1166
        <term><option>-fwarn-dodgy-imports</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
          </indexterm>
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
          <para>Causes a warning to be emitted in the following cases:</para>
          <itemizedlist>
            <listitem>
              <para>When a datatype <literal>T</literal> is imported with all
                constructors, i.e. <literal>T(..)</literal>, but has been
                exported abstractly, i.e. <literal>T</literal>.
              </para>
            </listitem>
            <listitem>
              <para>When an <literal>import</literal> statement hides an
                entity that is not exported.</para>
            </listitem>
          </itemizedlist>
dterei's avatar
dterei committed
1180
        </listitem>
1181
      </varlistentry>
rrt's avatar
rrt committed
1182

1183
      <varlistentry>
dterei's avatar
dterei committed
1184
1185
1186
1187
1188
        <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
1189
1190
1191
      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
1192
      error, rather than a warning, in GHC 7.2.
1193
      </para>
dterei's avatar
dterei committed
1194
        </listitem>
1195
1196
      </varlistentry>

1197
      <varlistentry>
dterei's avatar
dterei committed
1198
1199
1200
1201
1202
        <term><option>-fwarn-duplicate-exports</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
          <indexterm><primary>duplicate exports, warning</primary></indexterm>
          <indexterm><primary>export lists, duplicates</primary></indexterm>
rrt's avatar
rrt committed
1203

dterei's avatar
dterei committed
1204
          <para>Have the compiler warn about duplicate entries in
1205
1206
1207
1208
          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
1209

dterei's avatar
dterei committed
1210
1211
          <para>This option is on by default.</para>
        </listitem>
1212
1213
1214
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
        <term><option>-fwarn-hi-shadowing</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
          <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>
1226
1227
      </varlistentry>

1228
1229
      <varlistentry>
        <term><option>-fwarn-identities</option>:</term>
dterei's avatar
dterei committed
1230
        <listitem>
1231
1232
1233
1234
1235
1236
1237
1238
1239
          <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>
dterei's avatar
dterei committed
1240
        </listitem>
1241
1242
      </varlistentry>

1243
1244
1245
1246
1247
1248
1249
1250
1251
      <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
1252
          <option>-XNoImplicitPrelude</option> or a
1253
1254
1255
          <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>

          <para>Note that no warning is given for syntax that implicitly
1256
          refers to the Prelude, even if <option>-XNoImplicitPrelude</option>
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
          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>

1268
      <varlistentry>