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