Move user's guide to ReStructuredText
[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 ``-fno-warn-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 -fno-warn-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``
601     .. index::
602        single: -fprint-explicit-foralls
603        single: -fprint-explicit-kinds
604        single: -fprint-unicode-syntax
605
606     These three flags control the way in which GHC displays types, in
607     error messages and in GHCi. Using ``-fprint-explicit-foralls`` makes
608     GHC print explicit ``forall`` quantification at the top level of a
609     type; normally this is suppressed. For example, in GHCi:
610
611     ::
612
613         ghci> let f x = x
614         ghci> :t f
615         f :: a -> a
616         ghci> :set -fprint-explicit-foralls
617         ghci> :t f
618         f :: forall a. a -> a
619
620     However, regardless of the flag setting, the quantifiers are printed
621     under these circumstances:
622
623     -  For nested ``foralls``, e.g.
624
625        ::
626
627            ghci> :t GHC.ST.runST
628            GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a
629
630     -  If any of the quantified type variables has a kind that mentions
631        a kind variable, e.g.
632
633        ::
634
635            ghci> :i Data.Type.Equality.sym
636            Data.Type.Equality.sym ::
637              forall (k :: BOX) (a :: k) (b :: k).
638              (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a
639                    -- Defined in Data.Type.Equality
640
641     Using ``-fprint-explicit-kinds`` makes GHC print kind arguments in
642     types, which are normally suppressed. This can be important when you
643     are using kind polymorphism. For example:
644
645     ::
646
647         ghci> :set -XPolyKinds
648         ghci> data T a = MkT
649         ghci> :t MkT
650         MkT :: forall (k :: BOX) (a :: k). T a
651         ghci> :set -fprint-explicit-foralls
652         ghci> :t MkT
653         MkT :: forall (k :: BOX) (a :: k). T k a
654
655     When ``-fprint-unicode-syntax`` is enabled, GHC prints type
656     signatures using the unicode symbols from the ``-XUnicodeSyntax``
657     extension.
658
659     ::
660
661         ghci> :set -fprint-unicode-syntax
662         ghci> :t (>>)
663         (>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b
664
665 ``-fprint-expanded-synonyms``
666     .. index::
667        single: -fprint-expanded-synonyms
668
669     When enabled, GHC also prints type-synonym-expanded types in type
670     errors. For example, with this type synonyms:
671
672     ::
673
674         type Foo = Int
675         type Bar = Bool
676         type MyBarST s = ST s Bar
677
678     This error message:
679
680     ::
681
682         Couldn't match type 'Int' with 'Bool'
683         Expected type: ST s Foo
684           Actual type: MyBarST s
685
686     Becomes this:
687
688     ::
689
690         Couldn't match type 'Int' with 'Bool'
691         Expected type: ST s Foo
692           Actual type: MyBarST s
693         Type synonyms expanded:
694         Expected type: ST s Int
695           Actual type: ST s Bool
696
697 ``-ferror-spans``
698     .. index::
699        single: -ferror-spans
700
701     Causes GHC to emit the full source span of the syntactic entity
702     relating to an error message. Normally, GHC emits the source
703     location of the start of the syntactic entity only.
704
705     For example:
706
707     ::
708
709         test.hs:3:6: parse error on input `where'
710
711     becomes:
712
713     ::
714
715         test296.hs:3:6-10: parse error on input `where'
716
717     And multi-line spans are possible too:
718
719     ::
720
721         test.hs:(5,4)-(6,7):
722             Conflicting definitions for `a'
723             Bound at: test.hs:5:4
724                       test.hs:6:7
725             In the binding group for: a, b, a
726
727     Note that line numbers start counting at one, but column numbers
728     start at zero. This choice was made to follow existing convention
729     (i.e. this is how Emacs does it).
730
731 ``-H⟨size⟩``
732     .. index::
733        single: -H
734
735     Set the minimum size of the heap to ⟨size⟩. This option is
736     equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`.
737
738 ``-Rghc-timing``
739     .. index::
740        single: -Rghc-timing
741
742     Prints a one-line summary of timing statistics for the GHC run. This
743     option is equivalent to ``+RTS -tstderr``, see
744     :ref:`rts-options-gc`.
745
746 .. _options-platform:
747
748 Platform-specific Flags
749 -----------------------
750
751 .. index::
752    single: -m\* options
753    single: platform-specific options
754    single: machine-specific options
755
756 Some flags only make sense for particular target platforms.
757
758 ``-msse2``
759     (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
760     instruction set to implement floating point operations when using
761     the :ref:`native code generator <native-code-gen>`. This gives a
762     substantial performance improvement for floating point, but the
763     resulting compiled code will only run on processors that support
764     SSE2 (Intel Pentium 4 and later, or AMD Athlon 64 and later). The
765     :ref:`LLVM backend <llvm-code-gen>` will also use SSE2 if your
766     processor supports it but detects this automatically so no flag is
767     required.
768
769     SSE2 is unconditionally used on x86-64 platforms.
770
771 ``-msse4.2``
772     (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to
773     implement some floating point and bit operations when using the
774     :ref:`native code generator <native-code-gen>`. The resulting compiled
775     code will only run on processors that support SSE4.2 (Intel Core i7
776     and later). The :ref:`LLVM backend <llvm-code-gen>` will also use
777     SSE4.2 if your processor supports it but detects this automatically
778     so no flag is required.