using.xml 145 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
        <term>Mode flags</term>
        <listitem>
186
          <para>For example, <option>--make</option> or <option>-E</option>.
dterei's avatar
dterei committed
187
188
189
            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
      </varlistentry>

248
249
250
251
252
253
254
      <varlistentry>
        <term><filename>.hspp</filename></term>
        <listitem>
          <para>A file created by the preprocessor.</para>
        </listitem>
      </varlistentry>

255
      <varlistentry>
dterei's avatar
dterei committed
256
257
258
259
260
        <term><filename>.hi</filename></term>
        <listitem>
          <para>A Haskell interface file, probably
          compiler-generated.</para>
        </listitem>
261
262
263
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
264
265
266
267
268
        <term><filename>.hc</filename></term>
        <listitem>
          <para>Intermediate C file produced by the Haskell
          compiler.</para>
        </listitem>
269
270
271
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
272
273
274
275
276
        <term><filename>.c</filename></term>
        <listitem>
          <para>A C&nbsp;file not produced by the Haskell
          compiler.</para>
        </listitem>
277
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
278

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

      <varlistentry>
dterei's avatar
dterei committed
288
289
290
        <term><filename>.bc</filename></term>
        <listitem>
          <para>An llvm-intermediate-language bitcode file, usually
291
          produced by the compiler.</para>
dterei's avatar
dterei committed
292
        </listitem>
293
294
      </varlistentry>

295
      <varlistentry>
dterei's avatar
dterei committed
296
297
298
        <term><filename>.s</filename></term>
        <listitem>
          <para>An assembly-language source file, usually produced by
299
          the compiler.</para>
dterei's avatar
dterei committed
300
        </listitem>
301
302
303
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
304
305
306
307
        <term><filename>.o</filename></term>
        <listitem>
          <para>An object file, produced by an assembler.</para>
        </listitem>
308
309
310
311
312
313
314
      </varlistentry>
    </variablelist>

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

  </sect1>
rrt's avatar
rrt committed
315

316
317
  <sect1 id="modes">
    <title>Modes of operation</title>
318
    <indexterm><primary>help options</primary></indexterm>
319

320
321
322
323
324
325
326
327
328
329
330
331
332
333
    <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>
334
335
336

    <variablelist>
      <varlistentry>
dterei's avatar
dterei committed
337
338
339
        <term>
          <cmdsynopsis><command>ghc --interactive</command>
          </cmdsynopsis>
340
341
          <indexterm><primary>interactive mode</primary></indexterm>
          <indexterm><primary>ghci</primary></indexterm>
dterei's avatar
dterei committed
342
343
344
345
346
347
        </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>
348
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
349

350
      <varlistentry>
dterei's avatar
dterei committed
351
        <term>
352
          <cmdsynopsis><command>ghc --make</command>
dterei's avatar
dterei committed
353
          </cmdsynopsis>
354
          <indexterm><primary>make mode</primary></indexterm>
355
          <indexterm><primary><option>--make</option></primary></indexterm>
dterei's avatar
dterei committed
356
357
358
359
360
361
362
363
        </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>
364
365
366
367

          <para>
            This mode is the default if there are any Haskell
            source files mentioned on the command line, and in this case
368
            the <option>--make</option> option can be omitted.
369
          </para>
dterei's avatar
dterei committed
370
        </listitem>
371
372
373
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
374
375
376
        <term>
          <cmdsynopsis><command>ghc -e</command>
             <arg choice='plain'><replaceable>expr</replaceable></arg>
377
378
          </cmdsynopsis>
          <indexterm><primary>eval mode</primary></indexterm>
dterei's avatar
dterei committed
379
380
381
382
383
384
385
386
        </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>
387
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
388

389
      <varlistentry>
dterei's avatar
dterei committed
390
        <term>
391
          <cmdsynopsis>
dterei's avatar
dterei committed
392
            <command>ghc -E</command>
393
            <command>ghc -C</command>
dterei's avatar
dterei committed
394
395
396
397
398
399
400
            <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>
401
        </term>
dterei's avatar
dterei committed
402
403
404
        <listitem>
          <para>This is the traditional batch-compiler mode, in which
          GHC can compile source files one at a time, or link objects
405
          together into an executable. See <xref
dterei's avatar
dterei committed
406
407
          linkend="options-order"/>.</para>
        </listitem>
408
409
410
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
411
        <term>
412
          <cmdsynopsis>
413
            <command>ghc -M</command>
414
415
416
          </cmdsynopsis>
          <indexterm><primary>dependency-generation mode</primary></indexterm>
        </term>
dterei's avatar
dterei committed
417
418
419
420
421
422
        <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>
423
424
425
      </varlistentry>

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

      <varlistentry>
dterei's avatar
dterei committed
439
440
        <term>
          <cmdsynopsis>
441
          <command>ghc --help</command> <command>ghc -?</command>
dterei's avatar
dterei committed
442
            </cmdsynopsis>
443
          <indexterm><primary><option>--help</option></primary></indexterm>
444
        </term>
dterei's avatar
dterei committed
445
446
        <listitem>
          <para>Cause GHC to spew a long usage message to standard
447
          output and then exit.</para>
dterei's avatar
dterei committed
448
        </listitem>
449
450
      </varlistentry>

451
      <varlistentry>
dterei's avatar
dterei committed
452
        <term>
453
454
455
          <cmdsynopsis>
            <command>ghc --show-iface <replaceable>file</replaceable></command>
          </cmdsynopsis>
456
          <indexterm><primary><option>--show-iface</option></primary></indexterm>
457
        </term>
dterei's avatar
dterei committed
458
459
460
461
462
        <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>
463
464
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
465
      <varlistentry>
dterei's avatar
dterei committed
466
        <term>
Ian Lynagh's avatar
Ian Lynagh committed
467
          <cmdsynopsis>
Ian Lynagh's avatar
Ian Lynagh committed
468
            <command>ghc --supported-extensions</command>
Ian Lynagh's avatar
Ian Lynagh committed
469
470
            <command>ghc --supported-languages</command>
          </cmdsynopsis>
471
          <indexterm><primary><option>--supported-extensions</option></primary><primary><option>--supported-languages</option></primary></indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
472
        </term>
dterei's avatar
dterei committed
473
474
475
        <listitem>
          <para>Print the supported language extensions.</para>
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
476
477
      </varlistentry>

478
479
480
481
482
      <varlistentry>
        <term>
          <cmdsynopsis>
            <command>ghc --show-options</command>
          </cmdsynopsis>
483
          <indexterm><primary><option>--show-options</option></primary></indexterm>
484
485
486
487
488
489
        </term>
        <listitem>
          <para>Print the supported command line options. This flag can be used for autocompletion in a shell.</para>
        </listitem>
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
490
      <varlistentry>
dterei's avatar
dterei committed
491
        <term>
Ian Lynagh's avatar
Ian Lynagh committed
492
493
494
          <cmdsynopsis>
            <command>ghc --info</command>
          </cmdsynopsis>
495
          <indexterm><primary><option>--info</option></primary></indexterm>
Ian Lynagh's avatar
Ian Lynagh committed
496
        </term>
dterei's avatar
dterei committed
497
498
499
        <listitem>
          <para>Print information about the compiler.</para>
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
500
501
      </varlistentry>

502
      <varlistentry>
dterei's avatar
dterei committed
503
        <term>
504
          <cmdsynopsis>
505
506
507
            <command>ghc --version</command>
            <command>ghc -V</command>
          </cmdsynopsis>
508
          <indexterm><primary><option>-V</option></primary></indexterm>
509
          <indexterm><primary><option>--version</option></primary></indexterm>
510
        </term>
dterei's avatar
dterei committed
511
512
513
        <listitem>
          <para>Print a one-line string including GHC's version number.</para>
        </listitem>
514
515
516
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
517
        <term>
518
          <cmdsynopsis>
519
520
            <command>ghc --numeric-version</command>
          </cmdsynopsis>
521
          <indexterm><primary><option>--numeric-version</option></primary></indexterm>
522
        </term>
dterei's avatar
dterei committed
523
524
525
        <listitem>
          <para>Print GHC's numeric version number only.</para>
        </listitem>
526
527
528
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
529
530
        <term>
          <cmdsynopsis>
531
532
            <command>ghc --print-libdir</command>
          </cmdsynopsis>
533
          <indexterm><primary><option>--print-libdir</option></primary></indexterm>
534
        </term>
dterei's avatar
dterei committed
535
536
537
538
539
540
541
        <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
542
543
      in the package configuration file
      (see <xref linkend="packages"/>).</para>
dterei's avatar
dterei committed
544
        </listitem>
545
546
      </varlistentry>

547
548
549
    </variablelist>

    <sect2 id="make-mode">
550
551
      <title>Using <command>ghc</command> <option>--make</option></title>
      <indexterm><primary><option>--make</option></primary></indexterm>
552
      <indexterm><primary>separate compilation</primary></indexterm>
daniel.is.fischer's avatar
daniel.is.fischer committed
553

554
      <para>In this mode, GHC will build a multi-module Haskell program by following
Ian Lynagh's avatar
Ian Lynagh committed
555
      dependencies from one or more root modules (usually just
556
557
558
559
560
561
      <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>
562
ghc --make Main.hs
563
564
</screen>

565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
      <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>
581
582

      <para>The main advantages to using <literal>ghc
583
      --make</literal> over traditional
584
585
586
      <literal>Makefile</literal>s are:</para>

      <itemizedlist>
dterei's avatar
dterei committed
587
588
589
590
        <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
591
          --make</literal> can be up to twice as fast as
dterei's avatar
dterei committed
592
593
594
595
596
          running <literal>ghc</literal> individually on each source
          file.</para>
        </listitem>
        <listitem>
          <para>You don't have to write a <literal>Makefile</literal>.</para>
597
          <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
dterei's avatar
dterei committed
598
599
600
601
602
603
        </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>
604
605
606
607
608
        <listitem>
          <para>Using the <literal>-j</literal> flag, you can compile
          modules in parallel. Specify <literal>-jN</literal> to
          compile <replaceable>N</replaceable> jobs in parallel.</para>
        </listitem>
609
      </itemizedlist>
daniel.is.fischer's avatar
daniel.is.fischer committed
610

611
612
      <para>Any of the command-line options described in the rest of
      this chapter can be used with
613
      <option>--make</option>, but note that any options
614
615
      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
616
      file only, you'll need to use an <literal>OPTIONS_GHC</literal>
617
      pragma (see <xref linkend="source-file-options"/>).</para>
618
619

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

624
625
626
627
628
      <para>For backward compatibility with existing make scripts, when
      used in combination with <option>-c</option>, the linking phase
      is omitted (same as <option>--make</option>
      <option>-no-link</option>).</para>

629
630
631
632
633
634
635
636
637
638
      <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
639
      linkend="search-path"/>).</para>
640
    </sect2>
daniel.is.fischer's avatar
daniel.is.fischer committed
641

642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
    <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
665

666
667
668
669
670
671
672
673
674
675
676
677
      <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
678

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

682
683
      <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
684
      relevant flag is present, then go all the way through to linking.
685
      This table summarises:</para>
daniel.is.fischer's avatar
daniel.is.fischer committed
686

687
      <informaltable>
dterei's avatar
dterei committed
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
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
        <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>
747
      </informaltable>
daniel.is.fischer's avatar
daniel.is.fischer committed
748

749
750
751
752
      <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
753

754
755
756
      <para>Thus, a common invocation would be: </para>

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

760
761
762
763
      <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
764
765
766
      <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>
767
768
769

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

773
774
      <para>Note: The option <option>-E</option><indexterm><primary>-E
      option</primary></indexterm> runs just the pre-processing passes
775
      of the compiler, dumping the result in a file.</para>
776

777
778
779
780
      <para>Note: The option <option>-C</option> is only available when
      GHC is built in unregisterised mode. See <xref linkend="unreg"/>
      for more details.</para>

781
      <sect3 id="overriding-suffixes">
dterei's avatar
dterei committed
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
        <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>
802
803
      </sect3>

804
805
806
    </sect2>
  </sect1>

807
  <sect1 id="options-help">
808
    <title>Verbosity options</title>
809

810
    <indexterm><primary>verbosity options</primary></indexterm>
811

812
813
    <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>
814
815
    <variablelist>
      <varlistentry>
dterei's avatar
dterei committed
816
        <term>
817
818
819
          <option>-v</option>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
820
821
        <listitem>
          <para>The <option>-v</option> option makes GHC
822
          <emphasis>verbose</emphasis>: it reports its version number
823
824
825
826
827
          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
828
          <para>Please, oh please, use the <option>-v</option> option
829
830
831
          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
832
        </listitem>
833
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
834

835
      <varlistentry>
dterei's avatar
dterei committed
836
        <term>
837
838
839
          <option>-v</option><replaceable>n</replaceable>
          <indexterm><primary><option>-v</option></primary></indexterm>
        </term>
dterei's avatar
dterei committed
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
        <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
861
862
                <option>--make</option> or
                <option>--interactive</option> is on).</para>
dterei's avatar
dterei committed
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
              </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
879
880
                addition the full command line (if appropriate) for
                each compilation phase is also printed.</para>
dterei's avatar
dterei committed
881
882
883
884
885
886
887
888
889
890
891
892
893
894
              </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>
895
      </varlistentry>
daniel.is.fischer's avatar
daniel.is.fischer committed
896

897
898

      <varlistentry>
899
        <term><option>--fprint-explicit-foralls, -fprint-explicit-kinds, -fprint-unicode-syntax</option>
900
901
          <indexterm><primary><option>-fprint-explicit-foralls</option></primary></indexterm>
          <indexterm><primary><option>-fprint-explicit-kinds</option></primary></indexterm>
902
          <indexterm><primary><option>-fprint-unicode-syntax</option></primary></indexterm>
903
904
        </term>
        <listitem>
905
          <para>These three flags control the way in which GHC displays types, in error messages and in GHCi.
906
907
908
909
910
911
912
913
914
915
          Using <option>-fprint-explicit-foralls</option> makes GHC print explicit <literal>forall</literal>
          quantification at the top level of a type; normally this is suppressed.  For example, in GHCi:
<screen>
ghci> let f x = x
ghci> :t f
f :: a -> a
ghci> :set -fprint-explicit-foralls
ghci> :t f
f :: forall a. a -> a
</screen>
916
917
918
919
920
921
922
923
924
925
926
However, regardless of the flag setting, the quantifiers are printed under these circumstances:
<itemizedlist>
<listitem><para>For nested <literal>foralls</literal>, e.g.
<screen>
ghci> :t GHC.ST.runST
GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a
</screen>
</para></listitem>
<listitem><para>If any of the quantified type variables has a kind
that mentions a kind variable, e.g.
<screen>
927
928
929
930
931
ghci> :i Data.Type.Equality.sym
Data.Type.Equality.sym ::
  forall (k :: BOX) (a :: k) (b :: k).
  (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a
        -- Defined in Data.Type.Equality
932
933
934
935
936
937
</screen>
</para></listitem>
</itemizedlist>
          </para>
          <para>
         Using <option>-fprint-explicit-kinds</option> makes GHC print kind arguments
938
939
940
941
942
943
         in types, which are normally suppressed.  This can be important when you are using kind polymorphism.
         For example:
<screen>
ghci> :set -XPolyKinds
ghci> data T a = MkT
ghci> :t MkT
944
MkT :: forall (k :: BOX) (a :: k). T a
945
946
ghci> :set -fprint-explicit-foralls
ghci> :t MkT
947
MkT :: forall (k :: BOX) (a :: k). T k a
948
949
950
951
952
953
954
955
956
</screen>
         </para>
         <para>
          When <option>-fprint-unicode-syntax</option> is enabled, GHC prints type signatures using
          the unicode symbols from the <option>-XUnicodeSyntax</option> extension.
<screen>
ghci> :set -fprint-unicode-syntax
ghci> :t (>>)
(>>) :: &forall; (m :: * &rarr; *) a b. Monad m &rArr; m a &rarr; m b &rarr; m b
957
958
959
960
961
</screen>
         </para>
        </listitem>
      </varlistentry>

962
      <varlistentry>
dterei's avatar
dterei committed
963
        <term><option>-ferror-spans</option>
964
          <indexterm><primary><option>-ferror-spans</option></primary>
dterei's avatar
dterei committed
965
          </indexterm>
966
        </term>
dterei's avatar
dterei committed
967
968
969
970
971
        <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>
972

dterei's avatar
dterei committed
973
          <para>For example:</para>
974

975
976
977
<screen>
test.hs:3:6: parse error on input `where'
</screen>
978

dterei's avatar
dterei committed
979
          <para>becomes:</para>
980

981
982
983
<screen>
test296.hs:3:6-10: parse error on input `where'
</screen>
984

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

987
988
<screen>
test.hs:(5,4)-(6,7):
989
990
991
    Conflicting definitions for `a'
    Bound at: test.hs:5:4
              test.hs:6:7
992
993
    In the binding group for: a, b, a
</screen>
994

dterei's avatar
dterei committed
995
996
997
998
999
          <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>
1000
      </varlistentry>
1001

1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
      <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>

1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
      <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>
1028
1029
1030
    </variablelist>
  </sect1>

1031
  &separate;
rrt's avatar
rrt committed
1032

1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
  <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:
1045
    <option>-fwarn-overlapping-patterns</option>,
Ian Lynagh's avatar
Ian Lynagh committed
1046
    <option>-fwarn-warnings-deprecations</option>,
1047
    <option>-fwarn-deprecated-flags</option>,
1048
1049
    <option>-fwarn-unrecognised-pragmas</option>,
    <option>-fwarn-pointless-pragmas</option>,
1050
    <option>-fwarn-duplicate-constraints</option>,
1051
    <option>-fwarn-duplicate-exports</option>,
1052
    <option>-fwarn-overflowed-literals</option>,
1053
    <option>-fwarn-empty-enumerations</option>,
1054
    <option>-fwarn-missing-fields</option>,
1055
    <option>-fwarn-missing-methods</option>,
1056
    <option>-fwarn-wrong-do-bind</option>,
1057
    <option>-fwarn-unsupported-calling-conventions</option>,
1058
    <option>-fwarn-dodgy-foreign-imports</option>,
1059
    <option>-fwarn-inline-rule-shadowing</option>,
Austin Seipp's avatar
Austin Seipp committed
1060
1061
1062
    <option>-fwarn-unsupported-llvm-version</option>,
    <option>-fwarn-context-quantification</option>, and
    <option>-fwarn-tabs</option>.
1063
1064
    The following flags are simple ways to select standard
    &ldquo;packages&rdquo; of warnings:
1065
1066
    </para>

1067
    <variablelist>
1068
1069

      <varlistentry>
dterei's avatar
dterei committed
1070
1071
1072
1073
        <term><option>-W</option>:</term>
        <listitem>
          <indexterm><primary>-W option</primary></indexterm>
          <para>Provides the standard warnings plus
Austin Seipp's avatar
Austin Seipp committed
1074
          <option>-fwarn-unused-binds</option>,
dterei's avatar
dterei committed
1075
          <option>-fwarn-unused-matches</option>,
Austin Seipp's avatar
Austin Seipp committed
1076
1077
1078
1079
          <option>-fwarn-unused-imports</option>,
          <option>-fwarn-incomplete-patterns</option>,
          <option>-fwarn-dodgy-exports</option>, and
          <option>-fwarn-dodgy-imports</option>.</para>
dterei's avatar
dterei committed
1080
        </listitem>
1081
      </varlistentry>
rrt's avatar
rrt committed
1082

1083
      <varlistentry>
dterei's avatar
dterei committed
1084
1085
1086
1087
1088
1089
1090
        <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
1091
1092
1093
1094
1095
1096
1097
1098
1099
            <option>-fwarn-incomplete-uni-patterns</option>,
            <option>-fwarn-incomplete-record-updates</option>,
            <option>-fwarn-monomorphism-restriction</option>,
            <option>-fwarn-auto-orphans</option>,
            <option>-fwarn-implicit-prelude</option>,
            <option>-fwarn-missing-local-sigs</option>,
            <option>-fwarn-missing-exported-sigs</option>,
            <option>-fwarn-missing-import-lists</option> and
            <option>-fwarn-identities</option>.</para>
dterei's avatar
dterei committed
1100
        </listitem>
1101
1102
1103
      </varlistentry>

      <varlistentry>
dterei's avatar
dterei committed
1104
1105
1106
1107
        <term><option>-w</option>:</term>
        <listitem>
          <indexterm><primary><option>-w</option></primary></indexterm>
          <para>Turns off all warnings, including the standard ones and
1108
      those that <literal>-Wall</literal> doesn't enable.</para>
dterei's avatar
dterei committed
1109
        </listitem>
1110
      </varlistentry>
rrt's avatar
rrt committed
1111

1112
      <varlistentry>
dterei's avatar
dterei committed
1113
1114
1115
1116
1117
1118
        <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>
1119
1120
      </varlistentry>

Ian Lynagh's avatar
Ian Lynagh committed
1121
      <varlistentry>
dterei's avatar
dterei committed
1122
1123
1124
1125
1126
        <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
1127
        <option>-Werror</option> flag.</para>
dterei's avatar
dterei committed
1128
        </listitem>
Ian Lynagh's avatar
Ian Lynagh committed
1129
1130
      </varlistentry>

1131
    </variablelist>
rrt's avatar
rrt committed
1132

1133
1134
1135
    <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
1136

1137
    <variablelist>
rrt's avatar
rrt committed
1138

1139
      <varlistentry>
1140
        <term><option>-fwarn-typed-holes</option>:</term>
1141
        <listitem>
1142
          <indexterm><primary><option>-fwarn-typed-holes</option></primary>
1143
1144
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
1145
1146
1147
1148
1149
          <para>
              Determines whether the compiler reports typed holes warnings. Has
              no effect unless typed holes errors are deferred until runtime.
              See <xref linkend="typed-holes"/> and <xref linkend="defer-type-errors"/>
            </para>
1150
1151
1152
1153
1154
1155

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


1156
      <varlistentry>
dterei's avatar
dterei committed
1157
1158
1159
1160
1161
1162
        <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.  
1163
1164
1165
            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 
1166
            just fine.  See <xref linkend="defer-type-errors"/></para>
dterei's avatar
dterei committed
1167
        </listitem>
1168
1169
      </varlistentry>

1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
      <varlistentry>
        <term><option>-fdefer-typed-holes</option>:</term>
        <listitem>
          <indexterm><primary><option>-fdefer-typed-holes</option></primary>
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
          <para>
              Defer typed holes errors until runtime. This will turn the errors
              produced by <link linked="typed-holes">typed holes</link> into
              warnings. Using a value that depends on a typed hole produces a
              runtime error, the same as <option>-fdefer-type-errors</option>
              (which implies this option). See <xref linkend="typed-holes"/>
              and <xref linkend="defer-type-errors"/>.
          </para>
          <para>
              Implied by <option>-fdefer-type-errors</option>. See also
              <option>-fwarn-typed-holes</option>.
          </para>
        </listitem>
      </varlistentry>

thomasw's avatar
thomasw committed
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
      <varlistentry>
        <term><option>-fwarn-partial-type-signatures</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-partial-type-signatures</option></primary>
          </indexterm>
          <indexterm><primary>warnings</primary></indexterm>
          <para>
              Determines whether the compiler reports holes in partial type
              signatures as warnings. Has no effect unless
              <option>-XPartialTypeSignatures</option> is enabled, which
              controls whether errors should be generated for holes in types
              or not. See <xref linkend="partial-type-signatures"/>.
            </para>

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

1209
      <varlistentry>
dterei's avatar
dterei committed
1210
1211
1212
1213
1214
1215
        <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
1216
            suggestions for the name or package you might have meant instead.</para>
dterei's avatar
dterei committed
1217
1218
          <para>This option is on by default.</para>
        </listitem>