users-guide: Begin documenting --frontend
[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 .. _source-file-options:
89
90 Command line options in source files
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93 .. index::
94    single: source-file options
95
96 Sometimes it is useful to make the connection between a source file and
97 the command-line options it requires quite tight. For instance, if a
98 Haskell source file deliberately uses name shadowing, it should be
99 compiled with the ``-Wno-name-shadowing`` option. Rather than
100 maintaining the list of per-file options in a ``Makefile``, it is
101 possible to do this directly in the source file using the
102 ``OPTIONS_GHC`` :ref:`pragma <options-pragma>` ::
103
104     {-# OPTIONS_GHC -Wno-name-shadowing #-}
105     module X where
106     ...
107
108 ``OPTIONS_GHC`` is a *file-header pragma* (see :ref:`options-pragma`).
109
110 Only *dynamic* flags can be used in an ``OPTIONS_GHC`` pragma (see
111 :ref:`static-dynamic-flags`).
112
113 Note that your command shell does not get to the source file options,
114 they are just included literally in the array of command-line arguments
115 the compiler maintains internally, so you'll be desperately disappointed
116 if you try to glob etc. inside ``OPTIONS_GHC``.
117
118 .. note::
119    The contents of ``OPTIONS_GHC`` are appended to the command-line
120    options, so options given in the source file override those given on the
121    command-line.
122
123 It is not recommended to move all the contents of your Makefiles into
124 your source files, but in some circumstances, the ``OPTIONS_GHC`` pragma
125 is the Right Thing. (If you use :ghc-flag:`-keep-hc-file` and have ``OPTION`` flags in
126 your module, the ``OPTIONS_GHC`` will get put into the generated ``.hc`` file).
127
128 Setting options in GHCi
129 ~~~~~~~~~~~~~~~~~~~~~~~
130
131 Options may also be modified from within GHCi, using the :ghci-cmd:`:set`
132 command.
133
134 .. _static-dynamic-flags:
135
136 Static, Dynamic, and Mode options
137 ---------------------------------
138
139 .. index::
140    single: static; options
141    single: dynamic; options
142    single: mode; options
143
144 Each of GHC's command line options is classified as static, dynamic or
145 mode:
146
147     For example, :ghc-flag:`--make` or :ghc-flag:`-E`. There may only be a single mode
148     flag on the command line. The available modes are listed in
149     :ref:`modes`.
150
151     Most non-mode flags fall into this category. A dynamic flag may be
152     used on the command line, in a ``OPTIONS_GHC`` pragma in a source
153     file, or set using :ghci-cmd:`:set` in GHCi.
154
155     A few flags are "static", which means they can only be used on the
156     command-line, and remain in force over the entire GHC/GHCi run.
157
158 The flag reference tables (:ref:`flag-reference`) lists the status of
159 each flag.
160
161 There are a few flags that are static except that they can also be used
162 with GHCi's :ghci-cmd:`:set` command; these are listed as “static/\ ``:set``\ ”
163 in the table.
164
165 .. _file-suffixes:
166
167 Meaningful file suffixes
168 ------------------------
169
170 .. index::
171    single: suffixes, file
172    single: file suffixes for GHC
173
174 File names with "meaningful" suffixes (e.g., ``.lhs`` or ``.o``) cause
175 the "right thing" to happen to those files.
176
177 ``.hs``
178     A Haskell module.
179
180 ``.lhs``
181     .. index::
182        single: lhs file extension
183
184     A “literate Haskell” module.
185
186 ``.hspp``
187     A file created by the preprocessor.
188
189 ``.hi``
190     A Haskell interface file, probably compiler-generated.
191
192 ``.hc``
193     Intermediate C file produced by the Haskell compiler.
194
195 ``.c``
196     A C file not produced by the Haskell compiler.
197
198 ``.ll``
199     An llvm-intermediate-language source file, usually produced by the
200     compiler.
201
202 ``.bc``
203     An llvm-intermediate-language bitcode file, usually produced by the
204     compiler.
205
206 ``.s``
207     An assembly-language source file, usually produced by the compiler.
208
209 ``.o``
210     An object file, produced by an assembler.
211
212 Files with other suffixes (or without suffixes) are passed straight to
213 the linker.
214
215 .. _modes:
216
217 Modes of operation
218 ------------------
219
220 .. index::
221    single: help options
222
223 GHC's behaviour is firstly controlled by a mode flag. Only one of these
224 flags may be given, but it does not necessarily need to be the first
225 option on the command-line. For instance,
226
227 .. code-block:: none
228
229     $ ghc Main.hs --make -o my-application
230
231 If no mode flag is present, then GHC will enter :ghc-flag:`--make` mode
232 (:ref:`make-mode`) if there are any Haskell source files given on the
233 command line, or else it will link the objects named on the command line
234 to produce an executable.
235
236 The available mode flags are:
237
238 .. ghc-flag:: --interactive
239
240     .. index::
241        single: interactive mode
242        single: GHCi
243
244     Interactive mode, which is also available as :program:`ghci`. Interactive
245     mode is described in more detail in :ref:`ghci`.
246
247 .. ghc-flag:: --make
248
249     .. index::
250        single: make mode; of GHC
251
252     In this mode, GHC will build a multi-module Haskell program
253     automatically, figuring out dependencies for itself. If you have a
254     straightforward Haskell program, this is likely to be much easier,
255     and faster, than using :command:`make`. Make mode is described in
256     :ref:`make-mode`.
257
258     This mode is the default if there are any Haskell source files
259     mentioned on the command line, and in this case the :ghc-flag:`--make`
260     option can be omitted.
261
262 .. ghc-flag:: -e ⟨expr⟩
263
264     .. index::
265        single: eval mode; of GHC
266
267     Expression-evaluation mode. This is very similar to interactive
268     mode, except that there is a single expression to evaluate (⟨expr⟩)
269     which is given on the command line. See :ref:`eval-mode` for more
270     details.
271
272 .. ghc-flag:: -E
273               -C
274               -S
275               -c
276
277     This is the traditional batch-compiler mode, in which GHC can
278     compile source files one at a time, or link objects together into an
279     executable. See :ref:`options-order`.
280
281 .. ghc-flag:: -M
282
283     .. index::
284         single: dependency-generation mode; of GHC
285
286     Dependency-generation mode. In this mode, GHC can be used to
287     generate dependency information suitable for use in a ``Makefile``.
288     See :ref:`makefile-dependencies`.
289
290 .. ghc-flag:: --frontend <module>
291
292     .. index::
293         single: frontend plugins; using
294
295     Run GHC using the given frontend plugin. See :ref:`frontend_plugins` for
296     details.
297
298 .. ghc-flag:: --mk-dll
299
300     .. index::
301        single: DLL-creation mode
302
303     DLL-creation mode (Windows only). See :ref:`win32-dlls-create`.
304
305 .. ghc-flag:: --help
306               -?
307
308     Cause GHC to spew a long usage message to standard output and then
309     exit.
310
311 .. ghc-flag:: --show-iface ⟨file⟩
312
313     Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For
314     example ``ghc --show-iface M.hi``.
315
316 .. ghc-flag:: --supported-extensions
317               --supported-languages
318
319     Print the supported language extensions.
320
321 .. ghc-flag:: --show-options
322
323     Print the supported command line options. This flag can be used for
324     autocompletion in a shell.
325
326 .. ghc-flag:: --info
327
328     Print information about the compiler.
329
330 .. ghc-flag:: --version
331               -V
332
333     Print a one-line string including GHC's version number.
334
335 .. ghc-flag:: --numeric-version
336
337     Print GHC's numeric version number only.
338
339 .. ghc-flag:: --print-libdir
340
341     .. index::
342        single: libdir
343
344     Print the path to GHC's library directory. This is the top of the
345     directory tree containing GHC's libraries, interfaces, and include
346     files (usually something like ``/usr/local/lib/ghc-5.04`` on Unix).
347     This is the value of ``$libdir`` in the package
348     configuration file (see :ref:`packages`).
349
350 .. _make-mode:
351
352 Using ``ghc`` ``--make``
353 ~~~~~~~~~~~~~~~~~~~~~~~~
354
355 .. index::
356    single: --make; mode of GHC
357    single: separate compilation
358
359 In this mode, GHC will build a multi-module Haskell program by following
360 dependencies from one or more root modules (usually just ``Main``). For
361 example, if your ``Main`` module is in a file called :file:`Main.hs`, you
362 could compile and link the program like this:
363
364 .. code-block:: none
365
366     ghc --make Main.hs
367
368 In fact, GHC enters make mode automatically if there are any Haskell
369 source files on the command line and no other mode is specified, so in
370 this case we could just type
371
372 .. code-block:: none
373
374     ghc Main.hs
375
376 Any number of source file names or module names may be specified; GHC
377 will figure out all the modules in the program by following the imports
378 from these initial modules. It will then attempt to compile each module
379 which is out of date, and finally, if there is a ``Main`` module, the
380 program will also be linked into an executable.
381
382 The main advantages to using ``ghc --make`` over traditional
383 ``Makefile``\s are:
384
385 -  GHC doesn't have to be restarted for each compilation, which means it
386    can cache information between compilations. Compiling a multi-module
387    program with ``ghc --make`` can be up to twice as fast as running
388    ``ghc`` individually on each source file.
389
390 -  You don't have to write a ``Makefile``.
391
392    .. index::
393       single: Makefiles; avoiding
394
395 -  GHC re-calculates the dependencies each time it is invoked, so the
396    dependencies never get out of sync with the source.
397
398 -  Using the :ghc-flag:`-j` flag, you can compile modules in parallel. Specify
399    ``-j⟨N⟩`` to compile ⟨N⟩ jobs in parallel.
400
401 Any of the command-line options described in the rest of this chapter
402 can be used with ``--make``, but note that any options you give on the
403 command line will apply to all the source files compiled, so if you want
404 any options to apply to a single source file only, you'll need to use an
405 ``OPTIONS_GHC`` pragma (see :ref:`source-file-options`).
406
407 If the program needs to be linked with additional objects (say, some
408 auxiliary C code), then the object files can be given on the command
409 line and GHC will include them when linking the executable.
410
411 For backward compatibility with existing make scripts, when used in
412 combination with :ghc-flag:`-c`, the linking phase is omitted (same as
413 ``--make -no-link``).
414
415 Note that GHC can only follow dependencies if it has the source file
416 available, so if your program includes a module for which there is no
417 source file, even if you have an object and an interface file for the
418 module, then GHC will complain. The exception to this rule is for
419 package modules, which may or may not have source files.
420
421 The source files for the program don't all need to be in the same
422 directory; the :ghc-flag:`-i` option can be used to add directories to the
423 search path (see :ref:`search-path`).
424
425 .. ghc-flag:: -j <N>
426
427     Perform compilation in parallel when possible. GHC will use up to ⟨N⟩
428     threads during compilation. Note that compilation of a module may not
429     begin until its dependencies have been built.
430
431 .. _eval-mode:
432
433 Expression evaluation mode
434 ~~~~~~~~~~~~~~~~~~~~~~~~~~
435
436 This mode is very similar to interactive mode, except that there is a
437 single expression to evaluate which is specified on the command line as
438 an argument to the ``-e`` option:
439
440 .. code-block:: none
441
442     ghc -e expr
443
444 Haskell source files may be named on the command line, and they will be
445 loaded exactly as in interactive mode. The expression is evaluated in
446 the context of the loaded modules.
447
448 For example, to load and run a Haskell program containing a module
449 ``Main``, we might say:
450
451 .. code-block:: none
452
453     ghc -e Main.main Main.hs
454
455 or we can just use this mode to evaluate expressions in the context of
456 the ``Prelude``:
457
458 .. code-block:: none
459
460     $ ghc -e "interact (unlines.map reverse.lines)"
461     hello
462     olleh
463
464 .. _options-order:
465
466 Batch compiler mode
467 ~~~~~~~~~~~~~~~~~~~
468
469 In *batch mode*, GHC will compile one or more source files given on the
470 command line.
471
472 The first phase to run is determined by each input-file suffix, and the
473 last phase is determined by a flag. If no relevant flag is present, then
474 go all the way through to linking. This table summarises:
475
476 +-----------------------------------+------------------------------+----------------------------+---------------------------+
477 | Phase of the compilation system   | Suffix saying “start here”   | Flag saying “stop after”   | (suffix of) output file   |
478 +===================================+==============================+============================+===========================+
479 | literate pre-processor            | ``.lhs``                     |                            | ``.hs``                   |
480 +-----------------------------------+------------------------------+----------------------------+---------------------------+
481 | C pre-processor (opt.)            | ``.hs`` (with ``-cpp``)      | ``-E``                     | ``.hspp``                 |
482 +-----------------------------------+------------------------------+----------------------------+---------------------------+
483 | Haskell compiler                  | ``.hs``                      | ``-C``, ``-S``             | ``.hc``, ``.s``           |
484 +-----------------------------------+------------------------------+----------------------------+---------------------------+
485 | C compiler (opt.)                 | ``.hc`` or ``.c``            | ``-S``                     | ``.s``                    |
486 +-----------------------------------+------------------------------+----------------------------+---------------------------+
487 | assembler                         | ``.s``                       | ``-c``                     | ``.o``                    |
488 +-----------------------------------+------------------------------+----------------------------+---------------------------+
489 | linker                            | ⟨other⟩                      |                            | ``a.out``                 |
490 +-----------------------------------+------------------------------+----------------------------+---------------------------+
491
492 .. index::
493    single: -C
494    single: -E
495    single: -S
496    single: -c
497
498 Thus, a common invocation would be:
499
500 .. code-block:: none
501
502     ghc -c Foo.hs
503
504 to compile the Haskell source file ``Foo.hs`` to an object file
505 ``Foo.o``.
506
507 .. note::
508    What the Haskell compiler proper produces depends on what backend
509    code generator is used. See :ref:`code-generators` for more details.
510
511 .. note::
512    Pre-processing is optional, the :ghc-flag:`-cpp` flag turns it
513    on. See :ref:`c-pre-processor` for more details.
514
515 .. note::
516    The option :ghc-flag:`-E` runs just the pre-processing passes of
517    the compiler, dumping the result in a file.
518
519 .. note::
520    The option :ghc-flag:`-C` is only available when GHC is built in
521    unregisterised mode. See :ref:`unreg` for more details.
522
523 .. _overriding-suffixes:
524
525 Overriding the default behaviour for a file
526 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
527
528 As described above, the way in which a file is processed by GHC depends
529 on its suffix. This behaviour can be overridden using the :ghc-flag:`-x` option:
530
531 .. ghc-flag:: -x <suffix>
532
533     Causes all files following this option on the command line to be
534     processed as if they had the suffix ⟨suffix⟩. For example, to
535     compile a Haskell module in the file ``M.my-hs``, use
536     ``ghc -c -x hs M.my-hs``.
537
538 .. _options-help:
539
540 Verbosity options
541 -----------------
542
543 .. index::
544    single: verbosity options
545
546 See also the ``--help``, ``--version``, ``--numeric-version``, and
547 ``--print-libdir`` modes in :ref:`modes`.
548
549 .. ghc-flag:: -v
550
551     The :ghc-flag:`-v` option makes GHC *verbose*: it reports its version number
552     and shows (on stderr) exactly how it invokes each phase of the
553     compilation system. Moreover, it passes the ``-v`` flag to most
554     phases; each reports its version number (and possibly some other
555     information).
556
557     Please, oh please, use the ``-v`` option when reporting bugs!
558     Knowing that you ran the right bits in the right order is always the
559     first thing we want to verify.
560
561 .. ghc-flag:: -v ⟨n⟩
562     :noindex:
563
564     To provide more control over the compiler's verbosity, the ``-v``
565     flag takes an optional numeric argument. Specifying ``-v`` on its
566     own is equivalent to ``-v3``, and the other levels have the
567     following meanings:
568
569     ``-v0``
570         Disable all non-essential messages (this is the default).
571
572     ``-v1``
573         Minimal verbosity: print one line per compilation (this is the
574         default when ``--make`` or ``--interactive`` is on).
575
576     ``-v2``
577         Print the name of each compilation phase as it is executed.
578         (equivalent to ``-dshow-passes``).
579
580     ``-v3``
581         The same as ``-v2``, except that in addition the full command
582         line (if appropriate) for each compilation phase is also
583         printed.
584
585     ``-v4``
586         The same as ``-v3`` except that the intermediate program
587         representation after each compilation phase is also printed
588         (excluding preprocessed and C/assembly files).
589
590 .. ghc-flag:: --fprint-potential-instances
591
592     When GHC can't find an instance for a class, it displays a short
593     list of some in the instances it knows about. With this flag it
594     prints *all* the instances it knows about.
595
596 .. ghc-flag:: -fprint-explicit-foralls
597               -fprint-explicit-kinds
598               -fprint-unicode-syntax
599               -fprint-explicit-coercions
600               -fprint-equality-relations
601
602     These flags control the way in which GHC displays types, in
603     error messages and in GHCi. Using :ghc-flag:`-fprint-explicit-foralls` makes
604     GHC print explicit ``forall`` quantification at the top level of a
605     type; normally this is suppressed. For example, in GHCi:
606
607     .. code-block:: none
608
609         ghci> let f x = x
610         ghci> :t f
611         f :: a -> a
612         ghci> :set -fprint-explicit-foralls
613         ghci> :t f
614         f :: forall a. a -> a
615
616     However, regardless of the flag setting, the quantifiers are printed
617     under these circumstances:
618
619     -  For nested ``foralls``, e.g.
620
621        .. code-block:: none
622
623            ghci> :t GHC.ST.runST
624            GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a
625
626     -  If any of the quantified type variables has a kind that mentions
627        a kind variable, e.g.
628
629        .. code-block:: none
630
631            ghci> :i Data.Type.Equality.sym
632            Data.Type.Equality.sym ::
633              forall (k :: BOX) (a :: k) (b :: k).
634              (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a
635                    -- Defined in Data.Type.Equality
636
637     Using :ghc-flag:`-fprint-explicit-kinds` makes GHC print kind arguments in
638     types, which are normally suppressed. This can be important when you
639     are using kind polymorphism. For example:
640
641     .. code-block:: none
642
643         ghci> :set -XPolyKinds
644         ghci> data T a = MkT
645         ghci> :t MkT
646         MkT :: forall (k :: BOX) (a :: k). T a
647         ghci> :set -fprint-explicit-foralls
648         ghci> :t MkT
649         MkT :: forall (k :: BOX) (a :: k). T k a
650
651     When :ghc-flag:`-fprint-unicode-syntax` is enabled, GHC prints type
652     signatures using the unicode symbols from the ``-XUnicodeSyntax``
653     extension.
654
655     .. code-block:: none
656
657         ghci> :set -fprint-unicode-syntax
658         ghci> :t (>>)
659         (>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b
660
661     Using :ghc-flag:`-fprint-explicit-coercions` makes GHC print coercions in
662     types. When trying to prove the equality between types of different
663     kinds, GHC uses type-level coercions. Users will rarely need to
664     see these, as they are meant to be internal.
665
666     Using :ghc-flag:`-fprint-equality-relations` tells GHC to distinguish between
667     its equality relations when printing. For example, ``~`` is homogeneous
668     lifted equality (the kinds of its arguments are the same) while
669     ``~~`` is heterogeneous lifted equality (the kinds of its arguments
670     might be different) and ``~#`` is heterogeneous unlifted equality,
671     the internal equality relation used in GHC's solver. Generally,
672     users should not need to worry about the subtleties here; ``~`` is
673     probably what you want. Without :ghc-flag:`-fprint-equality-relations`, GHC
674     prints all of these as ``~``.
675
676 .. ghc-flag:: -fprint-expanded-synonyms
677
678     When enabled, GHC also prints type-synonym-expanded types in type
679     errors. For example, with this type synonyms: ::
680
681         type Foo = Int
682         type Bar = Bool
683         type MyBarST s = ST s Bar
684
685     This error message:
686
687     .. code-block:: none
688
689         Couldn't match type 'Int' with 'Bool'
690         Expected type: ST s Foo
691           Actual type: MyBarST s
692
693     Becomes this:
694
695     .. code-block:: none
696
697         Couldn't match type 'Int' with 'Bool'
698         Expected type: ST s Foo
699           Actual type: MyBarST s
700         Type synonyms expanded:
701         Expected type: ST s Int
702           Actual type: ST s Bool
703
704 .. ghc-flag:: -fprint-typechecker-elaboration
705
706     When enabled, GHC also prints extra information from the typechecker in
707     warnings. For example: ::
708
709         main :: IO ()
710         main = do
711           return $ let a = "hello" in a
712           return ()
713
714     This warning message:
715
716     .. code-block:: none
717
718         A do-notation statement discarded a result of type ‘[Char]’
719         Suppress this warning by saying
720           ‘_ <- ($) return let a = "hello" in a’
721         or by using the flag -fno-warn-unused-do-bind
722
723     Becomes this:
724
725     .. code-block:: none
726
727         A do-notation statement discarded a result of type ‘[Char]’
728         Suppress this warning by saying
729           ‘_ <- ($)
730                   return
731                   let
732                     AbsBinds [] []
733                       {Exports: [a <= a
734                                    <>]
735                        Exported types: a :: [Char]
736                                        [LclId, Str=DmdType]
737                        Binds: a = "hello"}
738                   in a’
739         or by using the flag -fno-warn-unused-do-bind
740
741 .. ghc-flag:: -ferror-spans
742
743     Causes GHC to emit the full source span of the syntactic entity
744     relating to an error message. Normally, GHC emits the source
745     location of the start of the syntactic entity only.
746
747     For example:
748
749     .. code-block:: none
750
751         test.hs:3:6: parse error on input `where'
752
753     becomes:
754
755     .. code-block:: none
756
757         test296.hs:3:6-10: parse error on input `where'
758
759     And multi-line spans are possible too:
760
761     .. code-block:: none
762
763         test.hs:(5,4)-(6,7):
764             Conflicting definitions for `a'
765             Bound at: test.hs:5:4
766                       test.hs:6:7
767             In the binding group for: a, b, a
768
769     Note that line numbers start counting at one, but column numbers
770     start at zero. This choice was made to follow existing convention
771     (i.e. this is how Emacs does it).
772
773 .. ghc-flag:: -H <size>
774
775     Set the minimum size of the heap to ⟨size⟩. This option is
776     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
777
778 .. ghc-flag:: -Rghc-timing
779
780     Prints a one-line summary of timing statistics for the GHC run. This
781     option is equivalent to ``+RTS -tstderr``, see
782     :ref:`rts-options-gc`.
783
784 .. _options-platform:
785
786 Platform-specific Flags
787 -----------------------
788
789 .. index::
790    single: -m\* options
791    single: platform-specific options
792    single: machine-specific options
793
794 Some flags only make sense for particular target platforms.
795
796 .. ghc-flag:: -msse2
797
798     (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
799     instruction set to implement floating point operations when using
800     the :ref:`native code generator <native-code-gen>`. This gives a
801     substantial performance improvement for floating point, but the
802     resulting compiled code will only run on processors that support
803     SSE2 (Intel Pentium 4 and later, or AMD Athlon 64 and later). The
804     :ref:`LLVM backend <llvm-code-gen>` will also use SSE2 if your
805     processor supports it but detects this automatically so no flag is
806     required.
807
808     SSE2 is unconditionally used on x86-64 platforms.
809
810 .. ghc-flag:: -msse4.2
811     :noindex:
812
813     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
814     implement some floating point and bit operations when using the
815     :ref:`native code generator <native-code-gen>`. The resulting compiled
816     code will only run on processors that support SSE4.2 (Intel Core i7
817     and later). The :ref:`LLVM backend <llvm-code-gen>` will also use
818     SSE4.2 if your processor supports it but detects this automatically
819     so no flag is required.