Sync the list of default warnings with reality; fixes #8060.
[ghc.git] / docs / users_guide / using.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <chapter id="using-ghc">
3 <title>Using GHC</title>
4
5 <indexterm><primary>GHC, using</primary></indexterm>
6 <indexterm><primary>using GHC</primary></indexterm>
7
8 <sect1>
9 <title>Getting started: compiling programs</title>
10
11 <para>
12 In this chapter you'll find a complete reference to the GHC
13 command-line syntax, including all 400+ flags. It's a large and
14 complex system, and there are lots of details, so it can be
15 quite hard to figure out how to get started. With that in mind,
16 this introductory section provides a quick introduction to the
17 basic usage of GHC for compiling a Haskell program, before the
18 following sections dive into the full syntax.
19 </para>
20
21 <para>
22 Let's create a Hello World program, and compile and run it.
23 First, create a file <filename>hello.hs</filename> containing
24 the Haskell code:
25 </para>
26
27 <programlisting>
28 main = putStrLn "Hello, World!"
29 </programlisting>
30
31 <para>To compile the program, use GHC like this:</para>
32
33 <screen>
34 $ ghc hello.hs
35 </screen>
36
37 <para>(where <literal>$</literal> represents the prompt: don't
38 type it). GHC will compile the source
39 file <filename>hello.hs</filename>, producing
40 an <firstterm>object
41 file</firstterm> <filename>hello.o</filename> and
42 an <firstterm>interface
43 file</firstterm> <filename>hello.hi</filename>, and then it
44 will link the object file to the libraries that come with GHC
45 to produce an executable called <filename>hello</filename> on
46 Unix/Linux/Mac, or <filename>hello.exe</filename> on
47 Windows.</para>
48
49 <para>
50 By default GHC will be very quiet about what it is doing, only
51 printing error messages. If you want to see in more detail
52 what's going on behind the scenes, add <option>-v</option> to
53 the command line.
54 </para>
55
56 <para>
57 Then we can run the program like this:
58 </para>
59
60 <screen>
61 $ ./hello
62 Hello World!
63 </screen>
64
65 <para>
66 If your program contains multiple modules, then you only need to
67 tell GHC the name of the source file containing
68 the <filename>Main</filename> module, and GHC will examine
69 the <literal>import</literal> declarations to find the other
70 modules that make up the program and find their source files.
71 This means that, with the exception of
72 the <literal>Main</literal> module, every source file should be
73 named after the module name that it contains (with dots replaced
74 by directory separators). For example, the
75 module <literal>Data.Person</literal> would be in the
76 file <filename>Data/Person.hs</filename> on Unix/Linux/Mac,
77 or <filename>Data\Person.hs</filename> on Windows.
78 </para>
79 </sect1>
80
81 <sect1>
82 <title>Options overview</title>
83
84 <para>GHC's behaviour is controlled by
85 <firstterm>options</firstterm>, which for historical reasons are
86 also sometimes referred to as command-line flags or arguments.
87 Options can be specified in three ways:</para>
88
89 <sect2>
90 <title>Command-line arguments</title>
91
92 <indexterm><primary>structure, command-line</primary></indexterm>
93 <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
94 <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
95
96 <para>An invocation of GHC takes the following form:</para>
97
98 <screen>
99 ghc [argument...]
100 </screen>
101
102 <para>Command-line arguments are either options or file names.</para>
103
104 <para>Command-line options begin with <literal>-</literal>.
105 They may <emphasis>not</emphasis> be grouped:
106 <option>-vO</option> is different from <option>-v -O</option>.
107 Options need not precede filenames: e.g., <literal>ghc *.o -o
108 foo</literal>. All options are processed and then applied to
109 all files; you cannot, for example, invoke <literal>ghc -c -O1
110 Foo.hs -O2 Bar.hs</literal> to apply different optimisation
111 levels to the files <filename>Foo.hs</filename> and
112 <filename>Bar.hs</filename>.</para>
113 </sect2>
114
115 <sect2 id="source-file-options">
116 <title>Command line options in source files</title>
117
118 <indexterm><primary>source-file options</primary></indexterm>
119
120 <para>Sometimes it is useful to make the connection between a
121 source file and the command-line options it requires quite
122 tight. For instance, if a Haskell source file deliberately
123 uses name shadowing, it should be compiled with the
124 <option>-fno-warn-name-shadowing</option> option. Rather than maintaining
125 the list of per-file options in a <filename>Makefile</filename>,
126 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>
129
130 <programlisting>
131 {-# OPTIONS_GHC -fno-warn-name-shadowing #-}
132 module X where
133 ...
134 </programlisting>
135
136 <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
137 (see <xref linkend="pragmas"/>).</para>
138
139 <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
140 (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 <para>NOTE: the contents of OPTIONS_GHC are appended to the
149 command-line options, so options given in the source file
150 override those given on the command-line.</para>
151
152 <para>It is not recommended to move all the contents of your
153 Makefiles into your source files, but in some circumstances, the
154 <literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
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 file).</para>
158 </sect2>
159
160 <sect2>
161 <title>Setting options in GHCi</title>
162
163 <para>Options may also be modified from within GHCi, using the
164 <literal>:set</literal> command. See <xref linkend="ghci-set"/>
165 for more details.</para>
166 </sect2>
167 </sect1>
168
169 <sect1 id="static-dynamic-flags">
170 <title>Static, Dynamic, and Mode options</title>
171 <indexterm><primary>static</primary><secondary>options</secondary>
172 </indexterm>
173 <indexterm><primary>dynamic</primary><secondary>options</secondary>
174 </indexterm>
175 <indexterm><primary>mode</primary><secondary>options</secondary>
176 </indexterm>
177
178 <para>Each of GHC's command line options is classified as
179 <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
180 <firstterm>mode</firstterm>:</para>
181
182 <variablelist>
183 <varlistentry>
184 <term>Mode flags</term>
185 <listitem>
186 <para>For example, <option>--make</option> or <option>-E</option>.
187 There may only be a single mode flag on the command line. The
188 available modes are listed in <xref linkend="modes"/>.</para>
189 </listitem>
190 </varlistentry>
191 <varlistentry>
192 <term>Dynamic Flags</term>
193 <listitem>
194 <para>Most non-mode flags fall into this category. A dynamic flag
195 may be used on the command line, in a
196 <literal>OPTIONS_GHC</literal> pragma in a source file, or set
197 using <literal>:set</literal> in GHCi.</para>
198 </listitem>
199 </varlistentry>
200 <varlistentry>
201 <term>Static Flags</term>
202 <listitem>
203 <para>A few flags are "static", which means they can only be used on
204 the command-line, and remain in force over the entire GHC/GHCi
205 run.</para>
206 </listitem>
207 </varlistentry>
208 </variablelist>
209
210 <para>The flag reference tables (<xref
211 linkend="flag-reference"/>) lists the status of each flag.</para>
212
213 <para>There are a few flags that are static except that they can
214 also be used with GHCi's <literal>:set</literal> command; these
215 are listed as &ldquo;static/<literal>:set</literal>&rdquo; in the
216 table.</para>
217 </sect1>
218
219 <sect1 id="file-suffixes">
220 <title>Meaningful file suffixes</title>
221
222 <indexterm><primary>suffixes, file</primary></indexterm>
223 <indexterm><primary>file suffixes for GHC</primary></indexterm>
224
225 <para>File names with &ldquo;meaningful&rdquo; suffixes (e.g.,
226 <filename>.lhs</filename> or <filename>.o</filename>) cause the
227 &ldquo;right thing&rdquo; to happen to those files.</para>
228
229 <variablelist>
230
231 <varlistentry>
232 <term><filename>.hs</filename></term>
233 <listitem>
234 <para>A Haskell module.</para>
235 </listitem>
236 </varlistentry>
237
238 <varlistentry>
239 <term>
240 <filename>.lhs</filename>
241 <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
242 </term>
243 <listitem>
244 <para>A &ldquo;literate Haskell&rdquo; module.</para>
245 </listitem>
246 </varlistentry>
247
248 <varlistentry>
249 <term><filename>.hi</filename></term>
250 <listitem>
251 <para>A Haskell interface file, probably
252 compiler-generated.</para>
253 </listitem>
254 </varlistentry>
255
256 <varlistentry>
257 <term><filename>.hc</filename></term>
258 <listitem>
259 <para>Intermediate C file produced by the Haskell
260 compiler.</para>
261 </listitem>
262 </varlistentry>
263
264 <varlistentry>
265 <term><filename>.c</filename></term>
266 <listitem>
267 <para>A C&nbsp;file not produced by the Haskell
268 compiler.</para>
269 </listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><filename>.ll</filename></term>
274 <listitem>
275 <para>An llvm-intermediate-language source file, usually
276 produced by the compiler.</para>
277 </listitem>
278 </varlistentry>
279
280 <varlistentry>
281 <term><filename>.bc</filename></term>
282 <listitem>
283 <para>An llvm-intermediate-language bitcode file, usually
284 produced by the compiler.</para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><filename>.s</filename></term>
290 <listitem>
291 <para>An assembly-language source file, usually produced by
292 the compiler.</para>
293 </listitem>
294 </varlistentry>
295
296 <varlistentry>
297 <term><filename>.o</filename></term>
298 <listitem>
299 <para>An object file, produced by an assembler.</para>
300 </listitem>
301 </varlistentry>
302 </variablelist>
303
304 <para>Files with other suffixes (or without suffixes) are passed
305 straight to the linker.</para>
306
307 </sect1>
308
309 <sect1 id="modes">
310 <title>Modes of operation</title>
311
312 <para>
313 GHC's behaviour is firstly controlled by a mode flag. Only one
314 of these flags may be given, but it does not necessarily need to
315 be the first option on the command-line.
316 </para>
317
318 <para>
319 If no mode flag is present, then GHC will enter make mode
320 (<xref linkend="make-mode" />) if there are any Haskell source
321 files given on the command line, or else it will link the
322 objects named on the command line to produce an executable.
323 </para>
324
325 <para>The available mode flags are:</para>
326
327 <variablelist>
328 <varlistentry>
329 <term>
330 <cmdsynopsis><command>ghc --interactive</command>
331 </cmdsynopsis>
332 <indexterm><primary>interactive mode</primary></indexterm>
333 <indexterm><primary>ghci</primary></indexterm>
334 </term>
335 <listitem>
336 <para>Interactive mode, which is also available as
337 <command>ghci</command>. Interactive mode is described in
338 more detail in <xref linkend="ghci"/>.</para>
339 </listitem>
340 </varlistentry>
341
342 <varlistentry>
343 <term>
344 <cmdsynopsis><command>ghc --make</command>
345 </cmdsynopsis>
346 <indexterm><primary>make mode</primary></indexterm>
347 <indexterm><primary><option>--make</option></primary></indexterm>
348 </term>
349 <listitem>
350 <para>In this mode, GHC will build a multi-module Haskell
351 program automatically, figuring out dependencies for itself.
352 If you have a straightforward Haskell program, this is
353 likely to be much easier, and faster, than using
354 <command>make</command>. Make mode is described in <xref
355 linkend="make-mode"/>.</para>
356
357 <para>
358 This mode is the default if there are any Haskell
359 source files mentioned on the command line, and in this case
360 the <option>--make</option> option can be omitted.
361 </para>
362 </listitem>
363 </varlistentry>
364
365 <varlistentry>
366 <term>
367 <cmdsynopsis><command>ghc -e</command>
368 <arg choice='plain'><replaceable>expr</replaceable></arg>
369 </cmdsynopsis>
370 <indexterm><primary>eval mode</primary></indexterm>
371 </term>
372 <listitem>
373 <para>Expression-evaluation mode. This is very similar to
374 interactive mode, except that there is a single expression
375 to evaluate (<replaceable>expr</replaceable>) which is given
376 on the command line. See <xref linkend="eval-mode"/> for
377 more details.</para>
378 </listitem>
379 </varlistentry>
380
381 <varlistentry>
382 <term>
383 <cmdsynopsis>
384 <command>ghc -E</command>
385 <command>ghc -c</command>
386 <command>ghc -S</command>
387 <command>ghc -c</command>
388 </cmdsynopsis>
389 <indexterm><primary><option>-E</option></primary></indexterm>
390 <indexterm><primary><option>-C</option></primary></indexterm>
391 <indexterm><primary><option>-S</option></primary></indexterm>
392 <indexterm><primary><option>-c</option></primary></indexterm>
393 </term>
394 <listitem>
395 <para>This is the traditional batch-compiler mode, in which
396 GHC can compile source files one at a time, or link objects
397 together into an executable. This mode also applies if
398 there is no other mode flag specified on the command line,
399 in which case it means that the specified files should be
400 compiled and then linked to form a program. See <xref
401 linkend="options-order"/>.</para>
402 </listitem>
403 </varlistentry>
404
405 <varlistentry>
406 <term>
407 <cmdsynopsis>
408 <command>ghc -M</command>
409 </cmdsynopsis>
410 <indexterm><primary>dependency-generation mode</primary></indexterm>
411 </term>
412 <listitem>
413 <para>Dependency-generation mode. In this mode, GHC can be
414 used to generate dependency information suitable for use in
415 a <literal>Makefile</literal>. See <xref
416 linkend="makefile-dependencies"/>.</para>
417 </listitem>
418 </varlistentry>
419
420 <varlistentry>
421 <term>
422 <cmdsynopsis>
423 <command>ghc --mk-dll</command>
424 </cmdsynopsis>
425 <indexterm><primary>DLL-creation mode</primary></indexterm>
426 </term>
427 <listitem>
428 <para>DLL-creation mode (Windows only). See <xref
429 linkend="win32-dlls-create"/>.</para>
430 </listitem>
431 </varlistentry>
432
433 <varlistentry>
434 <term>
435 <cmdsynopsis>
436 <command>ghc --help</command> <command>ghc -?</command>
437 </cmdsynopsis>
438 <indexterm><primary><option>--help</option></primary></indexterm>
439 </term>
440 <listitem>
441 <para>Cause GHC to spew a long usage message to standard
442 output and then exit.</para>
443 </listitem>
444 </varlistentry>
445
446 <varlistentry>
447 <term>
448 <cmdsynopsis>
449 <command>ghc --show-iface <replaceable>file</replaceable></command>
450 </cmdsynopsis>
451 <indexterm><primary><option>--show-iface</option></primary></indexterm>
452 </term>
453 <listitem>
454 <para>Read the interface in
455 <replaceable>file</replaceable> and dump it as text to
456 <literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para>
457 </listitem>
458 </varlistentry>
459
460 <varlistentry>
461 <term>
462 <cmdsynopsis>
463 <command>ghc --supported-extensions</command>
464 <command>ghc --supported-languages</command>
465 </cmdsynopsis>
466 <indexterm><primary><option>--supported-extensions</option></primary><primary><option>--supported-languages</option></primary></indexterm>
467 </term>
468 <listitem>
469 <para>Print the supported language extensions.</para>
470 </listitem>
471 </varlistentry>
472
473 <varlistentry>
474 <term>
475 <cmdsynopsis>
476 <command>ghc --show-options</command>
477 </cmdsynopsis>
478 <indexterm><primary><option>--show-options</option></primary></indexterm>
479 </term>
480 <listitem>
481 <para>Print the supported command line options. This flag can be used for autocompletion in a shell.</para>
482 </listitem>
483 </varlistentry>
484
485 <varlistentry>
486 <term>
487 <cmdsynopsis>
488 <command>ghc --info</command>
489 </cmdsynopsis>
490 <indexterm><primary><option>--info</option></primary></indexterm>
491 </term>
492 <listitem>
493 <para>Print information about the compiler.</para>
494 </listitem>
495 </varlistentry>
496
497 <varlistentry>
498 <term>
499 <cmdsynopsis>
500 <command>ghc --version</command>
501 <command>ghc -V</command>
502 </cmdsynopsis>
503 <indexterm><primary><option>-V</option></primary></indexterm>
504 <indexterm><primary><option>--version</option></primary></indexterm>
505 </term>
506 <listitem>
507 <para>Print a one-line string including GHC's version number.</para>
508 </listitem>
509 </varlistentry>
510
511 <varlistentry>
512 <term>
513 <cmdsynopsis>
514 <command>ghc --numeric-version</command>
515 </cmdsynopsis>
516 <indexterm><primary><option>--numeric-version</option></primary></indexterm>
517 </term>
518 <listitem>
519 <para>Print GHC's numeric version number only.</para>
520 </listitem>
521 </varlistentry>
522
523 <varlistentry>
524 <term>
525 <cmdsynopsis>
526 <command>ghc --print-libdir</command>
527 </cmdsynopsis>
528 <indexterm><primary><option>--print-libdir</option></primary></indexterm>
529 </term>
530 <listitem>
531 <para>Print the path to GHC's library directory. This is
532 the top of the directory tree containing GHC's libraries,
533 interfaces, and include files (usually something like
534 <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This
535 is the value of
536 <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
537 in the package configuration file
538 (see <xref linkend="packages"/>).</para>
539 </listitem>
540 </varlistentry>
541
542 </variablelist>
543
544 <sect2 id="make-mode">
545 <title>Using <command>ghc</command> <option>--make</option></title>
546 <indexterm><primary><option>--make</option></primary></indexterm>
547 <indexterm><primary>separate compilation</primary></indexterm>
548
549 <para>In this mode, GHC will build a multi-module Haskell program by following
550 dependencies from one or more root modules (usually just
551 <literal>Main</literal>). For example, if your
552 <literal>Main</literal> module is in a file called
553 <filename>Main.hs</filename>, you could compile and link the
554 program like this:</para>
555
556 <screen>
557 ghc --make Main.hs
558 </screen>
559
560 <para>
561 In fact, GHC enters make mode automatically if there are any
562 Haskell source files on the command line and no other mode is
563 specified, so in this case we could just type
564 </para>
565
566 <screen>
567 ghc Main.hs
568 </screen>
569
570 <para>Any number of source file names or module names may be
571 specified; GHC will figure out all the modules in the program by
572 following the imports from these initial modules. It will then
573 attempt to compile each module which is out of date, and
574 finally, if there is a <literal>Main</literal> module, the
575 program will also be linked into an executable.</para>
576
577 <para>The main advantages to using <literal>ghc
578 --make</literal> over traditional
579 <literal>Makefile</literal>s are:</para>
580
581 <itemizedlist>
582 <listitem>
583 <para>GHC doesn't have to be restarted for each compilation,
584 which means it can cache information between compilations.
585 Compiling a multi-module program with <literal>ghc
586 --make</literal> can be up to twice as fast as
587 running <literal>ghc</literal> individually on each source
588 file.</para>
589 </listitem>
590 <listitem>
591 <para>You don't have to write a <literal>Makefile</literal>.</para>
592 <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
593 </listitem>
594 <listitem>
595 <para>GHC re-calculates the dependencies each time it is
596 invoked, so the dependencies never get out of sync with the
597 source.</para>
598 </listitem>
599 </itemizedlist>
600
601 <para>Any of the command-line options described in the rest of
602 this chapter can be used with
603 <option>--make</option>, but note that any options
604 you give on the command line will apply to all the source files
605 compiled, so if you want any options to apply to a single source
606 file only, you'll need to use an <literal>OPTIONS_GHC</literal>
607 pragma (see <xref linkend="source-file-options"/>).</para>
608
609 <para>If the program needs to be linked with additional objects
610 (say, some auxiliary C code), then the object files can be
611 given on the command line and GHC will include them when linking
612 the executable.</para>
613
614 <para>Note that GHC can only follow dependencies if it has the
615 source file available, so if your program includes a module for
616 which there is no source file, even if you have an object and an
617 interface file for the module, then GHC will complain. The
618 exception to this rule is for package modules, which may or may
619 not have source files.</para>
620
621 <para>The source files for the program don't all need to be in
622 the same directory; the <option>-i</option> option can be used
623 to add directories to the search path (see <xref
624 linkend="search-path"/>).</para>
625 </sect2>
626
627 <sect2 id="eval-mode">
628 <title>Expression evaluation mode</title>
629
630 <para>This mode is very similar to interactive mode, except that
631 there is a single expression to evaluate which is specified on
632 the command line as an argument to the <option>-e</option>
633 option:</para>
634
635 <screen>
636 ghc -e <replaceable>expr</replaceable>
637 </screen>
638
639 <para>Haskell source files may be named on the command line, and
640 they will be loaded exactly as in interactive mode. The
641 expression is evaluated in the context of the loaded
642 modules.</para>
643
644 <para>For example, to load and run a Haskell program containing
645 a module <literal>Main</literal>, we might say</para>
646
647 <screen>
648 ghc -e Main.main Main.hs
649 </screen>
650
651 <para>or we can just use this mode to evaluate expressions in
652 the context of the <literal>Prelude</literal>:</para>
653
654 <screen>
655 $ ghc -e "interact (unlines.map reverse.lines)"
656 hello
657 olleh
658 </screen>
659 </sect2>
660
661 <sect2 id="options-order">
662 <title>Batch compiler mode</title>
663
664 <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
665 given on the command line.</para>
666
667 <para>The first phase to run is determined by each input-file
668 suffix, and the last phase is determined by a flag. If no
669 relevant flag is present, then go all the way through to linking.
670 This table summarises:</para>
671
672 <informaltable>
673 <tgroup cols="4">
674 <colspec align="left"/>
675 <colspec align="left"/>
676 <colspec align="left"/>
677 <colspec align="left"/>
678
679 <thead>
680 <row>
681 <entry>Phase of the compilation system</entry>
682 <entry>Suffix saying &ldquo;start here&rdquo;</entry>
683 <entry>Flag saying &ldquo;stop after&rdquo;</entry>
684 <entry>(suffix of) output file</entry>
685 </row>
686 </thead>
687 <tbody>
688 <row>
689 <entry>literate pre-processor</entry>
690 <entry><literal>.lhs</literal></entry>
691 <entry>-</entry>
692 <entry><literal>.hs</literal></entry>
693 </row>
694
695 <row>
696 <entry>C pre-processor (opt.) </entry>
697 <entry><literal>.hs</literal> (with
698 <option>-cpp</option>)</entry>
699 <entry><option>-E</option></entry>
700 <entry><literal>.hspp</literal></entry>
701 </row>
702
703 <row>
704 <entry>Haskell compiler</entry>
705 <entry><literal>.hs</literal></entry>
706 <entry><option>-C</option>, <option>-S</option></entry>
707 <entry><literal>.hc</literal>, <literal>.s</literal></entry>
708 </row>
709
710 <row>
711 <entry>C compiler (opt.)</entry>
712 <entry><literal>.hc</literal> or <literal>.c</literal></entry>
713 <entry><option>-S</option></entry>
714 <entry><literal>.s</literal></entry>
715 </row>
716
717 <row>
718 <entry>assembler</entry>
719 <entry><literal>.s</literal></entry>
720 <entry><option>-c</option></entry>
721 <entry><literal>.o</literal></entry>
722 </row>
723
724 <row>
725 <entry>linker</entry>
726 <entry><replaceable>other</replaceable></entry>
727 <entry>-</entry>
728 <entry><filename>a.out</filename></entry>
729 </row>
730 </tbody>
731 </tgroup>
732 </informaltable>
733
734 <indexterm><primary><option>-C</option></primary></indexterm>
735 <indexterm><primary><option>-E</option></primary></indexterm>
736 <indexterm><primary><option>-S</option></primary></indexterm>
737 <indexterm><primary><option>-c</option></primary></indexterm>
738
739 <para>Thus, a common invocation would be: </para>
740
741 <screen>
742 ghc -c Foo.hs
743 </screen>
744
745 <para>to compile the Haskell source file
746 <filename>Foo.hs</filename> to an object file
747 <filename>Foo.o</filename>.</para>
748
749 <para>Note: What the Haskell compiler proper produces depends on what
750 backend code generator is used. See <xref linkend="code-generators"/>
751 for more details.</para>
752
753 <para>Note: C pre-processing is optional, the
754 <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
755 flag turns it on. See <xref linkend="c-pre-processor"/> for more
756 details.</para>
757
758 <para>Note: The option <option>-E</option><indexterm><primary>-E
759 option</primary></indexterm> runs just the pre-processing passes
760 of the compiler, dumping the result in a file.</para>
761
762 <sect3 id="overriding-suffixes">
763 <title>Overriding the default behaviour for a file</title>
764
765 <para>As described above, the way in which a file is processed by GHC
766 depends on its suffix. This behaviour can be overridden using the
767 <option>-x</option> option:</para>
768
769 <variablelist>
770 <varlistentry>
771 <term><option>-x</option> <replaceable>suffix</replaceable>
772 <indexterm><primary><option>-x</option></primary>
773 </indexterm></term>
774 <listitem>
775 <para>Causes all files following this option on the command
776 line to be processed as if they had the suffix
777 <replaceable>suffix</replaceable>. For example, to compile a
778 Haskell module in the file <literal>M.my-hs</literal>,
779 use <literal>ghc -c -x hs M.my-hs</literal>.</para>
780 </listitem>
781 </varlistentry>
782 </variablelist>
783 </sect3>
784
785 </sect2>
786 </sect1>
787
788 <sect1 id="options-help">
789 <title>Help and verbosity options</title>
790
791 <indexterm><primary>help options</primary></indexterm>
792 <indexterm><primary>verbosity options</primary></indexterm>
793
794 <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
795 and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
796 <variablelist>
797 <varlistentry>
798 <term>
799 <option>-v</option>
800 <indexterm><primary><option>-v</option></primary></indexterm>
801 </term>
802 <listitem>
803 <para>The <option>-v</option> option makes GHC
804 <emphasis>verbose</emphasis>: it reports its version number
805 and shows (on stderr) exactly how it invokes each phase of
806 the compilation system. Moreover, it passes the
807 <option>-v</option> flag to most phases; each reports its
808 version number (and possibly some other information).</para>
809
810 <para>Please, oh please, use the <option>-v</option> option
811 when reporting bugs! Knowing that you ran the right bits in
812 the right order is always the first thing we want to
813 verify.</para>
814 </listitem>
815 </varlistentry>
816
817 <varlistentry>
818 <term>
819 <option>-v</option><replaceable>n</replaceable>
820 <indexterm><primary><option>-v</option></primary></indexterm>
821 </term>
822 <listitem>
823 <para>To provide more control over the compiler's verbosity,
824 the <option>-v</option> flag takes an optional numeric
825 argument. Specifying <option>-v</option> on its own is
826 equivalent to <option>-v3</option>, and the other levels
827 have the following meanings:</para>
828
829 <variablelist>
830 <varlistentry>
831 <term><option>-v0</option></term>
832 <listitem>
833 <para>Disable all non-essential messages (this is the
834 default).</para>
835 </listitem>
836 </varlistentry>
837
838 <varlistentry>
839 <term><option>-v1</option></term>
840 <listitem>
841 <para>Minimal verbosity: print one line per
842 compilation (this is the default when
843 <option>--make</option> or
844 <option>--interactive</option> is on).</para>
845 </listitem>
846 </varlistentry>
847
848 <varlistentry>
849 <term><option>-v2</option></term>
850 <listitem>
851 <para>Print the name of each compilation phase as it
852 is executed. (equivalent to
853 <option>-dshow-passes</option>).</para>
854 </listitem>
855 </varlistentry>
856
857 <varlistentry>
858 <term><option>-v3</option></term>
859 <listitem>
860 <para>The same as <option>-v2</option>, except that in
861 addition the full command line (if appropriate) for
862 each compilation phase is also printed.</para>
863 </listitem>
864 </varlistentry>
865
866 <varlistentry>
867 <term><option>-v4</option></term>
868 <listitem>
869 <para>The same as <option>-v3</option> except that the
870 intermediate program representation after each
871 compilation phase is also printed (excluding
872 preprocessed and C/assembly files).</para>
873 </listitem>
874 </varlistentry>
875 </variablelist>
876 </listitem>
877 </varlistentry>
878
879 <varlistentry>
880 <term><option>-ferror-spans</option>
881 <indexterm><primary><option>-ferror-spans</option></primary>
882 </indexterm>
883 </term>
884 <listitem>
885 <para>Causes GHC to emit the full source span of the
886 syntactic entity relating to an error message. Normally, GHC
887 emits the source location of the start of the syntactic
888 entity only.</para>
889
890 <para>For example:</para>
891
892 <screen>
893 test.hs:3:6: parse error on input `where'
894 </screen>
895
896 <para>becomes:</para>
897
898 <screen>
899 test296.hs:3:6-10: parse error on input `where'
900 </screen>
901
902 <para>And multi-line spans are possible too:</para>
903
904 <screen>
905 test.hs:(5,4)-(6,7):
906 Conflicting definitions for `a'
907 Bound at: test.hs:5:4
908 test.hs:6:7
909 In the binding group for: a, b, a
910 </screen>
911
912 <para>Note that line numbers start counting at one, but
913 column numbers start at zero. This choice was made to
914 follow existing convention (i.e. this is how Emacs does
915 it).</para>
916 </listitem>
917 </varlistentry>
918
919 <varlistentry>
920 <term><option>-H</option><replaceable>size</replaceable>
921 <indexterm><primary><option>-H</option></primary></indexterm>
922 </term>
923 <listitem>
924 <para>Set the minimum size of the heap to
925 <replaceable>size</replaceable>.
926 This option is equivalent to
927 <literal>+RTS&nbsp;-H<replaceable>size</replaceable></literal>,
928 see <xref linkend="rts-options-gc" />.
929 </para>
930 </listitem>
931 </varlistentry>
932
933 <varlistentry>
934 <term><option>-Rghc-timing</option>
935 <indexterm><primary><option>-Rghc-timing</option></primary></indexterm>
936 </term>
937 <listitem>
938 <para>Prints a one-line summary of timing statistics for the
939 GHC run. This option is equivalent to
940 <literal>+RTS&nbsp;-tstderr</literal>, see <xref
941 linkend="rts-options-gc" />.
942 </para>
943 </listitem>
944 </varlistentry>
945 </variablelist>
946 </sect1>
947
948 &separate;
949
950 <sect1 id="options-sanity">
951 <title>Warnings and sanity-checking</title>
952
953 <indexterm><primary>sanity-checking options</primary></indexterm>
954 <indexterm><primary>warnings</primary></indexterm>
955
956
957 <para>GHC has a number of options that select which types of
958 non-fatal error messages, otherwise known as warnings, can be
959 generated during compilation. By default, you get a standard set
960 of warnings which are generally likely to indicate bugs in your
961 program. These are:
962 <option>-fwarn-overlapping-patterns</option>,
963 <option>-fwarn-warnings-deprecations</option>,
964 <option>-fwarn-deprecated-flags</option>,
965 <option>-fwarn-unrecognised-pragmas</option>,
966 <option>-fwarn-pointless-pragmas</option>,
967 <option>-fwarn-duplicate-constraints</option>,
968 <option>-fwarn-duplicate-exports</option>,
969 <option>-fwarn-missing-fields</option>,
970 <option>-fwarn-missing-methods</option>,
971 <option>-fwarn-lazy-unlifted-bindings</option>,
972 <option>-fwarn-wrong-do-bind</option>,
973 <option>-fwarn-unsupported-calling-conventions</option>,
974 <option>-fwarn-dodgy-foreign-imports</option>,
975 <option>-fwarn-typeable-instances</option>,
976 <option>-fwarn-inline-rule-shadowing</option>,
977 <option>-fwarn-alternative-layout-rule-transitional</option>, and
978 <option>-fwarn-unsupported-llvm-version</option>.
979 The following flags are simple ways to select standard
980 &ldquo;packages&rdquo; of warnings:
981 </para>
982
983 <variablelist>
984
985 <varlistentry>
986 <term><option>-W</option>:</term>
987 <listitem>
988 <indexterm><primary>-W option</primary></indexterm>
989 <para>Provides the standard warnings plus
990 <option>-fwarn-incomplete-patterns</option>,
991 <option>-fwarn-dodgy-exports</option>,
992 <option>-fwarn-dodgy-imports</option>,
993 <option>-fwarn-unused-matches</option>,
994 <option>-fwarn-unused-imports</option>, and
995 <option>-fwarn-unused-binds</option>.</para>
996 </listitem>
997 </varlistentry>
998
999 <varlistentry>
1000 <term><option>-Wall</option>:</term>
1001 <listitem>
1002 <indexterm><primary><option>-Wall</option></primary></indexterm>
1003 <para>Turns on all warning options that indicate potentially
1004 suspicious code. The warnings that are
1005 <emphasis>not</emphasis> enabled by <option>-Wall</option>
1006 are
1007 <option>-fwarn-tabs</option>,
1008 <option>-fwarn-incomplete-uni-patterns</option>,
1009 <option>-fwarn-incomplete-record-updates</option>,
1010 <option>-fwarn-monomorphism-restriction</option>,
1011 <option>-fwarn-auto-orphans</option>,
1012 <option>-fwarn-implicit-prelude</option>,
1013 <option>-fwarn-missing-local-sigs</option>,
1014 <option>-fwarn-missing-import-lists</option>.</para>
1015 </listitem>
1016 </varlistentry>
1017
1018 <varlistentry>
1019 <term><option>-w</option>:</term>
1020 <listitem>
1021 <indexterm><primary><option>-w</option></primary></indexterm>
1022 <para>Turns off all warnings, including the standard ones and
1023 those that <literal>-Wall</literal> doesn't enable.</para>
1024 </listitem>
1025 </varlistentry>
1026
1027 <varlistentry>
1028 <term><option>-Werror</option>:</term>
1029 <listitem>
1030 <indexterm><primary><option>-Werror</option></primary></indexterm>
1031 <para>Makes any warning into a fatal error. Useful so that you don't
1032 miss warnings when doing batch compilation. </para>
1033 </listitem>
1034 </varlistentry>
1035
1036 <varlistentry>
1037 <term><option>-Wwarn</option>:</term>
1038 <listitem>
1039 <indexterm><primary><option>-Wwarn</option></primary></indexterm>
1040 <para>Warnings are treated only as warnings, not as errors. This is
1041 the default, but can be useful to negate a
1042 <option>-Werror</option> flag.</para>
1043 </listitem>
1044 </varlistentry>
1045
1046 </variablelist>
1047
1048 <para>The full set of warning options is described below. To turn
1049 off any warning, simply give the corresponding
1050 <option>-fno-warn-...</option> option on the command line.</para>
1051
1052 <variablelist>
1053
1054 <varlistentry>
1055 <term><option>-fdefer-type-errors</option>:</term>
1056 <listitem>
1057 <indexterm><primary><option>-fdefer-type-errors</option></primary>
1058 </indexterm>
1059 <indexterm><primary>warnings</primary></indexterm>
1060 <para>Defer as many type errors as possible until runtime.
1061 At compile time you get a warning (instead of an error). At
1062 runtime, if you use a value that depends on a type error, you
1063 get a runtime error; but you can run any type-correct parts of your code
1064 just fine. See <xref linkend="defer-type-errors"/></para>
1065 </listitem>
1066 </varlistentry>
1067
1068 <varlistentry>
1069 <term><option>-fhelpful-errors</option>:</term>
1070 <listitem>
1071 <indexterm><primary><option>-fhelpful-errors</option></primary>
1072 </indexterm>
1073 <indexterm><primary>warnings</primary></indexterm>
1074 <para>When a name or package is not found in scope, make
1075 suggestions for the name or package you might have meant instead.</para>
1076 <para>This option is on by default.</para>
1077 </listitem>
1078 </varlistentry>
1079
1080 <varlistentry>
1081 <term><option>-fwarn-unrecognised-pragmas</option>:</term>
1082 <listitem>
1083 <indexterm><primary><option>-fwarn-unrecognised-pragmas</option></primary>
1084 </indexterm>
1085 <indexterm><primary>warnings</primary></indexterm>
1086 <indexterm><primary>pragmas</primary></indexterm>
1087 <para>Causes a warning to be emitted when a
1088 pragma that GHC doesn't recognise is used. As well as pragmas
1089 that GHC itself uses, GHC also recognises pragmas known to be used
1090 by other tools, e.g. <literal>OPTIONS_HUGS</literal> and
1091 <literal>DERIVE</literal>.</para>
1092
1093 <para>This option is on by default.</para>
1094 </listitem>
1095 </varlistentry>
1096
1097 <varlistentry>
1098 <term><option>-fwarn-warnings-deprecations</option>:</term>
1099 <listitem>
1100 <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
1101 </indexterm>
1102 <indexterm><primary>warnings</primary></indexterm>
1103 <indexterm><primary>deprecations</primary></indexterm>
1104 <para>Causes a warning to be emitted when a
1105 module, function or type with a WARNING or DEPRECATED pragma
1106 is used. See <xref linkend="warning-deprecated-pragma"/> for more
1107 details on the pragmas.</para>
1108
1109 <para>This option is on by default.</para>
1110 </listitem>
1111 </varlistentry>
1112
1113 <varlistentry>
1114 <term><option>-fwarn-deprecated-flags</option>:</term>
1115 <listitem>
1116 <indexterm><primary><option>-fwarn-deprecated-flags</option></primary>
1117 </indexterm>
1118 <indexterm><primary>deprecated-flags</primary></indexterm>
1119 <para>Causes a warning to be emitted when a deprecated
1120 commandline flag is used.</para>
1121
1122 <para>This option is on by default.</para>
1123 </listitem>
1124 </varlistentry>
1125
1126 <varlistentry>
1127 <term><option>-fwarn-unsupported-calling-conventions</option>:</term>
1128 <listitem>
1129 <indexterm><primary><option>-fwarn-unsupported-calling-conventions</option></primary>
1130 </indexterm>
1131 <para>Causes a warning to be emitted for foreign declarations
1132 that use unsupported calling conventions. In particular,
1133 if the <literal>stdcall</literal> calling convention is used
1134 on an architecture other than i386 then it will be treated
1135 as <literal>ccall</literal>.</para>
1136 </listitem>
1137 </varlistentry>
1138
1139 <varlistentry>
1140 <term><option>-fwarn-dodgy-foreign-imports</option>:</term>
1141 <listitem>
1142 <indexterm><primary><option>-fwarn-dodgy-foreign-imports</option></primary>
1143 </indexterm>
1144 <para>Causes a warning to be emitted for foreign imports of
1145 the following form:</para>
1146
1147 <programlisting>
1148 foreign import "f" f :: FunPtr t
1149 </programlisting>
1150
1151 <para>on the grounds that it probably should be</para>
1152
1153 <programlisting>
1154 foreign import "&amp;f" f :: FunPtr t
1155 </programlisting>
1156
1157 <para>The first form declares that `f` is a (pure) C
1158 function that takes no arguments and returns a pointer to a
1159 C function with type `t`, whereas the second form declares
1160 that `f` itself is a C function with type `t`. The first
1161 declaration is usually a mistake, and one that is hard to
1162 debug because it results in a crash, hence this
1163 warning.</para>
1164 </listitem>
1165 </varlistentry>
1166
1167 <varlistentry>
1168 <term><option>-fwarn-dodgy-exports</option>:</term>
1169 <listitem>
1170 <indexterm><primary><option>-fwarn-dodgy-exports</option></primary>
1171 </indexterm>
1172 <para>Causes a warning to be emitted when a datatype
1173 <literal>T</literal> is exported
1174 with all constructors, i.e. <literal>T(..)</literal>, but is it
1175 just a type synonym.</para>
1176 <para>Also causes a warning to be emitted when a module is
1177 re-exported, but that module exports nothing.</para>
1178 </listitem>
1179 </varlistentry>
1180
1181 <varlistentry>
1182 <term><option>-fwarn-dodgy-imports</option>:</term>
1183 <listitem>
1184 <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
1185 </indexterm>
1186 <para>Causes a warning to be emitted in the following cases:</para>
1187 <itemizedlist>
1188 <listitem>
1189 <para>When a datatype <literal>T</literal> is imported with all
1190 constructors, i.e. <literal>T(..)</literal>, but has been
1191 exported abstractly, i.e. <literal>T</literal>.
1192 </para>
1193 </listitem>
1194 <listitem>
1195 <para>When an <literal>import</literal> statement hides an
1196 entity that is not exported.</para>
1197 </listitem>
1198 </itemizedlist>
1199 </listitem>
1200 </varlistentry>
1201
1202 <varlistentry>
1203 <term><option>-fwarn-lazy-unlifted-bindings</option>:</term>
1204 <listitem>
1205 <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary>
1206 </indexterm>
1207 <para>Causes a warning to be emitted when an unlifted type
1208 is bound in a way that looks lazy, e.g.
1209 <literal>where (I# x) = ...</literal>. Use
1210 <literal>where !(I# x) = ...</literal> instead. This will be an
1211 error, rather than a warning, in GHC 7.2.
1212 </para>
1213 </listitem>
1214 </varlistentry>
1215
1216 <varlistentry>
1217 <term><option>-fwarn-duplicate-constraints</option>:</term>
1218 <listitem>
1219 <indexterm><primary><option>-fwarn-duplicate-constraints</option></primary></indexterm>
1220 <indexterm><primary>duplicate constraints, warning</primary></indexterm>
1221
1222 <para>Have the compiler warn about duplicate constraints in a type signature. For
1223 example
1224 <programlisting>
1225 f :: (Eq a, Show a, Eq a) => a -> a
1226 </programlisting>
1227 The warning will indicate the duplicated <literal>Eq a</literal> constraint.
1228 </para>
1229
1230 <para>This option is on by default.</para>
1231 </listitem>
1232 </varlistentry>
1233
1234 <varlistentry>
1235 <term><option>-fwarn-duplicate-exports</option>:</term>
1236 <listitem>
1237 <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
1238 <indexterm><primary>duplicate exports, warning</primary></indexterm>
1239 <indexterm><primary>export lists, duplicates</primary></indexterm>
1240
1241 <para>Have the compiler warn about duplicate entries in
1242 export lists. This is useful information if you maintain
1243 large export lists, and want to avoid the continued export
1244 of a definition after you've deleted (one) mention of it in
1245 the export list.</para>
1246
1247 <para>This option is on by default.</para>
1248 </listitem>
1249 </varlistentry>
1250
1251 <varlistentry>
1252 <term><option>-fwarn-hi-shadowing</option>:</term>
1253 <listitem>
1254 <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
1255 <indexterm><primary>shadowing</primary>
1256 <secondary>interface files</secondary></indexterm>
1257
1258 <para>Causes the compiler to emit a warning when a module or
1259 interface file in the current directory is shadowing one
1260 with the same module name in a library or other
1261 directory.</para>
1262 </listitem>
1263 </varlistentry>
1264
1265 <varlistentry>
1266 <term><option>-fwarn-identities</option>:</term>
1267 <listitem>
1268 <indexterm><primary><option>-fwarn-identities</option></primary></indexterm>
1269 <para>Causes the compiler to emit a warning when a Prelude numeric
1270 conversion converts a type T to the same type T; such calls
1271 are probably no-ops and can be omitted. The functions checked for
1272 are: <literal>toInteger</literal>,
1273 <literal>toRational</literal>,
1274 <literal>fromIntegral</literal>,
1275 and <literal>realToFrac</literal>.
1276 </para>
1277 </listitem>
1278 </varlistentry>
1279
1280 <varlistentry>
1281 <term><option>-fwarn-implicit-prelude</option>:</term>
1282 <listitem>
1283 <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
1284 <indexterm><primary>implicit prelude, warning</primary></indexterm>
1285 <para>Have the compiler warn if the Prelude is implicitly
1286 imported. This happens unless either the Prelude module is
1287 explicitly imported with an <literal>import ... Prelude ...</literal>
1288 line, or this implicit import is disabled (either by
1289 <option>-XNoImplicitPrelude</option> or a
1290 <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>
1291
1292 <para>Note that no warning is given for syntax that implicitly
1293 refers to the Prelude, even if <option>-XNoImplicitPrelude</option>
1294 would change whether it refers to the Prelude.
1295 For example, no warning is given when
1296 <literal>368</literal> means
1297 <literal>Prelude.fromInteger (368::Prelude.Integer)</literal>
1298 (where <literal>Prelude</literal> refers to the actual Prelude module,
1299 regardless of the imports of the module being compiled).</para>
1300
1301 <para>This warning is off by default.</para>
1302 </listitem>
1303 </varlistentry>
1304
1305 <varlistentry>
1306 <term><option>-fwarn-incomplete-patterns</option>,
1307 <option>-fwarn-incomplete-uni-patterns</option>:
1308 </term>
1309 <listitem>
1310 <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
1311 <indexterm><primary><option>-fwarn-incomplete-uni-patterns</option></primary></indexterm>
1312 <indexterm><primary>incomplete patterns, warning</primary></indexterm>
1313 <indexterm><primary>patterns, incomplete</primary></indexterm>
1314
1315 <para>The option <option>-fwarn-incomplete-patterns</option> warns
1316 about places where
1317 a pattern-match might fail at runtime.
1318 The function
1319 <function>g</function> below will fail when applied to
1320 non-empty lists, so the compiler will emit a warning about
1321 this when <option>-fwarn-incomplete-patterns</option> is
1322 enabled.
1323
1324 <programlisting>
1325 g [] = 2
1326 </programlisting>
1327
1328 This option isn't enabled by default because it can be
1329 a bit noisy, and it doesn't always indicate a bug in the
1330 program. However, it's generally considered good practice
1331 to cover all the cases in your functions, and it is switched
1332 on by <option>-W</option>.</para>
1333
1334 <para>The flag <option>-fwarn-incomplete-uni-patterns</option> is
1335 similar, except that it
1336 applies only to lambda-expressions and pattern bindings, constructs
1337 that only allow a single pattern:
1338
1339 <programlisting>
1340 h = \[] -> 2
1341 Just k = f y
1342 </programlisting>
1343
1344 </para>
1345 </listitem>
1346 </varlistentry>
1347
1348 <varlistentry>
1349 <term><option>-fwarn-incomplete-record-updates</option>:</term>
1350 <listitem>
1351 <indexterm><primary><option>-fwarn-incomplete-record-updates</option></primary></indexterm>
1352 <indexterm><primary>incomplete record updates, warning</primary></indexterm>
1353 <indexterm><primary>record updates, incomplete</primary></indexterm>
1354
1355 <para>The function
1356 <function>f</function> below will fail when applied to
1357 <literal>Bar</literal>, so the compiler will emit a warning about
1358 this when <option>-fwarn-incomplete-record-updates</option> is
1359 enabled.</para>
1360
1361 <programlisting>
1362 data Foo = Foo { x :: Int }
1363 | Bar
1364
1365 f :: Foo -> Foo
1366 f foo = foo { x = 6 }
1367 </programlisting>
1368
1369 <para>This option isn't enabled by default because it can be
1370 very noisy, and it often doesn't indicate a bug in the
1371 program.</para>
1372 </listitem>
1373 </varlistentry>
1374
1375 <varlistentry>
1376 <term>
1377 <option>-fwarn-missing-fields</option>:
1378 <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
1379 <indexterm><primary>missing fields, warning</primary></indexterm>
1380 <indexterm><primary>fields, missing</primary></indexterm>
1381 </term>
1382 <listitem>
1383
1384 <para>This option is on by default, and warns you whenever
1385 the construction of a labelled field constructor isn't
1386 complete, missing initializers for one or more fields. While
1387 not an error (the missing fields are initialised with
1388 bottoms), it is often an indication of a programmer error.</para>
1389 </listitem>
1390 </varlistentry>
1391
1392 <varlistentry>
1393 <term>
1394 <option>-fwarn-missing-import-lists</option>:
1395 <indexterm><primary><option>-fwarn-import-lists</option></primary></indexterm>
1396 <indexterm><primary>missing import lists, warning</primary></indexterm>
1397 <indexterm><primary>import lists, missing</primary></indexterm>
1398 </term>
1399 <listitem>
1400
1401 <para>This flag warns if you use an unqualified
1402 <literal>import</literal> declaration
1403 that does not explicitly list the entities brought into scope. For
1404 example
1405 </para>
1406
1407 <programlisting>
1408 module M where
1409 import X( f )
1410 import Y
1411 import qualified Z
1412 p x = f x x
1413 </programlisting>
1414
1415 <para>
1416 The <option>-fwarn-import-lists</option> flag will warn about the import
1417 of <literal>Y</literal> but not <literal>X</literal>
1418 If module <literal>Y</literal> is later changed to export (say) <literal>f</literal>,
1419 then the reference to <literal>f</literal> in <literal>M</literal> will become
1420 ambiguous. No warning is produced for the import of <literal>Z</literal>
1421 because extending <literal>Z</literal>'s exports would be unlikely to produce
1422 ambiguity in <literal>M</literal>.
1423 </para>
1424 </listitem>
1425 </varlistentry>
1426
1427 <varlistentry>
1428 <term><option>-fwarn-missing-methods</option>:</term>
1429 <listitem>
1430 <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
1431 <indexterm><primary>missing methods, warning</primary></indexterm>
1432 <indexterm><primary>methods, missing</primary></indexterm>
1433
1434 <para>This option is on by default, and warns you whenever
1435 an instance declaration is missing one or more methods, and
1436 the corresponding class declaration has no default
1437 declaration for them.</para>
1438 <para>The warning is suppressed if the method name
1439 begins with an underscore. Here's an example where this is useful:
1440 <programlisting>
1441 class C a where
1442 _simpleFn :: a -> String
1443 complexFn :: a -> a -> String
1444 complexFn x y = ... _simpleFn ...
1445 </programlisting>
1446 The idea is that: (a) users of the class will only call <literal>complexFn</literal>;
1447 never <literal>_simpleFn</literal>; and (b)
1448 instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>.
1449 </para>
1450 </listitem>
1451 </varlistentry>
1452
1453 <varlistentry>
1454 <term><option>-fwarn-missing-signatures</option>:</term>
1455 <listitem>
1456 <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
1457 <indexterm><primary>type signatures, missing</primary></indexterm>
1458
1459 <para>If you would like GHC to check that every top-level
1460 function/value has a type signature, use the
1461 <option>-fwarn-missing-signatures</option> option. As part of
1462 the warning GHC also reports the inferred type. The
1463 option is off by default.</para>
1464 </listitem>
1465 </varlistentry>
1466
1467 <varlistentry>
1468 <term><option>-fwarn-missing-local-sigs</option>:</term>
1469 <listitem>
1470 <indexterm><primary><option>-fwarn-missing-local-sigs</option></primary></indexterm>
1471 <indexterm><primary>type signatures, missing</primary></indexterm>
1472
1473 <para>If you use the
1474 <option>-fwarn-missing-local-sigs</option> flag GHC will warn
1475 you about any polymorphic local bindings. As part of
1476 the warning GHC also reports the inferred type. The
1477 option is off by default.</para>
1478 </listitem>
1479 </varlistentry>
1480
1481 <varlistentry>
1482 <term><option>-fwarn-name-shadowing</option>:</term>
1483 <listitem>
1484 <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
1485 <indexterm><primary>shadowing, warning</primary></indexterm>
1486
1487 <para>This option causes a warning to be emitted whenever an
1488 inner-scope value has the same name as an outer-scope value,
1489 i.e. the inner value shadows the outer one. This can catch
1490 typographical errors that turn into hard-to-find bugs, e.g.,
1491 in the inadvertent capture of what would be a recursive call in
1492 <literal>f = ... let f = id in ... f ...</literal>.</para>
1493 <para>The warning is suppressed for names beginning with an underscore. For example
1494 <programlisting>
1495 f x = do { _ignore &lt;- this; _ignore &lt;- that; return (the other) }
1496 </programlisting>
1497 </para>
1498 </listitem>
1499 </varlistentry>
1500
1501 <varlistentry>
1502 <term><option>-fwarn-orphans, -fwarn-auto-orphans</option>:</term>
1503 <listitem>
1504 <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm>
1505 <indexterm><primary><option>-fwarn-auto-orphans</option></primary></indexterm>
1506 <indexterm><primary>orphan instances, warning</primary></indexterm>
1507 <indexterm><primary>orphan rules, warning</primary></indexterm>
1508
1509 <para>These flags cause a warning to be emitted whenever the
1510 module contains an "orphan" instance declaration or rewrite rule.
1511 An instance declaration is an orphan if it appears in a module in
1512 which neither the class nor the type being instanced are declared
1513 in the same module. A rule is an orphan if it is a rule for a
1514 function declared in another module. A module containing any
1515 orphans is called an orphan module.</para>
1516 <para>The trouble with orphans is that GHC must pro-actively read the interface
1517 files for all orphan modules, just in case their instances or rules
1518 play a role, whether or not the module's interface would otherwise
1519 be of any use. See <xref linkend="orphan-modules"/> for details.
1520 </para>
1521 <para>The flag <option>-fwarn-orphans</option> warns about user-written
1522 orphan rules or instances. The flag <option>-fwarn-auto-orphans</option>
1523 warns about automatically-generated orphan rules, notably as a result of
1524 specialising functions, for type classes (<literal>Specialise</literal>)
1525 or argument values (<literal>SpecConstr</literal>).</para>
1526 </listitem>
1527 </varlistentry>
1528
1529 <varlistentry>
1530 <term>
1531 <option>-fwarn-overlapping-patterns</option>:
1532 <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
1533 <indexterm><primary>overlapping patterns, warning</primary></indexterm>
1534 <indexterm><primary>patterns, overlapping</primary></indexterm>
1535 </term>
1536 <listitem>
1537 <para>By default, the compiler will warn you if a set of
1538 patterns are overlapping, e.g.,</para>
1539
1540 <programlisting>
1541 f :: String -&#62; Int
1542 f [] = 0
1543 f (_:xs) = 1
1544 f "2" = 2
1545 </programlisting>
1546
1547 <para>where the last pattern match in <function>f</function>
1548 won't ever be reached, as the second pattern overlaps
1549 it. More often than not, redundant patterns is a programmer
1550 mistake/error, so this option is enabled by default.</para>
1551 </listitem>
1552 </varlistentry>
1553
1554 <varlistentry>
1555 <term><option>-fwarn-tabs</option>:</term>
1556 <listitem>
1557 <indexterm><primary><option>-fwarn-tabs</option></primary></indexterm>
1558 <indexterm><primary>tabs, warning</primary></indexterm>
1559 <para>Have the compiler warn if there are tabs in your source
1560 file.</para>
1561
1562 <para>This warning is off by default.</para>
1563 </listitem>
1564 </varlistentry>
1565
1566 <varlistentry>
1567 <term><option>-fwarn-type-defaults</option>:</term>
1568 <listitem>
1569 <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
1570 <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
1571 <para>Have the compiler warn/inform you where in your source
1572 the Haskell defaulting mechanism for numeric types kicks
1573 in. This is useful information when converting code from a
1574 context that assumed one default into one with another,
1575 e.g., the &lsquo;default default&rsquo; for Haskell 1.4 caused the
1576 otherwise unconstrained value <constant>1</constant> to be
1577 given the type <literal>Int</literal>, whereas Haskell 98
1578 and later
1579 defaults it to <literal>Integer</literal>. This may lead to
1580 differences in performance and behaviour, hence the
1581 usefulness of being non-silent about this.</para>
1582
1583 <para>This warning is off by default.</para>
1584 </listitem>
1585 </varlistentry>
1586
1587 <varlistentry>
1588 <term><option>-fwarn-monomorphism-restriction</option>:</term>
1589 <listitem>
1590 <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm>
1591 <indexterm><primary>monomorphism restriction, warning</primary></indexterm>
1592 <para>Have the compiler warn/inform you where in your source
1593 the Haskell Monomorphism Restriction is applied. If applied silently
1594 the MR can give rise to unexpected behaviour, so it can be helpful
1595 to have an explicit warning that it is being applied.</para>
1596
1597 <para>This warning is off by default.</para>
1598 </listitem>
1599 </varlistentry>
1600
1601 <varlistentry>
1602 <term><option>-fwarn-unused-binds</option>:</term>
1603 <listitem>
1604 <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
1605 <indexterm><primary>unused binds, warning</primary></indexterm>
1606 <indexterm><primary>binds, unused</primary></indexterm>
1607 <para>Report any function definitions (and local bindings)
1608 which are unused. For top-level functions, the warning is
1609 only given if the binding is not exported.</para>
1610 <para>A definition is regarded as "used" if (a) it is exported, or (b) it is
1611 mentioned in the right hand side of another definition that is used, or (c) the
1612 function it defines begins with an underscore. The last case provides a
1613 way to suppress unused-binding warnings selectively. </para>
1614 <para> Notice that a variable
1615 is reported as unused even if it appears in the right-hand side of another
1616 unused binding. </para>
1617 </listitem>
1618 </varlistentry>
1619
1620 <varlistentry>
1621 <term><option>-fwarn-unused-imports</option>:</term>
1622 <listitem>
1623 <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
1624 <indexterm><primary>unused imports, warning</primary></indexterm>
1625 <indexterm><primary>imports, unused</primary></indexterm>
1626
1627 <para>Report any modules that are explicitly imported but
1628 never used. However, the form <literal>import M()</literal> is
1629 never reported as an unused import, because it is a useful idiom
1630 for importing instance declarations, which are anonymous in Haskell.</para>
1631 </listitem>
1632 </varlistentry>
1633
1634 <varlistentry>
1635 <term><option>-fwarn-unused-matches</option>:</term>
1636 <listitem>
1637 <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
1638 <indexterm><primary>unused matches, warning</primary></indexterm>
1639 <indexterm><primary>matches, unused</primary></indexterm>
1640
1641 <para>Report all unused variables which arise from pattern
1642 matches, including patterns consisting of a single variable.
1643 For instance <literal>f x y = []</literal> would report
1644 <varname>x</varname> and <varname>y</varname> as unused. The
1645 warning is suppressed if the variable name begins with an underscore, thus:
1646 <programlisting>
1647 f _x = True
1648 </programlisting>
1649 </para>
1650 </listitem>
1651 </varlistentry>
1652
1653 <varlistentry>
1654 <term><option>-fwarn-unused-do-bind</option>:</term>
1655 <listitem>
1656 <indexterm><primary><option>-fwarn-unused-do-bind</option></primary></indexterm>
1657 <indexterm><primary>unused do binding, warning</primary></indexterm>
1658 <indexterm><primary>do binding, unused</primary></indexterm>
1659
1660 <para>Report expressions occurring in <literal>do</literal> and <literal>mdo</literal> blocks
1661 that appear to silently throw information away.
1662 For instance <literal>do { mapM popInt xs ; return 10 }</literal> would report
1663 the first statement in the <literal>do</literal> block as suspicious,
1664 as it has the type <literal>StackM [Int]</literal> and not <literal>StackM ()</literal>, but that
1665 <literal>[Int]</literal> value is not bound to anything. The warning is suppressed by
1666 explicitly mentioning in the source code that your program is throwing something away:
1667 <programlisting>
1668 do { _ &lt;- mapM popInt xs ; return 10 }
1669 </programlisting>
1670 Of course, in this particular situation you can do even better:
1671 <programlisting>
1672 do { mapM_ popInt xs ; return 10 }
1673 </programlisting>
1674 </para>
1675 </listitem>
1676 </varlistentry>
1677
1678 <varlistentry>
1679 <term><option>-fwarn-wrong-do-bind</option>:</term>
1680 <listitem>
1681 <indexterm><primary><option>-fwarn-wrong-do-bind</option></primary></indexterm>
1682 <indexterm><primary>apparently erroneous do binding, warning</primary></indexterm>
1683 <indexterm><primary>do binding, apparently erroneous</primary></indexterm>
1684
1685 <para>Report expressions occurring in <literal>do</literal> and <literal>mdo</literal> blocks
1686 that appear to lack a binding.
1687 For instance <literal>do { return (popInt 10) ; return 10 }</literal> would report
1688 the first statement in the <literal>do</literal> block as suspicious,
1689 as it has the type <literal>StackM (StackM Int)</literal> (which consists of two nested applications
1690 of the same monad constructor), but which is not then &quot;unpacked&quot; by binding the result.
1691 The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away:
1692 <programlisting>
1693 do { _ &lt;- return (popInt 10) ; return 10 }
1694 </programlisting>
1695 For almost all sensible programs this will indicate a bug, and you probably intended to write:
1696 <programlisting>
1697 do { popInt 10 ; return 10 }
1698 </programlisting>
1699 </para>
1700 </listitem>
1701 </varlistentry>
1702
1703 <varlistentry>
1704 <term><option>-fwarn-typeable-instances</option>:</term>
1705 <listitem>
1706 <indexterm><primary><option>-fwarn-typeable-instances</option></primary></indexterm>
1707 <indexterm><primary>typeable instances, warning</primary></indexterm>
1708
1709 <para>Report handwritten (ie. not derived) instances of the
1710 <literal>Typeable</literal> class. These are ignore by the compiler;
1711 only derived instances of <literal>Typeable</literal> are allowed.
1712 </para>
1713 </listitem>
1714 </varlistentry>
1715
1716 </variablelist>
1717
1718 <para>If you're feeling really paranoid, the
1719 <option>-dcore-lint</option>
1720 option<indexterm><primary><option>-dcore-lint</option></primary></indexterm>
1721 is a good choice. It turns on heavyweight intra-pass
1722 sanity-checking within GHC. (It checks GHC's sanity, not
1723 yours.)</para>
1724
1725 </sect1>
1726
1727 &packages;
1728
1729 <sect1 id="options-optimise">
1730 <title>Optimisation (code improvement)</title>
1731
1732 <indexterm><primary>optimisation</primary></indexterm>
1733 <indexterm><primary>improvement, code</primary></indexterm>
1734
1735 <para>The <option>-O*</option> options specify convenient
1736 &ldquo;packages&rdquo; of optimisation flags; the
1737 <option>-f*</option> options described later on specify
1738 <emphasis>individual</emphasis> optimisations to be turned on/off;
1739 the <option>-m*</option> options specify
1740 <emphasis>machine-specific</emphasis> optimisations to be turned
1741 on/off.</para>
1742
1743 <sect2 id="optimise-pkgs">
1744 <title><option>-O*</option>: convenient &ldquo;packages&rdquo; of optimisation flags.</title>
1745
1746 <para>There are <emphasis>many</emphasis> options that affect
1747 the quality of code produced by GHC. Most people only have a
1748 general goal, something like &ldquo;Compile quickly&rdquo; or
1749 &ldquo;Make my program run like greased lightning.&rdquo; The
1750 following &ldquo;packages&rdquo; of optimisations (or lack
1751 thereof) should suffice.</para>
1752
1753 <para>Note that higher optimisation levels cause more
1754 cross-module optimisation to be performed, which can have an
1755 impact on how much of your program needs to be recompiled when
1756 you change something. This is one reason to stick to
1757 no-optimisation when developing code.</para>
1758
1759 <variablelist>
1760
1761 <varlistentry>
1762 <term>
1763 No <option>-O*</option>-type option specified:
1764 <indexterm><primary>-O* not specified</primary></indexterm>
1765 </term>
1766 <listitem>
1767 <para>This is taken to mean: &ldquo;Please compile
1768 quickly; I'm not over-bothered about compiled-code
1769 quality.&rdquo; So, for example: <command>ghc -c
1770 Foo.hs</command></para>
1771 </listitem>
1772 </varlistentry>
1773
1774 <varlistentry>
1775 <term>
1776 <option>-O0</option>:
1777 <indexterm><primary><option>-O0</option></primary></indexterm>
1778 </term>
1779 <listitem>
1780 <para>Means &ldquo;turn off all optimisation&rdquo;,
1781 reverting to the same settings as if no
1782 <option>-O</option> options had been specified. Saying
1783 <option>-O0</option> can be useful if
1784 eg. <command>make</command> has inserted a
1785 <option>-O</option> on the command line already.</para>
1786 </listitem>
1787 </varlistentry>
1788
1789 <varlistentry>
1790 <term>
1791 <option>-O</option> or <option>-O1</option>:
1792 <indexterm><primary>-O option</primary></indexterm>
1793 <indexterm><primary>-O1 option</primary></indexterm>
1794 <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
1795 </term>
1796 <listitem>
1797 <para>Means: &ldquo;Generate good-quality code without
1798 taking too long about it.&rdquo; Thus, for example:
1799 <command>ghc -c -O Main.lhs</command></para>
1800 </listitem>
1801 </varlistentry>
1802
1803 <varlistentry>
1804 <term>
1805 <option>-O2</option>:
1806 <indexterm><primary>-O2 option</primary></indexterm>
1807 <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
1808 </term>
1809 <listitem>
1810 <para>Means: &ldquo;Apply every non-dangerous
1811 optimisation, even if it means significantly longer
1812 compile times.&rdquo;</para>
1813
1814 <para>The avoided &ldquo;dangerous&rdquo; optimisations
1815 are those that can make runtime or space
1816 <emphasis>worse</emphasis> if you're unlucky. They are
1817 normally turned on or off individually.</para>
1818
1819 <para>At the moment, <option>-O2</option> is
1820 <emphasis>unlikely</emphasis> to produce better code than
1821 <option>-O</option>.</para>
1822 </listitem>
1823 </varlistentry>
1824 </variablelist>
1825
1826 <para>We don't use a <option>-O*</option> flag for day-to-day
1827 work. We use <option>-O</option> to get respectable speed;
1828 e.g., when we want to measure something. When we want to go for
1829 broke, we tend to use <option>-O2</option> (and we go for
1830 lots of coffee breaks).</para>
1831
1832 <para>The easiest way to see what <option>-O</option> (etc.)
1833 &ldquo;really mean&rdquo; is to run with <option>-v</option>,
1834 then stand back in amazement.</para>
1835 </sect2>
1836
1837 <sect2 id="options-f">
1838 <title><option>-f*</option>: platform-independent flags</title>
1839
1840 <indexterm><primary>-f* options (GHC)</primary></indexterm>
1841 <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
1842
1843 <para>These flags turn on and off individual optimisations.
1844 They are normally set via the <option>-O</option> options
1845 described above, and as such, you shouldn't need to set any of
1846 them explicitly (indeed, doing so could lead to unexpected
1847 results). A flag <option>-fwombat</option> can be negated by
1848 saying <option>-fno-wombat</option>. The flags below are off
1849 by default, except where noted below.
1850 </para>
1851
1852 <variablelist>
1853 <varlistentry>
1854 <term>
1855 <option>-fcse</option>
1856 <indexterm><primary><option>-fcse</option></primary></indexterm>
1857 </term>
1858 <listitem>
1859 <para><emphasis>On by default.</emphasis>. Enables the common-sub-expression
1860 elimination optimisation.
1861 Switching this off can be useful if you have some <literal>unsafePerformIO</literal>
1862 expressions that you don't want commoned-up.</para>
1863 </listitem>
1864 </varlistentry>
1865
1866 <varlistentry>
1867 <term>
1868 <option>-fstrictness</option>
1869 <indexterm><primary><option></option></primary></indexterm>
1870 </term>
1871 <listitem>
1872 <para> <emphasis>On by default.</emphasis>.
1873 Switch on the strictness analyser. There is a very old paper about GHC's
1874 strictness analyser, <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/simple-strictnes-analyser.ps.gz">
1875 Measuring the effectiveness of a simple strictness analyser</ulink>,
1876 but the current one is quite a bit different.
1877 </para>
1878
1879 <para>The strictness analyser figures out when arguments and
1880 variables in a function can be treated 'strictly' (that is they
1881 are always evaluated in the function at some point). This allow
1882 GHC to apply certain optimisations such as unboxing that
1883 otherwise don't apply as they change the semantics of the program
1884 when applied to lazy arguments.
1885 </para>
1886 </listitem>
1887 </varlistentry>
1888
1889 <varlistentry>
1890 <term>
1891 <option>-funbox-strict-fields</option>:
1892 <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
1893 <indexterm><primary>strict constructor fields</primary></indexterm>
1894 <indexterm><primary>constructor fields, strict</primary></indexterm>
1895 </term>
1896 <listitem>
1897 <para>This option causes all constructor fields which are marked
1898 strict (i.e. &ldquo;!&rdquo;) to be unpacked if possible. It is
1899 equivalent to adding an <literal>UNPACK</literal> pragma to every
1900 strict constructor field (see <xref linkend="unpack-pragma"/>).
1901 </para>
1902
1903 <para>This option is a bit of a sledgehammer: it might sometimes
1904 make things worse. Selectively unboxing fields by using
1905 <literal>UNPACK</literal> pragmas might be better. An alternative
1906 is to use <option>-funbox-strict-fields</option> to turn on
1907 unboxing by default but disable it for certain constructor
1908 fields using the <literal>NOUNPACK</literal> pragma (see
1909 <xref linkend="nounpack-pragma"/>).</para>
1910 </listitem>
1911 </varlistentry>
1912
1913 <varlistentry>
1914 <term>
1915 <option>-funbox-small-strict-fields</option>:
1916 <indexterm><primary><option>-funbox-small-strict-fields</option></primary></indexterm>
1917 <indexterm><primary>strict constructor fields</primary></indexterm>
1918 <indexterm><primary>constructor fields, strict</primary></indexterm>
1919 </term>
1920 <listitem>
1921 <para><emphasis>On by default.</emphasis>. This option
1922 causes all constructor fields which are marked strict
1923 (i.e. &ldquo;!&rdquo;) and which representation is smaller
1924 or equal to the size of a pointer to be unpacked, if
1925 possible. It is equivalent to adding an
1926 <literal>UNPACK</literal> pragma (see <xref
1927 linkend="unpack-pragma"/>) to every strict constructor
1928 field that fulfils the size restriction.
1929 </para>
1930
1931 <para>For example, the constructor fields in the following
1932 data types
1933 <programlisting>
1934 data A = A !Int
1935 data B = B !A
1936 newtype C = C B
1937 data D = D !C
1938 </programlisting>
1939 would all be represented by a single
1940 <literal>Int#</literal> (see <xref linkend="primitives"/>)
1941 value with
1942 <option>-funbox-small-strict-fields</option> enabled.
1943 </para>
1944
1945 <para>This option is less of a sledgehammer than
1946 <option>-funbox-strict-fields</option>: it should rarely make things
1947 worse. If you use <option>-funbox-small-strict-fields</option>
1948 to turn on unboxing by default you can disable it for certain
1949 constructor fields using the <literal>NOUNPACK</literal> pragma (see
1950 <xref linkend="nounpack-pragma"/>).</para>
1951
1952 <para>
1953 Note that for consistency <literal>Double</literal>,
1954 <literal>Word64</literal>, and <literal>Int64</literal> constructor
1955 fields are unpacked on 32-bit platforms, even though they are
1956 technically larger than a pointer on those platforms.
1957 </para>
1958 </listitem>
1959 </varlistentry>
1960
1961 <varlistentry>
1962 <term>
1963 <option>-fspec-constr</option>
1964 <indexterm><primary><option>-fspec-constr</option></primary></indexterm>
1965 </term>
1966 <listitem>
1967 <para><emphasis>Off by default, but enabled by -O2.</emphasis>
1968 Turn on call-pattern specialisation; see
1969 <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm">
1970 Call-pattern specialisation for Haskell programs</ulink>.
1971 </para>
1972
1973 <para>This optimisation specializes recursive functions according to
1974 their argument "shapes". This is best explained by example so
1975 consider:
1976 <programlisting>
1977 last :: [a] -> a
1978 last [] = error "last"
1979 last (x : []) = x
1980 last (x : xs) = last xs
1981 </programlisting>
1982 In this code, once we pass the initial check for an empty list we
1983 know that in the recursive case this pattern match is redundant. As
1984 such <option>-fspec-constr</option> will transform the above code
1985 to:
1986 <programlisting>
1987 last :: [a] -> a
1988 last [] = error "last"
1989 last (x : xs) = last' x xs
1990 where
1991 last' x [] = x
1992 last' x (y : ys) = last' y ys
1993 </programlisting>
1994 </para>
1995
1996 <para>As well avoid unnecessary pattern matching it also helps avoid
1997 unnecessary allocation. This applies when a argument is strict in
1998 the recursive call to itself but not on the initial entry. As
1999 strict recursive branch of the function is created similar to the
2000 above example.
2001 </para>
2002 </listitem>
2003 </varlistentry>
2004
2005 <varlistentry>
2006 <term>
2007 <option>-fspecialise</option>
2008 <indexterm><primary><option>-fspecialise</option></primary></indexterm>
2009 </term>
2010 <listitem>
2011 <para><emphasis>On by default.</emphasis>
2012 Specialise each type-class-overloaded function defined in this
2013 module for the types at which it is called in this module. Also
2014 specialise imported functions that have an INLINABLE pragma
2015 (<xref linkend="inlinable-pragma"/>) for the types at which they
2016 are called in this module.
2017 </para>
2018 </listitem>
2019 </varlistentry>
2020
2021 <varlistentry>
2022 <term>
2023 <option>-fstatic-argument-transformation</option>
2024 <indexterm><primary><option>-fstatic-argument-transformation</option></primary></indexterm>
2025 </term>
2026 <listitem>
2027 <para>Turn on the static argument transformation, which turns a
2028 recursive function into a non-recursive one with a local
2029 recursive loop. See Chapter 7 of
2030 <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz">
2031 Andre Santos's PhD thesis</ulink>
2032 </para>
2033 </listitem>
2034 </varlistentry>
2035
2036 <varlistentry>
2037 <term>
2038 <option>-ffloat-in</option>
2039 <indexterm><primary><option></option></primary></indexterm>
2040 </term>
2041 <listitem>
2042 <para><emphasis>On by default.</emphasis>
2043 Float let-bindings inwards, nearer their binding site. See
2044 <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz">
2045 Let-floating: moving bindings to give faster programs (ICFP'96)</ulink>.
2046 </para>
2047
2048 <para>This optimisation moves let bindings closer to their use
2049 site. The benefit here is that this may avoid unnecessary
2050 allocation if the branch the let is now on is never executed. It
2051 also enables other optimisation passes to work more effectively
2052 as they have more information locally.
2053 </para>
2054
2055 <para>This optimisation isn't always beneficial though (so GHC
2056 applies some heuristics to decide when to apply it). The details
2057 get complicated but a simple example is that it is often beneficial
2058 to move let bindings outwards so that multiple let bindings can be
2059 grouped into a larger single let binding, effectively batching
2060 their allocation and helping the garbage collector and allocator.
2061 </para>
2062 </listitem>
2063 </varlistentry>
2064
2065 <varlistentry>
2066 <term>
2067 <option>-ffull-laziness</option>
2068 <indexterm><primary><option>-ffull-laziness</option></primary></indexterm>
2069 </term>
2070 <listitem>
2071 <para><emphasis>On by default.</emphasis>
2072 Run the full laziness optimisation (also known as let-floating),
2073 which floats let-bindings outside enclosing lambdas, in the hope
2074 they will be thereby be computed less often. See
2075 <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz">Let-floating:
2076 moving bindings to give faster programs (ICFP'96)</ulink>.
2077 Full laziness increases sharing, which can lead to increased memory
2078 residency.
2079 </para>
2080
2081 <para>NOTE: GHC doesn't implement complete full-laziness.
2082 When optimisation in on, and <option>-fno-full-laziness</option>
2083 is not given, some transformations that increase sharing are
2084 performed, such as extracting repeated computations from a loop.
2085 These are the same transformations that a fully lazy
2086 implementation would do, the difference is that GHC doesn't
2087 consistently apply full-laziness, so don't rely on it.
2088 </para>
2089 </listitem>
2090 </varlistentry>
2091
2092 <varlistentry>
2093 <term>
2094 <option>-fdo-lambda-eta-expansion</option>
2095 <indexterm><primary><option></option></primary></indexterm>
2096 </term>
2097 <listitem>
2098 <para><emphasis>On by default.</emphasis>
2099 Eta-expand let-bindings to increase their arity.
2100 </para>
2101 </listitem>
2102 </varlistentry>
2103
2104 <varlistentry>
2105 <term>
2106 <option>-fdo-eta-reduction</option>
2107 <indexterm><primary><option></option></primary></indexterm>
2108 </term>
2109 <listitem>
2110 <para><emphasis>On by default.</emphasis>
2111 Eta-reduce lambda expressions, if doing so gets rid of a whole
2112 group of lambdas.
2113 </para>
2114 </listitem>
2115 </varlistentry>
2116
2117 <varlistentry>
2118 <term>
2119 <option>-fcase-merge</option>
2120 <indexterm><primary><option></option></primary></indexterm>
2121 </term>
2122 <listitem>
2123 <para><emphasis>On by default.</emphasis>
2124 Merge immediately-nested case expressions that scrutinse the same variable. Example
2125 <programlisting>
2126 case x of
2127 Red -> e1
2128 _ -> case x of
2129 Blue -> e2
2130 Green -> e3
2131 ==>
2132 case x of
2133 Red -> e1
2134 Blue -> e2
2135 Green -> e2
2136 </programlisting>
2137 </para>
2138 </listitem>
2139 </varlistentry>
2140
2141 <varlistentry>
2142 <term>
2143 <option>-fliberate-case</option>
2144 <indexterm><primary><option>-fliberate-case</option></primary></indexterm>
2145 </term>
2146 <listitem>
2147 <para><emphasis>Off by default, but enabled by -O2.</emphasis>
2148 Turn on the liberate-case transformation. This unrolls recursive
2149 function once in its own RHS, to avoid repeated case analysis of
2150 free variables. It's a bit like the call-pattern specialiser
2151 (<option>-fspec-constr</option>) but for free variables rather than
2152 arguments.
2153 </para>
2154 </listitem>
2155 </varlistentry>
2156
2157 <varlistentry>
2158 <term>
2159 <option>-fdicts-cheap</option>
2160 <indexterm><primary><option></option></primary></indexterm>
2161 </term>
2162 <listitem>
2163 <para>A very experimental flag that makes dictionary-valued
2164 expressions seem cheap to the optimiser.
2165 </para>
2166 </listitem>
2167 </varlistentry>
2168
2169 <varlistentry>
2170 <term>
2171 <option>-feager-blackholing</option>
2172 <indexterm><primary><option></option></primary></indexterm>
2173 </term>
2174 <listitem>
2175 <para>Usually GHC black-holes a thunk only when it switches
2176 threads. This flag makes it do so as soon as the thunk is
2177 entered. See <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/">
2178 Haskell on a shared-memory multiprocessor</ulink>.
2179 </para>
2180 </listitem>
2181 </varlistentry>
2182
2183 <varlistentry>
2184 <term>
2185 <option>-fno-state-hack</option>
2186 <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
2187 </term>
2188 <listitem>
2189 <para>Turn off the "state hack" whereby any lambda with a
2190 <literal>State#</literal> token as argument is considered to be
2191 single-entry, hence it is considered OK to inline things inside
2192 it. This can improve performance of IO and ST monad code, but it
2193 runs the risk of reducing sharing.
2194 </para>
2195 </listitem>
2196 </varlistentry>
2197
2198 <varlistentry>
2199 <term>
2200 <option>-fpedantic-bottoms</option>
2201 <indexterm><primary><option>-fpedantic-bottoms</option></primary></indexterm>
2202 </term>
2203 <listitem>
2204 <para>Make GHC be more precise about its treatment of bottom (but see also
2205 <option>-fno-state-hack</option>). In particular, stop GHC
2206 eta-expanding through a case expression, which is good for
2207 performance, but bad if you are using <literal>seq</literal> on
2208 partial applications.
2209 </para>
2210 </listitem>
2211 </varlistentry>
2212
2213 <varlistentry>
2214 <term>
2215 <option>-fsimpl-tick-factor=<replaceable>n</replaceable></option>
2216 <indexterm><primary><option>-fsimpl-tick-factor</option></primary></indexterm>
2217 </term>
2218 <listitem>
2219 <para>GHC's optimiser can diverge if you write rewrite rules (
2220 <xref linkend="rewrite-rules"/>) that don't terminate, or (less
2221 satisfactorily) if you code up recursion through data types
2222 (<xref linkend="bugs-ghc"/>). To avoid making the compiler fall
2223 into an infinite loop, the optimiser carries a "tick count" and
2224 stops inlining and applying rewrite rules when this count is
2225 exceeded. The limit is set as a multiple of the program size, so
2226 bigger programs get more ticks. The
2227 <option>-fsimpl-tick-factor</option> flag lets you change the
2228 multiplier. The default is 100; numbers larger than 100 give more
2229 ticks, and numbers smaller than 100 give fewer.
2230 </para>
2231
2232 <para>If the tick-count expires, GHC summarises what simplifier
2233 steps it has done; you can use
2234 <option>-fddump-simpl-stats</option> to generate a much more
2235 detailed list. Usually that identifies the loop quite
2236 accurately, because some numbers are very large.
2237 </para>
2238 </listitem>
2239 </varlistentry>
2240
2241 <varlistentry>
2242 <term>
2243 <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
2244 <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
2245 <indexterm><primary>inlining, controlling</primary></indexterm>
2246 <indexterm><primary>unfolding, controlling</primary></indexterm>
2247 </term>
2248 <listitem>
2249 <para>(Default: 45) Governs the maximum size that GHC will allow a
2250 function unfolding to be. (An unfolding has a &ldquo;size&rdquo;
2251 that reflects the cost in terms of &ldquo;code bloat&rdquo; of
2252 expanding (aka inlining) that unfolding at a call site. A bigger
2253 function would be assigned a bigger cost.)
2254 </para>
2255
2256 <para>Consequences: (a) nothing larger than this will be inlined
2257 (unless it has an INLINE pragma); (b) nothing larger than this
2258 will be spewed into an interface file.
2259 </para>
2260
2261 <para>Increasing this figure is more likely to result in longer
2262 compile times than faster code. The
2263 <option>-funfolding-use-threshold</option> is more useful.
2264 </para>
2265 </listitem>
2266 </varlistentry>
2267
2268 <varlistentry>
2269 <term>
2270 <option>-funfolding-use-threshold=<replaceable>n</replaceable></option>
2271 <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
2272 <indexterm><primary>inlining, controlling</primary></indexterm>
2273 <indexterm><primary>unfolding, controlling</primary></indexterm>
2274 </term>
2275 <listitem>
2276 <para>(Default: 8) This is the magic cut-off figure for unfolding
2277 (aka inlining): below this size, a function definition will be
2278 unfolded at the call-site, any bigger and it won't. The size
2279 computed for a function depends on two things: the actual size of
2280 the expression minus any discounts that
2281 apply (see <option>-funfolding-con-discount</option>).
2282 </para>
2283
2284 <para>The difference between this and
2285 <option>-funfolding-creation-threshold</option> is that this one
2286 determines if a function definition will be inlined <emphasis>at
2287 a call site</emphasis>. The other option determines if a
2288 function definition will be kept around at all for potential
2289 inlining.
2290 </para>
2291 </listitem>
2292 </varlistentry>
2293
2294 <varlistentry>
2295 <term>
2296 <option>-fexpose-all-unfoldings</option>
2297 <indexterm><primary><option></option></primary></indexterm>
2298 </term>
2299 <listitem>
2300 <para>An experimental flag to expose all unfoldings, even for very
2301 large or recursive functions. This allows for all functions to be
2302 inlined while usually GHC would avoid inlining larger functions.
2303 </para>
2304 </listitem>
2305 </varlistentry>
2306
2307 <varlistentry>
2308 <term>
2309 <option>-fvectorise</option>
2310 <indexterm><primary><option></option></primary></indexterm>
2311 </term>
2312 <listitem>
2313 <para>Part of <link linkend="dph">Data Parallel Haskell
2314 (DPH)</link>.</para>
2315
2316 <para><emphasis>Off by default.</emphasis> Enable the
2317 <emphasis>vectorisation</emphasis> optimisation transformation. This
2318 optimisation transforms the nested data parallelism code of programs
2319 using DPH into flat data parallelism. Flat data parallel programs
2320 should have better load balancing, enable SIMD parallelism and
2321 friendlier cache behaviour.</para>
2322 </listitem>
2323 </varlistentry>
2324
2325 <varlistentry>
2326 <term>
2327 <option>-favoid-vect</option>
2328 <indexterm><primary><option></option></primary></indexterm>
2329 </term>
2330 <listitem>
2331 <para>Part of <link linkend="dph">Data Parallel Haskell
2332 (DPH)</link>.</para>
2333
2334 <para><emphasis>Off by default.</emphasis> Enable the
2335 <emphasis>vectorisation</emphasis> avoidance optimisation. This
2336 optimisation only works when used in combination with the
2337 <option>-fvectorise</option> transformation.</para>
2338
2339 <para>While vectorisation of code using DPH is often a big win, it
2340 can also produce worse results for some kinds of code. This
2341 optimisation modifies the vectorisation transformation to try to
2342 determine if a function would be better of unvectorised and if
2343 so, do just that.</para>
2344 </listitem>
2345 </varlistentry>
2346
2347 <varlistentry>
2348 <term>
2349 <option>-fregs-graph</option>
2350 <indexterm><primary><option></option></primary></indexterm>
2351 </term>
2352 <listitem>
2353 <para><emphasis>Off by default, but enabled by -O2. Only applies in
2354 combination with the native code generator.</emphasis>
2355 Use the graph colouring register allocator for register allocation
2356 in the native code generator. By default, GHC uses a simpler,
2357 faster linear register allocator. The downside being that the
2358 linear register allocator usually generates worse code.
2359 </para>
2360 </listitem>
2361 </varlistentry>
2362
2363 <varlistentry>
2364 <term>
2365 <option>-fregs-iterative</option>
2366 <indexterm><primary><option></option></primary></indexterm>
2367 </term>
2368 <listitem>
2369 <para><emphasis>Off by default, only applies in combination with
2370 the native code generator.</emphasis>
2371 Use the iterative coalescing graph colouring register allocator for
2372 register allocation in the native code generator. This is the same
2373 register allocator as the <option>-freg-graph</option> one but also
2374 enables iterative coalescing during register allocation.
2375 </para>
2376 </listitem>
2377 </varlistentry>
2378
2379 <varlistentry>
2380 <term>
2381 <option>-fexcess-precision</option>
2382 <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
2383 </term>
2384 <listitem>
2385 <para>When this option is given, intermediate floating
2386 point values can have a <emphasis>greater</emphasis>
2387 precision/range than the final type. Generally this is a
2388 good thing, but some programs may rely on the exact
2389 precision/range of
2390 <literal>Float</literal>/<literal>Double</literal> values
2391 and should not use this option for their compilation.</para>
2392
2393 <para>
2394 Note that the 32-bit x86 native code generator only
2395 supports excess-precision mode, so neither
2396 <option>-fexcess-precision</option> nor
2397 <option>-fno-excess-precision</option> has any effect.
2398 This is a known bug, see <xref linkend="bugs-ghc" />.
2399 </para>
2400 </listitem>
2401 </varlistentry>
2402
2403 <varlistentry>
2404 <term>
2405 <option>-fignore-asserts</option>
2406 <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
2407 </term>
2408 <listitem>
2409 <para>Causes GHC to ignore uses of the function
2410 <literal>Exception.assert</literal> in source code (in
2411 other words, rewriting <literal>Exception.assert p
2412 e</literal> to <literal>e</literal> (see <xref
2413 linkend="assertions"/>). This flag is turned on by
2414 <option>-O</option>.
2415 </para>
2416 </listitem>
2417 </varlistentry>
2418
2419 <varlistentry>
2420 <term>
2421 <option>-fignore-interface-pragmas</option>
2422 <indexterm><primary><option>-fignore-interface-pragmas</option></primary></indexterm>
2423 </term>
2424 <listitem>
2425 <para>Tells GHC to ignore all inessential information when reading interface files.
2426 That is, even if <filename>M.hi</filename> contains unfolding or strictness information
2427 for a function, GHC will ignore that information.</para>
2428 </listitem>
2429 </varlistentry>
2430
2431 <varlistentry>
2432 <term>
2433 <option>-fomit-interface-pragmas</option>
2434 <indexterm><primary><option>-fomit-interface-pragmas</option></primary></indexterm>
2435 </term>
2436 <listitem>
2437 <para>Tells GHC to omit all inessential information from the
2438 interface file generated for the module being compiled (say M).
2439 This means that a module importing M will see only the
2440 <emphasis>types</emphasis> of the functions that M exports, but
2441 not their unfoldings, strictness info, etc. Hence, for example,
2442 no function exported by M will be inlined into an importing module.
2443 The benefit is that modules that import M will need to be
2444 recompiled less often (only when M's exports change their type, not
2445 when they change their implementation).</para>
2446 </listitem>
2447 </varlistentry>
2448
2449 <varlistentry>
2450 <term>
2451 <option>-fomit-yields</option>
2452 <indexterm><primary><option>-fomit-yields</option></primary></indexterm>
2453 </term>
2454 <listitem>
2455 <para><emphasis>On by default.</emphasis> Tells GHC to omit
2456 heap checks when no allocation is being performed. While this improves
2457 binary sizes by about 5%, it also means that threads run in
2458 tight non-allocating loops will not get preempted in a timely
2459 fashion. If it is important to always be able to interrupt such
2460 threads, you should turn this optimization off. Consider also
2461 recompiling all libraries with this optimization turned off, if you
2462 need to guarantee interruptibility.
2463 </para>
2464 </listitem>
2465 </varlistentry>
2466
2467 </variablelist>
2468
2469 </sect2>
2470
2471 </sect1>
2472
2473 &code-gens;
2474
2475 &phases;
2476
2477 &shared_libs;
2478
2479 <sect1 id="using-concurrent">
2480 <title>Using Concurrent Haskell</title>
2481 <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
2482
2483 <para>GHC supports Concurrent Haskell by default, without requiring a
2484 special option or libraries compiled in a certain way. To get access to
2485 the support libraries for Concurrent Haskell, just import
2486 <ulink
2487 url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>. More information on Concurrent Haskell is provided in the documentation for that module.</para>
2488
2489 <para>
2490 Optionally, the program may be linked with
2491 the <option>-threaded</option> option (see
2492 <xref linkend="options-linker" />. This provides two benefits:
2493
2494 <itemizedlist>
2495 <listitem>
2496 <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be
2497 used, which allows threads to run in
2498 parallel<indexterm><primary>parallelism</primary></indexterm>
2499 on a
2500 multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm>
2501 or
2502 multicore<indexterm><primary>multicore</primary></indexterm>
2503 machine. See <xref linkend="using-smp" />.</para>
2504 </listitem>
2505 <listitem>
2506 <para>If a thread makes a foreign call (and the call is
2507 not marked <literal>unsafe</literal>), then other
2508 Haskell threads in the program will continue to run
2509 while the foreign call is in progress.
2510 Additionally, <literal>foreign export</literal>ed
2511 Haskell functions may be called from multiple OS
2512 threads simultaneously. See
2513 <xref linkend="ffi-threads" />.</para>
2514 </listitem>
2515 </itemizedlist>
2516 </para>
2517
2518 <para>The following RTS option(s) affect the behaviour of Concurrent
2519 Haskell programs:<indexterm><primary>RTS options, concurrent</primary></indexterm></para>
2520
2521 <variablelist>
2522 <varlistentry>
2523 <term><option>-C<replaceable>s</replaceable></option></term>
2524 <listitem>
2525 <para><indexterm><primary><option>-C<replaceable>s</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
2526 Sets the context switch interval to <replaceable>s</replaceable>
2527 seconds. A context switch will occur at the next heap block
2528 allocation after the timer expires (a heap block allocation occurs
2529 every 4k of allocation). With <option>-C0</option> or
2530 <option>-C</option>, context switches will occur as often as
2531 possible (at every heap block allocation). By default, context
2532 switches occur every 20ms.</para>
2533 </listitem>
2534 </varlistentry>
2535 </variablelist>
2536 </sect1>
2537
2538 <sect1 id="using-smp">
2539 <title>Using SMP parallelism</title>
2540 <indexterm><primary>parallelism</primary>
2541 </indexterm>
2542 <indexterm><primary>SMP</primary>
2543 </indexterm>
2544
2545 <para>GHC supports running Haskell programs in parallel on an SMP
2546 (symmetric multiprocessor).</para>
2547
2548 <para>There's a fine distinction between
2549 <emphasis>concurrency</emphasis> and <emphasis>parallelism</emphasis>:
2550 parallelism is all about making your program run
2551 <emphasis>faster</emphasis> by making use of multiple processors
2552 simultaneously. Concurrency, on the other hand, is a means of
2553 abstraction: it is a convenient way to structure a program that must
2554 respond to multiple asynchronous events.</para>
2555
2556 <para>However, the two terms are certainly related. By making use of
2557 multiple CPUs it is possible to run concurrent threads in parallel,
2558 and this is exactly what GHC's SMP parallelism support does. But it
2559 is also possible to obtain performance improvements with parallelism
2560 on programs that do not use concurrency. This section describes how to
2561 use GHC to compile and run parallel programs, in <xref
2562 linkend="lang-parallel" /> we describe the language features that affect
2563 parallelism.</para>
2564
2565 <sect2 id="parallel-compile-options">
2566 <title>Compile-time options for SMP parallelism</title>
2567
2568 <para>In order to make use of multiple CPUs, your program must be
2569 linked with the <option>-threaded</option> option (see <xref
2570 linkend="options-linker" />). Additionally, the following
2571 compiler options affect parallelism:</para>
2572
2573 <variablelist>
2574 <varlistentry>
2575 <term><option>-feager-blackholing</option></term>
2576 <indexterm><primary><option>-feager-blackholing</option></primary></indexterm>
2577 <listitem>
2578 <para>
2579 Blackholing is the act of marking a thunk (lazy
2580 computuation) as being under evaluation. It is useful for
2581 three reasons: firstly it lets us detect certain kinds of
2582 infinite loop (the <literal>NonTermination</literal>
2583 exception), secondly it avoids certain kinds of space
2584 leak, and thirdly it avoids repeating a computation in a
2585 parallel program, because we can tell when a computation
2586 is already in progress.</para>
2587
2588 <para>
2589 The option <option>-feager-blackholing</option> causes
2590 each thunk to be blackholed as soon as evaluation begins.
2591 The default is "lazy blackholing", whereby thunks are only
2592 marked as being under evaluation when a thread is paused
2593 for some reason. Lazy blackholing is typically more
2594 efficient (by 1-2&percnt; or so), because most thunks don't
2595 need to be blackholed. However, eager blackholing can
2596 avoid more repeated computation in a parallel program, and
2597 this often turns out to be important for parallelism.
2598 </para>
2599
2600 <para>
2601 We recommend compiling any code that is intended to be run
2602 in parallel with the <option>-feager-blackholing</option>
2603 flag.
2604 </para>
2605 </listitem>
2606 </varlistentry>
2607 </variablelist>
2608 </sect2>
2609
2610 <sect2 id="parallel-options">
2611 <title>RTS options for SMP parallelism</title>
2612
2613 <para>There are two ways to run a program on multiple
2614 processors:
2615 call <literal>Control.Concurrent.setNumCapabilities</literal> from your
2616 program, or use the RTS <option>-N</option> option.</para>
2617
2618 <variablelist>
2619 <varlistentry>
2620 <term><option>-N<optional><replaceable>x</replaceable></optional></option></term>
2621 <listitem>
2622 <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
2623 Use <replaceable>x</replaceable> simultaneous threads when
2624 running the program. Normally <replaceable>x</replaceable>
2625 should be chosen to match the number of CPU cores on the
2626 machine<footnote><para>Whether hyperthreading cores should be counted or not is an
2627 open question; please feel free to experiment and let us know what
2628 results you find.</para></footnote>. For example,
2629 on a dual-core machine we would probably use
2630 <literal>+RTS -N2 -RTS</literal>.</para>
2631
2632 <para>Omitting <replaceable>x</replaceable>,
2633 i.e. <literal>+RTS -N -RTS</literal>, lets the runtime
2634 choose the value of <replaceable>x</replaceable> itself
2635 based on how many processors are in your machine.</para>
2636
2637 <para>Be careful when using all the processors in your
2638 machine: if some of your processors are in use by other
2639 programs, this can actually harm performance rather than
2640 improve it.</para>
2641
2642 <para>Setting <option>-N</option> also has the effect of
2643 enabling the parallel garbage collector (see
2644 <xref linkend="rts-options-gc" />).</para>
2645
2646 <para>The current value of the <option>-N</option> option
2647 is available to the Haskell program
2648 via <literal>Control.Concurrent.getNumCapabilities</literal>, and
2649 it may be changed while the program is running by
2650 calling <literal>Control.Concurrent.setNumCapabilities</literal>.</para>
2651 </listitem>
2652 </varlistentry>
2653 </variablelist>
2654
2655 <para>The following options affect the way the runtime schedules
2656 threads on CPUs:</para>
2657
2658 <variablelist>
2659 <varlistentry>
2660 <term><option>-qa</option></term>
2661 <indexterm><primary><option>-qa</option></primary><secondary>RTS
2662 option</secondary></indexterm>
2663 <listitem>
2664 <para>Use the OS's affinity facilities to try to pin OS
2665 threads to CPU cores. This is an experimental feature,
2666 and may or may not be useful. Please let us know
2667 whether it helps for you!</para>
2668 </listitem>
2669 </varlistentry>
2670 <varlistentry>
2671 <term><option>-qm</option></term>
2672 <indexterm><primary><option>-qm</option></primary><secondary>RTS
2673 option</secondary></indexterm>
2674 <listitem>
2675 <para>Disable automatic migration for load balancing.
2676 Normally the runtime will automatically try to schedule
2677 threads across the available CPUs to make use of idle
2678 CPUs; this option disables that behaviour. Note that
2679 migration only applies to threads; sparks created
2680 by <literal>par</literal> are load-balanced separately
2681 by work-stealing.</para>
2682
2683 <para>
2684 This option is probably only of use for concurrent
2685 programs that explicitly schedule threads onto CPUs
2686 with <literal>Control.Concurrent.forkOn</literal>.
2687 </para>
2688 </listitem>
2689 </varlistentry>
2690 </variablelist>
2691 </sect2>
2692
2693 <sect2>
2694 <title>Hints for using SMP parallelism</title>
2695
2696 <para>Add the <literal>-s</literal> RTS option when
2697 running the program to see timing stats, which will help to tell you
2698 whether your program got faster by using more CPUs or not. If the user
2699 time is greater than
2700 the elapsed time, then the program used more than one CPU. You should
2701 also run the program without <literal>-N</literal> for
2702 comparison.</para>
2703
2704 <para>The output of <literal>+RTS -s</literal> tells you how
2705 many &ldquo;sparks&rdquo; were created and executed during the
2706 run of the program (see <xref linkend="rts-options-gc" />), which
2707 will give you an idea how well your <literal>par</literal>
2708 annotations are working.</para>
2709
2710 <para>GHC's parallelism support has improved in 6.12.1 as a
2711 result of much experimentation and tuning in the runtime
2712 system. We'd still be interested to hear how well it works
2713 for you, and we're also interested in collecting parallel
2714 programs to add to our benchmarking suite.</para>
2715 </sect2>
2716 </sect1>
2717
2718 <sect1 id="options-platform">
2719 <title>Platform-specific Flags</title>
2720
2721 <indexterm><primary>-m* options</primary></indexterm>
2722 <indexterm><primary>platform-specific options</primary></indexterm>
2723 <indexterm><primary>machine-specific options</primary></indexterm>
2724
2725 <para>Some flags only make sense for particular target
2726 platforms.</para>
2727
2728 <variablelist>
2729
2730 <varlistentry>
2731 <term><option>-msse2</option>:</term>
2732 <listitem>
2733 <para>
2734 (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
2735 instruction set to implement floating point operations when using
2736 the <link linkend="native-code-gen">native code generator</link>.
2737 This gives a substantial performance improvement for floating
2738 point, but the resulting compiled code
2739 will only run on processors that support SSE2 (Intel Pentium 4 and
2740 later, or AMD Athlon 64 and later). The
2741 <link linkend="llvm-code-gen">LLVM backend</link> will also use SSE2
2742 if your processor supports it but detects this automatically so no
2743 flag is required.
2744 </para>
2745 <para>
2746 SSE2 is unconditionally used on x86-64 platforms.
2747 </para>
2748 </listitem>
2749 </varlistentry>
2750
2751 <varlistentry>
2752 <term><option>-msse4.2</option>:</term>
2753 <listitem>
2754 <para>
2755 (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
2756 implement some floating point and bit operations when using the
2757 <link linkend="native-code-gen">native code generator</link>. The
2758 resulting compiled code will only run on processors that
2759 support SSE4.2 (Intel Core i7 and later). The
2760 <link linkend="llvm-code-gen">LLVM backend</link> will also use
2761 SSE4.2 if your processor supports it but detects this automatically
2762 so no flag is required.
2763 </para>
2764 </listitem>
2765 </varlistentry>
2766
2767 </variablelist>
2768
2769 </sect1>
2770
2771 &runtime;
2772
2773 <sect1 id="ext-core">
2774 <title>Generating and compiling External Core Files</title>
2775
2776 <indexterm><primary>intermediate code generation</primary></indexterm>
2777
2778 <para>GHC can dump its optimized intermediate code (said to be in &ldquo;Core&rdquo; format)
2779 to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix
2780 <filename>.hcr</filename>. The Core format is described in <ulink url="../../core.pdf">
2781 <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
2782 and sample tools
2783 for manipulating Core files (in Haskell) are available in the
2784 <ulink url="http://hackage.haskell.org/package/extcore">extcore package on Hackage</ulink>. Note that the format of <literal>.hcr</literal>
2785 files is <emphasis>different</emphasis> from the Core output format that GHC generates
2786 for debugging purposes (<xref linkend="options-debugging"/>), though the two formats appear somewhat similar.</para>
2787
2788 <para>The Core format natively supports notes which you can add to
2789 your source code using the <literal>CORE</literal> pragma (see <xref
2790 linkend="pragmas"/>).</para>
2791
2792 <variablelist>
2793
2794 <varlistentry>
2795 <term>
2796 <option>-fext-core</option>
2797 <indexterm><primary><option>-fext-core</option></primary></indexterm>
2798 </term>
2799 <listitem>
2800 <para>Generate <literal>.hcr</literal> files.</para>
2801 </listitem>
2802 </varlistentry>
2803
2804 </variablelist>
2805
2806 <para>Currently (as of version 6.8.2), GHC does not have the ability to read in External Core files as source. If you would like GHC to have this ability, please <ulink url="http://hackage.haskell.org/trac/ghc/wiki/MailingListsAndIRC">make your wishes known to the GHC Team</ulink>.</para>
2807
2808 </sect1>
2809
2810 &debug;
2811 &flags;
2812
2813 </chapter>
2814
2815 <!-- Emacs stuff:
2816 ;;; Local Variables: ***
2817 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
2818 ;;; End: ***
2819 -->