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