users_guide: Use semantic directive/role for command line options
[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:: --mk-dll
291
292     .. index::
293        single: DLL-creation mode
294
295     DLL-creation mode (Windows only). See :ref:`win32-dlls-create`.
296
297 .. ghc-flag:: --help
298               -?
299
300     Cause GHC to spew a long usage message to standard output and then
301     exit.
302
303 .. ghc-flag:: --show-iface ⟨file⟩
304
305     Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For
306     example ``ghc --show-iface M.hi``.
307
308 .. ghc-flag:: --supported-extensions
309               --supported-languages
310
311     Print the supported language extensions.
312
313 .. ghc-flag:: --show-options
314
315     Print the supported command line options. This flag can be used for
316     autocompletion in a shell.
317
318 .. ghc-flag:: --info
319
320     Print information about the compiler.
321
322 .. ghc-flag:: --version
323               -V
324
325     Print a one-line string including GHC's version number.
326
327 .. ghc-flag:: --numeric-version
328
329     Print GHC's numeric version number only.
330
331 .. ghc-flag:: --print-libdir
332
333     .. index::
334        single: libdir
335
336     Print the path to GHC's library directory. This is the top of the
337     directory tree containing GHC's libraries, interfaces, and include
338     files (usually something like ``/usr/local/lib/ghc-5.04`` on Unix).
339     This is the value of ``$libdir`` in the package
340     configuration file (see :ref:`packages`).
341
342 .. _make-mode:
343
344 Using ``ghc`` ``--make``
345 ~~~~~~~~~~~~~~~~~~~~~~~~
346
347 .. index::
348    single: --make; mode of GHC
349    single: separate compilation
350
351 In this mode, GHC will build a multi-module Haskell program by following
352 dependencies from one or more root modules (usually just ``Main``). For
353 example, if your ``Main`` module is in a file called :file:`Main.hs`, you
354 could compile and link the program like this:
355
356 .. code-block:: none
357
358     ghc --make Main.hs
359
360 In fact, GHC enters make mode automatically if there are any Haskell
361 source files on the command line and no other mode is specified, so in
362 this case we could just type
363
364 .. code-block:: none
365
366     ghc Main.hs
367
368 Any number of source file names or module names may be specified; GHC
369 will figure out all the modules in the program by following the imports
370 from these initial modules. It will then attempt to compile each module
371 which is out of date, and finally, if there is a ``Main`` module, the
372 program will also be linked into an executable.
373
374 The main advantages to using ``ghc --make`` over traditional
375 ``Makefile``\s are:
376
377 -  GHC doesn't have to be restarted for each compilation, which means it
378    can cache information between compilations. Compiling a multi-module
379    program with ``ghc --make`` can be up to twice as fast as running
380    ``ghc`` individually on each source file.
381
382 -  You don't have to write a ``Makefile``.
383
384    .. index::
385       single: Makefiles; avoiding
386
387 -  GHC re-calculates the dependencies each time it is invoked, so the
388    dependencies never get out of sync with the source.
389
390 -  Using the :ghc-flag:`-j` flag, you can compile modules in parallel. Specify
391    ``-j⟨N⟩`` to compile ⟨N⟩ jobs in parallel.
392
393 Any of the command-line options described in the rest of this chapter
394 can be used with ``--make``, but note that any options you give on the
395 command line will apply to all the source files compiled, so if you want
396 any options to apply to a single source file only, you'll need to use an
397 ``OPTIONS_GHC`` pragma (see :ref:`source-file-options`).
398
399 If the program needs to be linked with additional objects (say, some
400 auxiliary C code), then the object files can be given on the command
401 line and GHC will include them when linking the executable.
402
403 For backward compatibility with existing make scripts, when used in
404 combination with :ghc-flag:`-c`, the linking phase is omitted (same as
405 ``--make -no-link``).
406
407 Note that GHC can only follow dependencies if it has the source file
408 available, so if your program includes a module for which there is no
409 source file, even if you have an object and an interface file for the
410 module, then GHC will complain. The exception to this rule is for
411 package modules, which may or may not have source files.
412
413 The source files for the program don't all need to be in the same
414 directory; the :ghc-flag:`-i` option can be used to add directories to the
415 search path (see :ref:`search-path`).
416
417 .. ghc-flag:: -j <N>
418
419     Perform compilation in parallel when possible. GHC will use up to ⟨N⟩
420     threads during compilation. Note that compilation of a module may not
421     begin until its dependencies have been built.
422
423 .. _eval-mode:
424
425 Expression evaluation mode
426 ~~~~~~~~~~~~~~~~~~~~~~~~~~
427
428 This mode is very similar to interactive mode, except that there is a
429 single expression to evaluate which is specified on the command line as
430 an argument to the ``-e`` option:
431
432 .. code-block:: none
433
434     ghc -e expr
435
436 Haskell source files may be named on the command line, and they will be
437 loaded exactly as in interactive mode. The expression is evaluated in
438 the context of the loaded modules.
439
440 For example, to load and run a Haskell program containing a module
441 ``Main``, we might say:
442
443 .. code-block:: none
444
445     ghc -e Main.main Main.hs
446
447 or we can just use this mode to evaluate expressions in the context of
448 the ``Prelude``:
449
450 .. code-block:: none
451
452     $ ghc -e "interact (unlines.map reverse.lines)"
453     hello
454     olleh
455
456 .. _options-order:
457
458 Batch compiler mode
459 ~~~~~~~~~~~~~~~~~~~
460
461 In *batch mode*, GHC will compile one or more source files given on the
462 command line.
463
464 The first phase to run is determined by each input-file suffix, and the
465 last phase is determined by a flag. If no relevant flag is present, then
466 go all the way through to linking. This table summarises:
467
468 +-----------------------------------+------------------------------+----------------------------+---------------------------+
469 | Phase of the compilation system   | Suffix saying “start here”   | Flag saying “stop after”   | (suffix of) output file   |
470 +===================================+==============================+============================+===========================+
471 | literate pre-processor            | ``.lhs``                     |                            | ``.hs``                   |
472 +-----------------------------------+------------------------------+----------------------------+---------------------------+
473 | C pre-processor (opt.)            | ``.hs`` (with ``-cpp``)      | ``-E``                     | ``.hspp``                 |
474 +-----------------------------------+------------------------------+----------------------------+---------------------------+
475 | Haskell compiler                  | ``.hs``                      | ``-C``, ``-S``             | ``.hc``, ``.s``           |
476 +-----------------------------------+------------------------------+----------------------------+---------------------------+
477 | C compiler (opt.)                 | ``.hc`` or ``.c``            | ``-S``                     | ``.s``                    |
478 +-----------------------------------+------------------------------+----------------------------+---------------------------+
479 | assembler                         | ``.s``                       | ``-c``                     | ``.o``                    |
480 +-----------------------------------+------------------------------+----------------------------+---------------------------+
481 | linker                            | ⟨other⟩                      |                            | ``a.out``                 |
482 +-----------------------------------+------------------------------+----------------------------+---------------------------+
483
484 .. index::
485    single: -C
486    single: -E
487    single: -S
488    single: -c
489
490 Thus, a common invocation would be:
491
492 .. code-block:: none
493
494     ghc -c Foo.hs
495
496 to compile the Haskell source file ``Foo.hs`` to an object file
497 ``Foo.o``.
498
499 .. note::
500    What the Haskell compiler proper produces depends on what backend
501    code generator is used. See :ref:`code-generators` for more details.
502
503 .. note::
504    Pre-processing is optional, the :ghc-flag:`-cpp` flag turns it
505    on. See :ref:`c-pre-processor` for more details.
506
507 .. note::
508    The option :ghc-flag:`-E` runs just the pre-processing passes of
509    the compiler, dumping the result in a file.
510
511 .. note::
512    The option :ghc-flag:`-C` is only available when GHC is built in
513    unregisterised mode. See :ref:`unreg` for more details.
514
515 .. _overriding-suffixes:
516
517 Overriding the default behaviour for a file
518 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
519
520 As described above, the way in which a file is processed by GHC depends
521 on its suffix. This behaviour can be overridden using the :ghc-flag:`-x` option:
522
523 .. ghc-flag:: -x <suffix>
524
525     Causes all files following this option on the command line to be
526     processed as if they had the suffix ⟨suffix⟩. For example, to
527     compile a Haskell module in the file ``M.my-hs``, use
528     ``ghc -c -x hs M.my-hs``.
529
530 .. _options-help:
531
532 Verbosity options
533 -----------------
534
535 .. index::
536    single: verbosity options
537
538 See also the ``--help``, ``--version``, ``--numeric-version``, and
539 ``--print-libdir`` modes in :ref:`modes`.
540
541 .. ghc-flag:: -v
542
543     The :ghc-flag:`-v` option makes GHC *verbose*: it reports its version number
544     and shows (on stderr) exactly how it invokes each phase of the
545     compilation system. Moreover, it passes the ``-v`` flag to most
546     phases; each reports its version number (and possibly some other
547     information).
548
549     Please, oh please, use the ``-v`` option when reporting bugs!
550     Knowing that you ran the right bits in the right order is always the
551     first thing we want to verify.
552
553 .. ghc-flag:: -v ⟨n⟩
554     :noindex:
555
556     To provide more control over the compiler's verbosity, the ``-v``
557     flag takes an optional numeric argument. Specifying ``-v`` on its
558     own is equivalent to ``-v3``, and the other levels have the
559     following meanings:
560
561     ``-v0``
562         Disable all non-essential messages (this is the default).
563
564     ``-v1``
565         Minimal verbosity: print one line per compilation (this is the
566         default when ``--make`` or ``--interactive`` is on).
567
568     ``-v2``
569         Print the name of each compilation phase as it is executed.
570         (equivalent to ``-dshow-passes``).
571
572     ``-v3``
573         The same as ``-v2``, except that in addition the full command
574         line (if appropriate) for each compilation phase is also
575         printed.
576
577     ``-v4``
578         The same as ``-v3`` except that the intermediate program
579         representation after each compilation phase is also printed
580         (excluding preprocessed and C/assembly files).
581
582 .. ghc-flag:: --fprint-potential-instances
583
584     When GHC can't find an instance for a class, it displays a short
585     list of some in the instances it knows about. With this flag it
586     prints *all* the instances it knows about.
587
588 .. ghc-flag:: -fprint-explicit-foralls
589               -fprint-explicit-kinds
590               -fprint-unicode-syntax
591               -fprint-explicit-coercions
592               -fprint-equality-relations
593
594     These flags control the way in which GHC displays types, in
595     error messages and in GHCi. Using :ghc-flag:`-fprint-explicit-foralls` makes
596     GHC print explicit ``forall`` quantification at the top level of a
597     type; normally this is suppressed. For example, in GHCi:
598
599     .. code-block:: none
600
601         ghci> let f x = x
602         ghci> :t f
603         f :: a -> a
604         ghci> :set -fprint-explicit-foralls
605         ghci> :t f
606         f :: forall a. a -> a
607
608     However, regardless of the flag setting, the quantifiers are printed
609     under these circumstances:
610
611     -  For nested ``foralls``, e.g.
612
613        .. code-block:: none
614
615            ghci> :t GHC.ST.runST
616            GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a
617
618     -  If any of the quantified type variables has a kind that mentions
619        a kind variable, e.g.
620
621        .. code-block:: none
622
623            ghci> :i Data.Type.Equality.sym
624            Data.Type.Equality.sym ::
625              forall (k :: BOX) (a :: k) (b :: k).
626              (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a
627                    -- Defined in Data.Type.Equality
628
629     Using :ghc-flag:`-fprint-explicit-kinds` makes GHC print kind arguments in
630     types, which are normally suppressed. This can be important when you
631     are using kind polymorphism. For example:
632
633     .. code-block:: none
634
635         ghci> :set -XPolyKinds
636         ghci> data T a = MkT
637         ghci> :t MkT
638         MkT :: forall (k :: BOX) (a :: k). T a
639         ghci> :set -fprint-explicit-foralls
640         ghci> :t MkT
641         MkT :: forall (k :: BOX) (a :: k). T k a
642
643     When :ghc-flag:`-fprint-unicode-syntax` is enabled, GHC prints type
644     signatures using the unicode symbols from the ``-XUnicodeSyntax``
645     extension.
646
647     .. code-block:: none
648
649         ghci> :set -fprint-unicode-syntax
650         ghci> :t (>>)
651         (>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b
652
653     Using :ghc-flag:`-fprint-explicit-coercions` makes GHC print coercions in
654     types. When trying to prove the equality between types of different
655     kinds, GHC uses type-level coercions. Users will rarely need to
656     see these, as they are meant to be internal.
657
658     Using :ghc-flag:`-fprint-equality-relations` tells GHC to distinguish between
659     its equality relations when printing. For example, ``~`` is homogeneous
660     lifted equality (the kinds of its arguments are the same) while
661     ``~~`` is heterogeneous lifted equality (the kinds of its arguments
662     might be different) and ``~#`` is heterogeneous unlifted equality,
663     the internal equality relation used in GHC's solver. Generally,
664     users should not need to worry about the subtleties here; ``~`` is
665     probably what you want. Without :ghc-flag:`-fprint-equality-relations`, GHC
666     prints all of these as ``~``.
667
668 .. ghc-flag:: -fprint-expanded-synonyms
669
670     When enabled, GHC also prints type-synonym-expanded types in type
671     errors. For example, with this type synonyms: ::
672
673         type Foo = Int
674         type Bar = Bool
675         type MyBarST s = ST s Bar
676
677     This error message:
678
679     .. code-block:: none
680
681         Couldn't match type 'Int' with 'Bool'
682         Expected type: ST s Foo
683           Actual type: MyBarST s
684
685     Becomes this:
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         Type synonyms expanded:
693         Expected type: ST s Int
694           Actual type: ST s Bool
695
696 .. ghc-flag:: -fprint-typechecker-elaboration
697
698     When enabled, GHC also prints extra information from the typechecker in
699     warnings. For example: ::
700
701         main :: IO ()
702         main = do
703           return $ let a = "hello" in a
704           return ()
705
706     This warning message:
707
708     .. code-block:: none
709
710         A do-notation statement discarded a result of type ‘[Char]’
711         Suppress this warning by saying
712           ‘_ <- ($) return let a = "hello" in a’
713         or by using the flag -fno-warn-unused-do-bind
714
715     Becomes this:
716
717     .. code-block:: none
718
719         A do-notation statement discarded a result of type ‘[Char]’
720         Suppress this warning by saying
721           ‘_ <- ($)
722                   return
723                   let
724                     AbsBinds [] []
725                       {Exports: [a <= a
726                                    <>]
727                        Exported types: a :: [Char]
728                                        [LclId, Str=DmdType]
729                        Binds: a = "hello"}
730                   in a’
731         or by using the flag -fno-warn-unused-do-bind
732
733 .. ghc-flag:: -ferror-spans
734
735     Causes GHC to emit the full source span of the syntactic entity
736     relating to an error message. Normally, GHC emits the source
737     location of the start of the syntactic entity only.
738
739     For example:
740
741     .. code-block:: none
742
743         test.hs:3:6: parse error on input `where'
744
745     becomes:
746
747     .. code-block:: none
748
749         test296.hs:3:6-10: parse error on input `where'
750
751     And multi-line spans are possible too:
752
753     .. code-block:: none
754
755         test.hs:(5,4)-(6,7):
756             Conflicting definitions for `a'
757             Bound at: test.hs:5:4
758                       test.hs:6:7
759             In the binding group for: a, b, a
760
761     Note that line numbers start counting at one, but column numbers
762     start at zero. This choice was made to follow existing convention
763     (i.e. this is how Emacs does it).
764
765 .. ghc-flag:: -H <size>
766
767     Set the minimum size of the heap to ⟨size⟩. This option is
768     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
769
770 .. ghc-flag:: -Rghc-timing
771
772     Prints a one-line summary of timing statistics for the GHC run. This
773     option is equivalent to ``+RTS -tstderr``, see
774     :ref:`rts-options-gc`.
775
776 .. _options-platform:
777
778 Platform-specific Flags
779 -----------------------
780
781 .. index::
782    single: -m\* options
783    single: platform-specific options
784    single: machine-specific options
785
786 Some flags only make sense for particular target platforms.
787
788 .. ghc-flag:: -msse2
789
790     (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
791     instruction set to implement floating point operations when using
792     the :ref:`native code generator <native-code-gen>`. This gives a
793     substantial performance improvement for floating point, but the
794     resulting compiled code will only run on processors that support
795     SSE2 (Intel Pentium 4 and later, or AMD Athlon 64 and later). The
796     :ref:`LLVM backend <llvm-code-gen>` will also use SSE2 if your
797     processor supports it but detects this automatically so no flag is
798     required.
799
800     SSE2 is unconditionally used on x86-64 platforms.
801
802 .. ghc-flag:: -msse4.2
803     :noindex:
804
805     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
806     implement some floating point and bit operations when using the
807     :ref:`native code generator <native-code-gen>`. The resulting compiled
808     code will only run on processors that support SSE4.2 (Intel Core i7
809     and later). The :ref:`LLVM backend <llvm-code-gen>` will also use
810     SSE4.2 if your processor supports it but detects this automatically
811     so no flag is required.