users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[ghc.git] / docs / users_guide / using.rst
1 .. _using-ghc:
2
3 Using GHC
4 =========
5
6 .. index::
7    single: GHC, using
8    single: using GHC
9
10 Getting started: compiling programs
11 -----------------------------------
12
13 In this chapter you'll find a complete reference to the GHC command-line
14 syntax, including all 400+ flags. It's a large and complex system, and
15 there are lots of details, so it can be quite hard to figure out how to
16 get started. With that in mind, this introductory section provides a
17 quick introduction to the basic usage of GHC for compiling a Haskell
18 program, before the following sections dive into the full syntax.
19
20 Let's create a Hello World program, and compile and run it. First,
21 create a file :file:`hello.hs` containing the Haskell code: ::
22
23     main = putStrLn "Hello, World!"
24
25 To compile the program, use GHC like this:
26
27 .. code-block:: sh
28
29     $ ghc hello.hs
30
31 (where ``$`` represents the prompt: don't type it). GHC will compile the
32 source file :file:`hello.hs`, producing an object file :file:`hello.o` and an
33 interface file :file:`hello.hi`, and then it will link the object file to
34 the libraries that come with GHC to produce an executable called
35 :file:`hello` on Unix/Linux/Mac, or :file:`hello.exe` on Windows.
36
37 By default GHC will be very quiet about what it is doing, only printing
38 error messages. If you want to see in more detail what's going on behind
39 the scenes, add :ghc-flag:`-v` to the command line.
40
41 Then we can run the program like this:
42
43 .. code-block:: sh
44
45     $ ./hello
46     Hello World!
47
48 If your program contains multiple modules, then you only need to tell
49 GHC the name of the source file containing the ``Main`` module, and GHC
50 will examine the ``import`` declarations to find the other modules that
51 make up the program and find their source files. This means that, with
52 the exception of the ``Main`` module, every source file should be named
53 after the module name that it contains (with dots replaced by directory
54 separators). For example, the module ``Data.Person`` would be in the
55 file ``Data/Person.hs`` on Unix/Linux/Mac, or ``Data\Person.hs`` on
56 Windows.
57
58 Options overview
59 ----------------
60
61 GHC's behaviour is controlled by options, which for historical reasons
62 are also sometimes referred to as command-line flags or arguments.
63 Options can be specified in three ways:
64
65 Command-line arguments
66 ~~~~~~~~~~~~~~~~~~~~~~
67
68 .. index::
69    single: structure, command-line
70    single: command-line; arguments
71    single: arguments; command-line
72
73 An invocation of GHC takes the following form:
74
75 .. code-block:: none
76
77     ghc [argument...]
78
79 Command-line arguments are either options or file names.
80
81 Command-line options begin with ``-``. They may *not* be grouped:
82 ``-vO`` is different from ``-v -O``. Options need not precede filenames:
83 e.g., ``ghc *.o -o foo``. All options are processed and then applied to
84 all files; you cannot, for example, invoke
85 ``ghc -c -O1 Foo.hs -O2 Bar.hs`` to apply different optimisation levels
86 to the files ``Foo.hs`` and ``Bar.hs``.
87
88 .. note::
89
90     .. index::
91        single: command-line; order of arguments
92
93     Note that command-line options are *order-dependent*, with arguments being
94     evaluated from left-to-right. This can have seemingly strange effects in the
95     presence of flag implication. For instance, consider
96     :ghc-flag:`-fno-specialise <-fspecialise>` and :ghc-flag:`-O1` (which implies
97     :ghc-flag:`-fspecialise`). These two command lines mean very different
98     things:
99
100     ``-fno-specialise -O1``
101
102         ``-fspecialise`` will be enabled as the ``-fno-specialise`` is overriden
103         by the ``-O1``.
104
105     ``-O1 -fno-specialise``
106
107         ``-fspecialise`` will not be enabled, since the ``-fno-specialise``
108         overrides the ``-fspecialise`` implied by ``-O1``.
109
110 .. _source-file-options:
111
112 Command line options in source files
113 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114
115 .. index::
116    single: source-file options
117
118 Sometimes it is useful to make the connection between a source file and
119 the command-line options it requires quite tight. For instance, if a
120 Haskell source file deliberately uses name shadowing, it should be
121 compiled with the ``-Wno-name-shadowing`` option. Rather than
122 maintaining the list of per-file options in a ``Makefile``, it is
123 possible to do this directly in the source file using the
124 ``OPTIONS_GHC`` :ref:`pragma <options-pragma>` ::
125
126     {-# OPTIONS_GHC -Wno-name-shadowing #-}
127     module X where
128     ...
129
130 ``OPTIONS_GHC`` is a *file-header pragma* (see :ref:`options-pragma`).
131
132 Only *dynamic* flags can be used in an ``OPTIONS_GHC`` pragma (see
133 :ref:`static-dynamic-flags`).
134
135 Note that your command shell does not get to the source file options,
136 they are just included literally in the array of command-line arguments
137 the compiler maintains internally, so you'll be desperately disappointed
138 if you try to glob etc. inside ``OPTIONS_GHC``.
139
140 .. note::
141    The contents of ``OPTIONS_GHC`` are appended to the command-line
142    options, so options given in the source file override those given on the
143    command-line.
144
145 It is not recommended to move all the contents of your Makefiles into
146 your source files, but in some circumstances, the ``OPTIONS_GHC`` pragma
147 is the Right Thing. (If you use :ghc-flag:`-keep-hc-file` and have ``OPTION`` flags in
148 your module, the ``OPTIONS_GHC`` will get put into the generated ``.hc`` file).
149
150 Setting options in GHCi
151 ~~~~~~~~~~~~~~~~~~~~~~~
152
153 Options may also be modified from within GHCi, using the :ghci-cmd:`:set`
154 command.
155
156 .. _static-dynamic-flags:
157
158 Static, Dynamic, and Mode options
159 ---------------------------------
160
161 .. index::
162    single: static; options
163    single: dynamic; options
164    single: mode; options
165
166 Each of GHC's command line options is classified as static, dynamic or
167 mode:
168
169     For example, :ghc-flag:`--make` or :ghc-flag:`-E`. There may only be a single mode
170     flag on the command line. The available modes are listed in
171     :ref:`modes`.
172
173     Most non-mode flags fall into this category. A dynamic flag may be
174     used on the command line, in a ``OPTIONS_GHC`` pragma in a source
175     file, or set using :ghci-cmd:`:set` in GHCi.
176
177     A few flags are "static", which means they can only be used on the
178     command-line, and remain in force over the entire GHC/GHCi run.
179
180 The flag reference tables (:ref:`flag-reference`) lists the status of
181 each flag.
182
183 There are a few flags that are static except that they can also be used
184 with GHCi's :ghci-cmd:`:set` command; these are listed as “static/\ ``:set``\ ”
185 in the table.
186
187 .. _file-suffixes:
188
189 Meaningful file suffixes
190 ------------------------
191
192 .. index::
193    single: suffixes, file
194    single: file suffixes for GHC
195
196 File names with "meaningful" suffixes (e.g., ``.lhs`` or ``.o``) cause
197 the "right thing" to happen to those files.
198
199 ``.hs``
200     A Haskell module.
201
202 ``.lhs``
203     .. index::
204        single: lhs file extension
205
206     A “literate Haskell” module.
207
208 ``.hspp``
209     A file created by the preprocessor.
210
211 ``.hi``
212     A Haskell interface file, probably compiler-generated.
213
214 ``.hc``
215     Intermediate C file produced by the Haskell compiler.
216
217 ``.c``
218     A C file not produced by the Haskell compiler.
219
220 ``.ll``
221     An llvm-intermediate-language source file, usually produced by the
222     compiler.
223
224 ``.bc``
225     An llvm-intermediate-language bitcode file, usually produced by the
226     compiler.
227
228 ``.s``
229     An assembly-language source file, usually produced by the compiler.
230
231 ``.o``
232     An object file, produced by an assembler.
233
234 Files with other suffixes (or without suffixes) are passed straight to
235 the linker.
236
237 .. _modes:
238
239 Modes of operation
240 ------------------
241
242 .. index::
243    single: help options
244
245 GHC's behaviour is firstly controlled by a mode flag. Only one of these
246 flags may be given, but it does not necessarily need to be the first
247 option on the command-line. For instance,
248
249 .. code-block:: none
250
251     $ ghc Main.hs --make -o my-application
252
253 If no mode flag is present, then GHC will enter :ghc-flag:`--make` mode
254 (:ref:`make-mode`) if there are any Haskell source files given on the
255 command line, or else it will link the objects named on the command line
256 to produce an executable.
257
258 The available mode flags are:
259
260 .. ghc-flag:: --interactive
261     :shortdesc: Interactive mode - normally used by just running ``ghci``;
262         see :ref:`ghci` for details.
263     :type: mode
264     :category: modes
265
266     .. index::
267        single: interactive mode
268        single: GHCi
269
270     Interactive mode, which is also available as :program:`ghci`. Interactive
271     mode is described in more detail in :ref:`ghci`.
272
273 .. ghc-flag:: --make
274     :shortdesc: Build a multi-module Haskell program, automatically figuring out
275         dependencies. Likely to be much easier, and faster, than using
276         ``make``; see :ref:`make-mode` for details.
277     :type: mode
278     :category: modes
279
280     .. index::
281        single: make mode; of GHC
282
283     In this mode, GHC will build a multi-module Haskell program
284     automatically, figuring out dependencies for itself. If you have a
285     straightforward Haskell program, this is likely to be much easier,
286     and faster, than using :command:`make`. Make mode is described in
287     :ref:`make-mode`.
288
289     This mode is the default if there are any Haskell source files
290     mentioned on the command line, and in this case the :ghc-flag:`--make`
291     option can be omitted.
292
293 .. ghc-flag:: -e ⟨expr⟩
294     :shortdesc: Evaluate ``expr``; see :ref:`eval-mode` for details.
295     :type: mode
296     :category: modes
297
298     .. index::
299        single: eval mode; of GHC
300
301     Expression-evaluation mode. This is very similar to interactive
302     mode, except that there is a single expression to evaluate (⟨expr⟩)
303     which is given on the command line. See :ref:`eval-mode` for more
304     details.
305
306 .. ghc-flag:: -E
307     :shortdesc: Stop after preprocessing (``.hspp`` file)
308     :type: mode
309     :category: phases
310
311     Stop after preprocessing (``.hspp`` file)
312
313 .. ghc-flag:: -C
314     :shortdesc: Stop after generating C (``.hc`` file)
315     :type: mode
316     :category: phases
317     
318     Stop after generating C (``.hc`` file)
319
320 .. ghc-flag:: -S
321     :shortdesc: Stop after generating assembly (``.s`` file)
322     :type: mode
323     :category: phases
324
325     Stop after generating assembly (``.s`` file)
326
327 .. ghc-flag:: -c
328     :shortdesc: Stop after generating object (``.o``) file
329     :type: mode
330     :category: phases
331     
332     Stop after generating object (``.o``) file
333
334     This is the traditional batch-compiler mode, in which GHC can
335     compile source files one at a time, or link objects together into an
336     executable. See :ref:`options-order`.
337
338 .. ghc-flag:: -M
339     :shortdesc: generate dependency information suitable for use in a
340         ``Makefile``; see :ref:`makefile-dependencies` for details.
341     :type: mode
342     :category: modes
343
344     .. index::
345         single: dependency-generation mode; of GHC
346
347     Dependency-generation mode. In this mode, GHC can be used to
348     generate dependency information suitable for use in a ``Makefile``.
349     See :ref:`makefile-dependencies`.
350
351 .. ghc-flag:: --frontend ⟨module⟩
352     :shortdesc: run GHC with the given frontend plugin; see
353         :ref:`frontend_plugins` for details.
354     :type: mode
355     :category: modes
356
357     .. index::
358         single: frontend plugins; using
359
360     Run GHC using the given frontend plugin. See :ref:`frontend_plugins` for
361     details.
362
363 .. ghc-flag:: --mk-dll
364     :shortdesc: DLL-creation mode (Windows only)
365     :type: mode
366     :category: modes
367
368     .. index::
369        single: DLL-creation mode
370
371     DLL-creation mode (Windows only). See :ref:`win32-dlls-create`.
372
373 .. ghc-flag:: --help
374               -?
375     :shortdesc: Display help
376     :type: mode
377     :category: modes
378
379     Cause GHC to spew a long usage message to standard output and then
380     exit.
381
382 .. ghc-flag:: --show-iface ⟨file⟩
383     :shortdesc: display the contents of an interface file.
384     :type: mode
385     :category: modes
386
387     Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For
388     example ``ghc --show-iface M.hi``.
389
390 .. ghc-flag:: --supported-extensions
391               --supported-languages
392     :shortdesc: display the supported language extensions
393     :type: mode
394     :category: modes
395
396     Print the supported language extensions.
397
398 .. ghc-flag:: --show-options
399     :shortdesc: display the supported command line options
400     :type: mode
401     :category: modes
402
403     Print the supported command line options. This flag can be used for
404     autocompletion in a shell.
405
406 .. ghc-flag:: --info
407     :shortdesc: display information about the compiler
408     :type: mode
409     :category: modes
410
411     Print information about the compiler.
412
413 .. ghc-flag:: --version
414               -V
415     :shortdesc: display GHC version
416     :type: mode
417     :category: modes
418
419     Print a one-line string including GHC's version number.
420
421 .. ghc-flag:: --numeric-version
422     :shortdesc: display GHC version (numeric only)
423     :type: mode
424     :category: modes
425
426     Print GHC's numeric version number only.
427
428 .. ghc-flag:: --print-libdir
429     :shortdesc: display GHC library directory
430     :type: mode
431     :category: modes
432
433     .. index::
434        single: libdir
435
436     Print the path to GHC's library directory. This is the top of the
437     directory tree containing GHC's libraries, interfaces, and include
438     files (usually something like ``/usr/local/lib/ghc-5.04`` on Unix).
439     This is the value of ``$libdir`` in the package
440     configuration file (see :ref:`packages`).
441
442 .. _make-mode:
443
444 Using ``ghc`` ``--make``
445 ~~~~~~~~~~~~~~~~~~~~~~~~
446
447 .. index::
448    single: --make; mode of GHC
449    single: separate compilation
450
451 In this mode, GHC will build a multi-module Haskell program by following
452 dependencies from one or more root modules (usually just ``Main``). For
453 example, if your ``Main`` module is in a file called :file:`Main.hs`, you
454 could compile and link the program like this:
455
456 .. code-block:: none
457
458     ghc --make Main.hs
459
460 In fact, GHC enters make mode automatically if there are any Haskell
461 source files on the command line and no other mode is specified, so in
462 this case we could just type
463
464 .. code-block:: none
465
466     ghc Main.hs
467
468 Any number of source file names or module names may be specified; GHC
469 will figure out all the modules in the program by following the imports
470 from these initial modules. It will then attempt to compile each module
471 which is out of date, and finally, if there is a ``Main`` module, the
472 program will also be linked into an executable.
473
474 The main advantages to using ``ghc --make`` over traditional
475 ``Makefile``\s are:
476
477 -  GHC doesn't have to be restarted for each compilation, which means it
478    can cache information between compilations. Compiling a multi-module
479    program with ``ghc --make`` can be up to twice as fast as running
480    ``ghc`` individually on each source file.
481
482 -  You don't have to write a ``Makefile``.
483
484    .. index::
485       single: Makefiles; avoiding
486
487 -  GHC re-calculates the dependencies each time it is invoked, so the
488    dependencies never get out of sync with the source.
489
490 -  Using the :ghc-flag:`-j[⟨n⟩]` flag, you can compile modules in parallel.
491    Specify ``-j ⟨n⟩`` to compile ⟨n⟩ jobs in parallel. If ⟨n⟩ is omitted, then
492    it defaults to the number of processors.
493
494 Any of the command-line options described in the rest of this chapter
495 can be used with ``--make``, but note that any options you give on the
496 command line will apply to all the source files compiled, so if you want
497 any options to apply to a single source file only, you'll need to use an
498 ``OPTIONS_GHC`` pragma (see :ref:`source-file-options`).
499
500 If the program needs to be linked with additional objects (say, some
501 auxiliary C code), then the object files can be given on the command
502 line and GHC will include them when linking the executable.
503
504 For backward compatibility with existing make scripts, when used in
505 combination with :ghc-flag:`-c`, the linking phase is omitted (same as
506 ``--make -no-link``).
507
508 Note that GHC can only follow dependencies if it has the source file
509 available, so if your program includes a module for which there is no
510 source file, even if you have an object and an interface file for the
511 module, then GHC will complain. The exception to this rule is for
512 package modules, which may or may not have source files.
513
514 The source files for the program don't all need to be in the same
515 directory; the :ghc-flag:`-i` option can be used to add directories to the
516 search path (see :ref:`search-path`).
517
518 .. ghc-flag:: -j[⟨n⟩]
519     :shortdesc: When compiling with :ghc-flag:`--make`, compile ⟨n⟩ modules
520         in parallel.
521     :type: dynamic
522     :category: misc
523
524     Perform compilation in parallel when possible. GHC will use up to ⟨N⟩
525     threads during compilation. If N is omitted, then it defaults to the
526     number of processors. Note that compilation of a module may not begin
527     until its dependencies have been built.
528
529 .. _eval-mode:
530
531 Expression evaluation mode
532 ~~~~~~~~~~~~~~~~~~~~~~~~~~
533
534 This mode is very similar to interactive mode, except that there is a
535 single expression to evaluate which is specified on the command line as
536 an argument to the ``-e`` option:
537
538 .. code-block:: none
539
540     ghc -e expr
541
542 Haskell source files may be named on the command line, and they will be
543 loaded exactly as in interactive mode. The expression is evaluated in
544 the context of the loaded modules.
545
546 For example, to load and run a Haskell program containing a module
547 ``Main``, we might say:
548
549 .. code-block:: none
550
551     ghc -e Main.main Main.hs
552
553 or we can just use this mode to evaluate expressions in the context of
554 the ``Prelude``:
555
556 .. code-block:: none
557
558     $ ghc -e "interact (unlines.map reverse.lines)"
559     hello
560     olleh
561
562 .. _options-order:
563
564 Batch compiler mode
565 ~~~~~~~~~~~~~~~~~~~
566
567 In *batch mode*, GHC will compile one or more source files given on the
568 command line.
569
570 The first phase to run is determined by each input-file suffix, and the
571 last phase is determined by a flag. If no relevant flag is present, then
572 go all the way through to linking. This table summarises:
573
574 +-----------------------------------+------------------------------+----------------------------+---------------------------+
575 | Phase of the compilation system   | Suffix saying “start here”   | Flag saying “stop after”   | (suffix of) output file   |
576 +===================================+==============================+============================+===========================+
577 | literate pre-processor            | ``.lhs``                     |                            | ``.hs``                   |
578 +-----------------------------------+------------------------------+----------------------------+---------------------------+
579 | C pre-processor (opt.)            | ``.hs`` (with ``-cpp``)      | ``-E``                     | ``.hspp``                 |
580 +-----------------------------------+------------------------------+----------------------------+---------------------------+
581 | Haskell compiler                  | ``.hs``                      | ``-C``, ``-S``             | ``.hc``, ``.s``           |
582 +-----------------------------------+------------------------------+----------------------------+---------------------------+
583 | C compiler (opt.)                 | ``.hc`` or ``.c``            | ``-S``                     | ``.s``                    |
584 +-----------------------------------+------------------------------+----------------------------+---------------------------+
585 | assembler                         | ``.s``                       | ``-c``                     | ``.o``                    |
586 +-----------------------------------+------------------------------+----------------------------+---------------------------+
587 | linker                            | ⟨other⟩                      |                            | ``a.out``                 |
588 +-----------------------------------+------------------------------+----------------------------+---------------------------+
589
590 .. index::
591    single: -C
592    single: -E
593    single: -S
594    single: -c
595
596 Thus, a common invocation would be:
597
598 .. code-block:: none
599
600     ghc -c Foo.hs
601
602 to compile the Haskell source file ``Foo.hs`` to an object file
603 ``Foo.o``.
604
605 .. note::
606    What the Haskell compiler proper produces depends on what backend
607    code generator is used. See :ref:`code-generators` for more details.
608
609 .. note::
610    Pre-processing is optional, the :ghc-flag:`-cpp` flag turns it
611    on. See :ref:`c-pre-processor` for more details.
612
613 .. note::
614    The option :ghc-flag:`-E` runs just the pre-processing passes of
615    the compiler, dumping the result in a file.
616
617 .. note::
618    The option :ghc-flag:`-C` is only available when GHC is built in
619    unregisterised mode. See :ref:`unreg` for more details.
620
621 .. _overriding-suffixes:
622
623 Overriding the default behaviour for a file
624 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
625
626 As described above, the way in which a file is processed by GHC depends on its
627 suffix. This behaviour can be overridden using the :ghc-flag:`-x ⟨suffix⟩`
628 option:
629
630 .. ghc-flag:: -x ⟨suffix⟩
631     :shortdesc: Override default behaviour for source files
632     :type: dynamic
633     :category: phases
634
635     Causes all files following this option on the command line to be
636     processed as if they had the suffix ⟨suffix⟩. For example, to
637     compile a Haskell module in the file ``M.my-hs``, use
638     ``ghc -c -x hs M.my-hs``.
639
640 .. _options-help:
641
642 Verbosity options
643 -----------------
644
645 .. index::
646    single: verbosity options
647
648 See also the ``--help``, ``--version``, ``--numeric-version``, and
649 ``--print-libdir`` modes in :ref:`modes`.
650
651 .. ghc-flag:: -v
652     :shortdesc: verbose mode (equivalent to ``-v3``)
653     :type: dynamic
654     :category: verbosity
655
656     The :ghc-flag:`-v` option makes GHC *verbose*: it reports its version number
657     and shows (on stderr) exactly how it invokes each phase of the
658     compilation system. Moreover, it passes the ``-v`` flag to most
659     phases; each reports its version number (and possibly some other
660     information).
661
662     Please, oh please, use the ``-v`` option when reporting bugs!
663     Knowing that you ran the right bits in the right order is always the
664     first thing we want to verify.
665
666 .. ghc-flag:: -v⟨n⟩
667     :shortdesc: set verbosity level
668     :type: dynamic
669     :category: verbosity
670
671     To provide more control over the compiler's verbosity, the ``-v``
672     flag takes an optional numeric argument. Specifying ``-v`` on its
673     own is equivalent to ``-v3``, and the other levels have the
674     following meanings:
675
676     ``-v0``
677         Disable all non-essential messages (this is the default).
678
679     ``-v1``
680         Minimal verbosity: print one line per compilation (this is the
681         default when :ghc-flag:`--make` or :ghc-flag:`--interactive` is on).
682
683     ``-v2``
684         Print the name of each compilation phase as it is executed.
685         (equivalent to :ghc-flag:`-dshow-passes`).
686
687     ``-v3``
688         The same as ``-v2``, except that in addition the full command
689         line (if appropriate) for each compilation phase is also
690         printed.
691
692     ``-v4``
693         The same as ``-v3`` except that the intermediate program
694         representation after each compilation phase is also printed
695         (excluding preprocessed and C/assembly files).
696
697 .. ghc-flag:: -fprint-potential-instances
698     :shortdesc: display all available instances in type error messages
699     :type: dynamic
700     :reverse: -fno-print-potential-instances
701     :category: verbosity
702
703     When GHC can't find an instance for a class, it displays a short
704     list of some in the instances it knows about. With this flag it
705     prints *all* the instances it knows about.
706
707 .. ghc-flag:: -fhide-source-paths
708     :shortdesc: hide module source and object paths
709     :type: dynamic
710     :category: verbosity
711
712     Starting with minimal verbosity (``-v1``, see :ghc-flag:`-v`), GHC
713     displays the name, the source path and the target path of each compiled
714     module. This flag can be used to reduce GHC's output by hiding source paths
715     and target paths.
716
717 The following flags control the way in which GHC displays types in error
718 messages and in GHCi:
719
720 .. ghc-flag:: -fprint-unicode-syntax
721     :shortdesc: Use unicode syntax when printing expressions, types and kinds.
722         See also :ghc-flag:`-XUnicodeSyntax`
723     :type: dynamic
724     :reverse: -fno-print-unicode-syntax
725     :category: verbosity
726
727     When enabled GHC prints type signatures using the unicode symbols from the
728     :ghc-flag:`-XUnicodeSyntax` extension. For instance,
729
730     .. code-block:: none
731
732         ghci> :set -fprint-unicode-syntax
733         ghci> :t +v (>>)
734         (>>) ∷ Monad m ⇒ ∀ a b. m a → m b → m b
735
736 .. _pretty-printing-types:
737
738 .. ghc-flag:: -fprint-explicit-foralls
739     :shortdesc: Print explicit ``forall`` quantification in types.
740         See also :ghc-flag:`-XExplicitForAll`
741     :type: dynamic
742     :reverse: -fno-print-explicit-foralls
743     :category: verbosity
744
745     Using :ghc-flag:`-fprint-explicit-foralls` makes
746     GHC print explicit ``forall`` quantification at the top level of a
747     type; normally this is suppressed. For example, in GHCi:
748
749     .. code-block:: none
750
751         ghci> let f x = x
752         ghci> :t f
753         f :: a -> a
754         ghci> :set -fprint-explicit-foralls
755         ghci> :t f
756         f :: forall a. a -> a
757
758     However, regardless of the flag setting, the quantifiers are printed
759     under these circumstances:
760
761     -  For nested ``foralls``, e.g.
762
763        .. code-block:: none
764
765            ghci> :t GHC.ST.runST
766            GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a
767
768     -  If any of the quantified type variables has a kind that mentions
769        a kind variable, e.g.
770
771        .. code-block:: none
772
773            ghci> :i Data.Type.Equality.sym
774            Data.Type.Equality.sym ::
775              forall (k :: BOX) (a :: k) (b :: k).
776              (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a
777                    -- Defined in Data.Type.Equality
778
779 .. ghc-flag:: -fprint-explicit-kinds
780     :shortdesc: Print explicit kind foralls and kind arguments in types.
781         See also :ghc-flag:`-XKindSignatures`
782     :type: dynamic
783     :reverse: -fno-print-explicit-kinds
784     :category: verbosity
785
786     Using :ghc-flag:`-fprint-explicit-kinds` makes GHC print kind arguments in
787     types, which are normally suppressed. This can be important when you
788     are using kind polymorphism. For example:
789
790     .. code-block:: none
791
792         ghci> :set -XPolyKinds
793         ghci> data T a = MkT
794         ghci> :t MkT
795         MkT :: forall (k :: BOX) (a :: k). T a
796         ghci> :set -fprint-explicit-foralls
797         ghci> :t MkT
798         MkT :: forall (k :: BOX) (a :: k). T k a
799
800 .. ghc-flag:: -fprint-explicit-runtime-reps
801     :shortdesc: Print ``RuntimeRep`` variables in types which are
802         runtime-representation polymorphic.
803     :type: dynamic
804     :reverse: -fno-print-explicit-runtime-reps
805     :category: verbosity
806
807     When :ghc-flag:`-fprint-explicit-runtime-reps` is enabled, GHC prints
808     ``RuntimeRep`` type variables for levity-polymorphic types.
809     Otherwise GHC will default these to ``PtrRepLifted``. For example,
810
811     .. code-block:: none
812
813         ghci> :t ($)
814         ($) :: (a -> b) -> a -> b
815         ghci> :set -fprint-explicit-runtime-reps
816         ghci> :t ($)
817         ($)
818           :: forall (r :: GHC.Types.RuntimeRep) a (b :: TYPE r).
819              (a -> b) -> a -> b
820
821 .. ghc-flag:: -fprint-explicit-coercions
822     :shortdesc: Print coercions in types
823     :type: dynamic
824     :reverse: -fno-print-explicit-coercions
825     :category: verbosity
826
827     Using :ghc-flag:`-fprint-explicit-coercions` makes GHC print coercions in
828     types. When trying to prove the equality between types of different
829     kinds, GHC uses type-level coercions. Users will rarely need to
830     see these, as they are meant to be internal.
831
832 .. ghc-flag:: -fprint-equality-relations
833     :shortdesc: Distinguish between equality relations when printing
834     :type: dynamic
835     :reverse: -fno-print-equality-relations
836     :category: verbosity
837
838     Using :ghc-flag:`-fprint-equality-relations` tells GHC to distinguish between
839     its equality relations when printing. For example, ``~`` is homogeneous
840     lifted equality (the kinds of its arguments are the same) while
841     ``~~`` is heterogeneous lifted equality (the kinds of its arguments
842     might be different) and ``~#`` is heterogeneous unlifted equality,
843     the internal equality relation used in GHC's solver. Generally,
844     users should not need to worry about the subtleties here; ``~`` is
845     probably what you want. Without :ghc-flag:`-fprint-equality-relations`, GHC
846     prints all of these as ``~``. See also :ref:`equality-constraints`.
847
848 .. ghc-flag:: -fprint-expanded-synonyms
849     :shortdesc: In type errors, also print type-synonym-expanded types.
850     :type: dynamic
851     :reverse: -fno-print-expanded-synonyms
852     :category: verbosity
853
854     When enabled, GHC also prints type-synonym-expanded types in type
855     errors. For example, with this type synonyms: ::
856
857         type Foo = Int
858         type Bar = Bool
859         type MyBarST s = ST s Bar
860
861     This error message:
862
863     .. code-block:: none
864
865         Couldn't match type 'Int' with 'Bool'
866         Expected type: ST s Foo
867           Actual type: MyBarST s
868
869     Becomes this:
870
871     .. code-block:: none
872
873         Couldn't match type 'Int' with 'Bool'
874         Expected type: ST s Foo
875           Actual type: MyBarST s
876         Type synonyms expanded:
877         Expected type: ST s Int
878           Actual type: ST s Bool
879
880 .. ghc-flag:: -fprint-typechecker-elaboration
881     :shortdesc: Print extra information from typechecker.
882     :type: dynamic
883     :reverse: -fno-print-typechecker-elaboration
884     :category: verbosity
885
886     When enabled, GHC also prints extra information from the typechecker in
887     warnings. For example: ::
888
889         main :: IO ()
890         main = do
891           return $ let a = "hello" in a
892           return ()
893
894     This warning message:
895
896     .. code-block:: none
897
898         A do-notation statement discarded a result of type ‘[Char]’
899         Suppress this warning by saying
900           ‘_ <- ($) return let a = "hello" in a’
901         or by using the flag -fno-warn-unused-do-bind
902
903     Becomes this:
904
905     .. code-block:: none
906
907         A do-notation statement discarded a result of type ‘[Char]’
908         Suppress this warning by saying
909           ‘_ <- ($)
910                   return
911                   let
912                     AbsBinds [] []
913                       {Exports: [a <= a
914                                    <>]
915                        Exported types: a :: [Char]
916                                        [LclId, Str=DmdType]
917                        Binds: a = "hello"}
918                   in a’
919         or by using the flag -fno-warn-unused-do-bind
920
921 .. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩
922     :shortdesc: Use colors in error messages
923     :type: dynamic
924     :category: verbosity
925
926     Causes GHC to display error messages with colors.  To do this, the
927     terminal must have support for ANSI color codes, or else garbled text will
928     appear.  The default value is ``auto``, which means GHC will make an
929     attempt to detect whether terminal supports colors and choose accordingly.
930
931     The precise color scheme is controlled by the environment variable
932     ``GHC_COLORS`` (or ``GHC_COLOURS``).  This can be set to colon-separated
933     list of ``key=value`` pairs.  These are the default settings:
934
935     .. code-block:: none
936
937         header=:message=1:warning=1;35:error=1;31:fatal=1;31:margin=1;34
938
939     Each value is expected to be a `Select Graphic Rendition (SGR) substring
940     <https://en.wikipedia.org/wiki/ANSI_escape_code#graphics>`_.  The
941     formatting of each element can inherit from parent elements.  For example,
942     if ``header`` is left empty, it will inherit the formatting of
943     ``message``.  Alternatively if ``header`` is set to ``1`` (bold), it will
944     be bolded but still inherits the color of ``message``.
945
946     Currently, in the primary message, the following inheritance tree is in
947     place:
948
949     - ``message``
950
951       - ``header``
952
953         - ``warning``
954         - ``error``
955         - ``fatal``
956
957     In the caret diagnostics, there is currently no inheritance at all between
958     ``margin``, ``warning``, ``error``, and ``fatal``.
959
960     The environment variable can also be set to the magical values ``never``
961     or ``always``, which is equivalent to setting the corresponding
962     ``-fdiagnostics-color`` flag but with lower precedence.
963
964 .. ghc-flag:: -fdiagnostics-show-caret
965     :shortdesc: Whether to show snippets of original source code
966     :type: dynamic
967     :reverse: -fno-diagnostics-show-caret
968     :category: verbosity
969
970     Controls whether GHC displays a line of the original source code where the
971     error was detected.  This also affects the associated caret symbol that
972     points at the region of code at fault.  The flag is on by default.
973
974 .. ghc-flag:: -ferror-spans
975     :shortdesc: Output full span in error messages
976     :type: dynamic
977     :category: verbosity
978
979     Causes GHC to emit the full source span of the syntactic entity
980     relating to an error message. Normally, GHC emits the source
981     location of the start of the syntactic entity only.
982
983     For example:
984
985     .. code-block:: none
986
987         test.hs:3:6: parse error on input `where'
988
989     becomes:
990
991     .. code-block:: none
992
993         test296.hs:3:6-10: parse error on input `where'
994
995     And multi-line spans are possible too:
996
997     .. code-block:: none
998
999         test.hs:(5,4)-(6,7):
1000             Conflicting definitions for `a'
1001             Bound at: test.hs:5:4
1002                       test.hs:6:7
1003             In the binding group for: a, b, a
1004
1005     Note that line numbers start counting at one, but column numbers
1006     start at zero. This choice was made to follow existing convention
1007     (i.e. this is how Emacs does it).
1008
1009 .. ghc-flag:: -H ⟨size⟩
1010     :shortdesc: Set the minimum size of the heap to ⟨size⟩
1011     :type: dynamic
1012     :category: misc
1013
1014     Set the minimum size of the heap to ⟨size⟩. This option is
1015     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
1016
1017 .. ghc-flag:: -Rghc-timing
1018     :shortdesc: Summarise timing stats for GHC (same as ``+RTS -tstderr``).
1019     :type: dynamic
1020     :category: verbosity
1021
1022     Prints a one-line summary of timing statistics for the GHC run. This
1023     option is equivalent to ``+RTS -tstderr``, see
1024     :ref:`rts-options-gc`.
1025
1026 .. _options-platform:
1027
1028 Platform-specific Flags
1029 -----------------------
1030
1031 .. index::
1032    single: -m\* options
1033    single: platform-specific options
1034    single: machine-specific options
1035
1036 Some flags only make sense for particular target platforms.
1037
1038 .. ghc-flag:: -msse2
1039     :shortdesc: (x86 only) Use SSE2 for floating-point operations
1040     :type: dynamic
1041     :category: platform-options
1042
1043     (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
1044     instruction set to implement floating point operations when using
1045     the :ref:`native code generator <native-code-gen>`. This gives a
1046     substantial performance improvement for floating point, but the
1047     resulting compiled code will only run on processors that support
1048     SSE2 (Intel Pentium 4 and later, or AMD Athlon 64 and later). The
1049     :ref:`LLVM backend <llvm-code-gen>` will also use SSE2 if your
1050     processor supports it but detects this automatically so no flag is
1051     required.
1052
1053     SSE2 is unconditionally used on x86-64 platforms.
1054
1055 .. ghc-flag:: -msse4.2
1056     :shortdesc: (x86 only) Use SSE4.2 for floating-point operations
1057     :type: dynamic
1058     :category: platform-options
1059
1060     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
1061     implement some floating point and bit operations when using the
1062     :ref:`native code generator <native-code-gen>`. The resulting compiled
1063     code will only run on processors that support SSE4.2 (Intel Core i7
1064     and later). The :ref:`LLVM backend <llvm-code-gen>` will also use
1065     SSE4.2 if your processor supports it but detects this automatically
1066     so no flag is required.