Merge commit '7b0b9f603bb1215e2b7af23c2404d637b95a4988' as 'hadrian'
[ghc.git] / docs / users_guide / using-optimisation.rst
1 .. _options-optimise:
2
3 Optimisation (code improvement)
4 -------------------------------
5
6 .. index::
7    single: optimisation
8    single: improvement, code
9
10 The ``-O*`` options specify convenient "packages" of optimisation flags;
11 the ``-f*`` options described later on specify *individual*
12 optimisations to be turned on/off; the ``-m*`` options specify
13 *machine-specific* optimisations to be turned on/off.
14
15 Most of these options are boolean and have options to turn them both "on" and
16 "off" (beginning with the prefix ``no-``). For instance, while ``-fspecialise``
17 enables specialisation, ``-fno-specialise`` disables it. When multiple flags for
18 the same option appear in the command-line they are evaluated from left to
19 right. For instance, ``-fno-specialise -fspecialise`` will enable
20 specialisation.
21
22 It is important to note that the ``-O*`` flags are roughly equivalent to
23 combinations of ``-f*`` flags. For this reason, the effect of the
24 ``-O*`` and ``-f*`` flags is dependent upon the order in which they
25 occur on the command line.
26
27 For instance, take the example of ``-fno-specialise -O1``. Despite the
28 ``-fno-specialise`` appearing in the command line, specialisation will
29 still be enabled. This is the case as ``-O1`` implies ``-fspecialise``,
30 overriding the previous flag. By contrast, ``-O1 -fno-specialise`` will
31 compile without specialisation, as one would expect.
32
33 .. _optimise-pkgs:
34
35 ``-O*``: convenient “packages” of optimisation flags.
36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38 There are *many* options that affect the quality of code produced by
39 GHC. Most people only have a general goal, something like "Compile
40 quickly" or "Make my program run like greased lightning." The following
41 "packages" of optimisations (or lack thereof) should suffice.
42
43 Note that higher optimisation levels cause more cross-module
44 optimisation to be performed, which can have an impact on how much of
45 your program needs to be recompiled when you change something. This is
46 one reason to stick to no-optimisation when developing code.
47
48 **No ``-O*``-type option specified:** This is taken to mean “Please 
49 compile quickly; I'm not over-bothered about compiled-code quality.”
50 So, for example, ``ghc -c Foo.hs``
51
52 .. ghc-flag:: -O0
53     :shortdesc: Disable optimisations (default)
54     :type: dynamic
55     :category: optimization-levels
56
57     Means "turn off all optimisation", reverting to the same settings as
58     if no ``-O`` options had been specified. Saying ``-O0`` can be
59     useful if e.g. ``make`` has inserted a ``-O`` on the command line
60     already.
61
62 .. ghc-flag:: -O
63               -O1
64     :shortdesc: Enable level 1 optimisations
65     :type: dynamic
66     :reverse: -O0
67     :category: optimization-levels
68
69     .. index::
70        single: optimise; normally
71
72     Means: "Generate good-quality code without taking too long about
73     it." Thus, for example: ``ghc -c -O Main.lhs``
74
75 .. ghc-flag:: -O2
76     :shortdesc: Enable level 2 optimisations
77     :type: dynamic
78     :reverse: -O0
79     :category: optimization-levels
80
81     .. index::
82        single: optimise; aggressively
83
84     Means: "Apply every non-dangerous optimisation, even if it means
85     significantly longer compile times."
86
87     The avoided "dangerous" optimisations are those that can make
88     runtime or space *worse* if you're unlucky. They are normally turned
89     on or off individually.
90
91 .. ghc-flag:: -Odph
92     :shortdesc: Enable level 2 optimisations, set
93         ``-fmax-simplifier-iterations=20``
94         and ``-fsimplifier-phases=3``.
95     :type: dynamic
96     :category: optimization-levels
97
98     .. index::
99        single: optimise; DPH
100
101     Enables all ``-O2`` optimisation, sets
102     ``-fmax-simplifier-iterations=20`` and ``-fsimplifier-phases=3``.
103     Designed for use with :ref:`Data Parallel Haskell (DPH) <dph>`.
104
105 We don't use a ``-O*`` flag for day-to-day work. We use ``-O`` to get
106 respectable speed; e.g., when we want to measure something. When we want
107 to go for broke, we tend to use ``-O2`` (and we go for lots of coffee
108 breaks).
109
110 The easiest way to see what ``-O`` (etc.) “really mean” is to run with
111 :ghc-flag:`-v`, then stand back in amazement.
112
113 .. _options-f:
114
115 ``-f*``: platform-independent flags
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
118 .. index::
119    single: -f\* options (GHC)
120    single: -fno-\* options (GHC)
121
122 These flags turn on and off individual optimisations. Flags marked as
123 on by default are enabled by ``-O``, and as such you shouldn't
124 need to set any of them explicitly. A flag ``-fwombat`` can be negated
125 by saying ``-fno-wombat``.
126
127 .. ghc-flag:: -fcase-merge
128     :shortdesc: Enable case-merging. Implied by :ghc-flag:`-O`.
129     :type: dynamic
130     :reverse: -fno-case-merge
131     :category:
132
133     :default: on
134
135     Merge immediately-nested case expressions that scrutinise the same variable.
136     For example, ::
137
138           case x of
139              Red -> e1
140              _   -> case x of
141                       Blue -> e2
142                       Green -> e3
143
144     Is transformed to, ::
145
146           case x of
147              Red -> e1
148              Blue -> e2
149              Green -> e2
150
151 .. ghc-flag:: -fcase-folding
152     :shortdesc: Enable constant folding in case expressions. Implied by :ghc-flag:`-O`.
153     :type: dynamic
154     :reverse: -fno-case-folding
155     :category:
156
157     :default: on
158
159     Allow constant folding in case expressions that scrutinise some primops:
160     For example, ::
161
162           case x `minusWord#` 10## of
163              10## -> e1
164              20## -> e2
165              v    -> e3
166
167     Is transformed to, ::
168
169           case x of
170              20## -> e1
171              30## -> e2
172              _    -> let v = x `minusWord#` 10## in e3
173
174 .. ghc-flag:: -fcall-arity
175     :shortdesc: Enable call-arity optimisation. Implied by :ghc-flag:`-O`.
176     :type: dynamic
177     :reverse: -fno-call-arity
178     :category:
179
180     :default: on
181
182     Enable call-arity analysis.
183
184 .. ghc-flag:: -fexitification
185     :shortdesc: Enables exitification optimisation. Implied by :ghc-flag:`-O`.
186     :type: dynamic
187     :reverse: -fno-exitification
188     :category:
189
190     :default: on
191
192     Enables the floating of exit paths out of recursive functions.
193
194 .. ghc-flag:: -fcmm-elim-common-blocks
195     :shortdesc: Enable Cmm common block elimination. Implied by :ghc-flag:`-O`.
196     :type: dynamic
197     :reverse: -fno-cmm-elim-common-blocks
198     :category:
199
200     :default: on
201
202     Enables the common block elimination optimisation
203     in the code generator. This optimisation attempts to find identical
204     Cmm blocks and eliminate the duplicates.
205
206 .. ghc-flag:: -fcmm-sink
207     :shortdesc: Enable Cmm sinking. Implied by :ghc-flag:`-O`.
208     :type: dynamic
209     :reverse: -fno-cmm-sink
210     :category:
211
212     :default: on
213
214     Enables the sinking pass in the code generator.
215     This optimisation attempts to find identical Cmm blocks and
216     eliminate the duplicates attempts to move variable bindings closer
217     to their usage sites. It also inlines simple expressions like
218     literals or registers.
219
220 .. ghc-flag:: -fcpr-anal
221     :shortdesc: Turn on CPR analysis in the demand analyser. Implied by :ghc-flag:`-O`.
222     :type: dynamic
223     :reverse: -fno-cpr-anal
224     :category:
225
226     :default: on
227
228     Turn on CPR analysis in the demand analyser.
229
230 .. ghc-flag:: -fcse
231     :shortdesc: Enable common sub-expression elimination. Implied by :ghc-flag:`-O`.
232     :type: dynamic
233     :reverse: -fno-cse
234     :category:
235
236     :default: on
237
238     Enables the common-sub-expression elimination
239     optimisation. Switching this off can be useful if you have some
240     ``unsafePerformIO`` expressions that you don't want commoned-up.
241
242 .. ghc-flag:: -fstg-cse
243     :shortdesc: Enable common sub-expression elimination on the STG
244         intermediate language
245     :type: dynamic
246     :reverse: -fno-stg-cse
247     :category:
248
249     :default: on
250
251     Enables the common-sub-expression elimination optimisation on the STG
252     intermediate language, where it is able to common up some subexpressions
253     that differ in their types, but not their represetation.
254
255 .. ghc-flag:: -fdicts-cheap
256     :shortdesc: Make dictionary-valued expressions seem cheap to the optimiser.
257     :type: dynamic
258     :reverse: -fno-dicts-cheap
259     :category:
260
261     :default: off
262
263     A very experimental flag that makes dictionary-valued expressions
264     seem cheap to the optimiser.
265
266 .. ghc-flag:: -fdicts-strict
267     :shortdesc: Make dictionaries strict
268     :type: dynamic
269     :reverse: -fno-dicts-strict
270     :category:
271
272     :default: off
273
274     Make dictionaries strict.
275
276 .. ghc-flag:: -fdmd-tx-dict-sel
277     :shortdesc: Use a special demand transformer for dictionary selectors.
278         Always enabled by default.
279     :type: dynamic
280     :reverse: -fno-dmd-tx-dict-sel
281     :category:
282
283     :default: on
284
285     Use a special demand transformer for dictionary selectors.
286
287 .. ghc-flag:: -fdo-eta-reduction
288     :shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`.
289     :type: dynamic
290     :reverse: -fno-do-eta-reduction
291     :category:
292
293     :default: on
294
295     Eta-reduce lambda expressions, if doing so gets rid of a whole group of
296     lambdas.
297
298 .. ghc-flag:: -fdo-lambda-eta-expansion
299     :shortdesc: Enable lambda eta-expansion. Always enabled by default.
300     :type: dynamic
301     :reverse: -fno-do-lambda-eta-expansion
302     :category:
303
304     :default: on
305
306     Eta-expand let-bindings to increase their arity.
307
308 .. ghc-flag:: -feager-blackholing
309     :shortdesc: Turn on :ref:`eager blackholing <parallel-compile-options>`
310     :type: dynamic
311     :category:
312
313     :default: off
314
315     Usually GHC black-holes a thunk only when it switches threads. This
316     flag makes it do so as soon as the thunk is entered. See `Haskell on
317     a shared-memory
318     multiprocessor <http://community.haskell.org/~simonmar/papers/multiproc.pdf>`__.
319
320     See :ref:`parallel-compile-options` for a dicussion on its use.
321
322 .. ghc-flag:: -fexcess-precision
323     :shortdesc: Enable excess intermediate precision
324     :type: dynamic
325     :reverse: -fno-excess-precision
326     :category:
327
328     :default: off
329
330     When this option is given, intermediate floating point values can
331     have a *greater* precision/range than the final type. Generally this
332     is a good thing, but some programs may rely on the exact
333     precision/range of ``Float``/``Double`` values and should not use
334     this option for their compilation.
335
336     Note that the 32-bit x86 native code generator only supports
337     excess-precision mode, so neither ``-fexcess-precision`` nor
338     ``-fno-excess-precision`` has any effect. This is a known bug, see
339     :ref:`bugs-ghc`.
340
341 .. ghc-flag:: -fexpose-all-unfoldings
342     :shortdesc: Expose all unfoldings, even for very large or recursive functions.
343     :type: dynamic
344     :reverse: -fno-expose-all-unfoldings
345     :category:
346
347     :default: off
348
349     An experimental flag to expose all unfoldings, even for very large
350     or recursive functions. This allows for all functions to be inlined
351     while usually GHC would avoid inlining larger functions.
352
353 .. ghc-flag:: -ffloat-in
354     :shortdesc: Turn on the float-in transformation. Implied by :ghc-flag:`-O`.
355     :type: dynamic
356     :reverse: -fno-float-in
357     :category:
358
359     :default: on
360
361     Float let-bindings inwards, nearer their binding
362     site. See `Let-floating: moving bindings to give faster programs
363     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
364
365     This optimisation moves let bindings closer to their use site. The
366     benefit here is that this may avoid unnecessary allocation if the
367     branch the let is now on is never executed. It also enables other
368     optimisation passes to work more effectively as they have more
369     information locally.
370
371     This optimisation isn't always beneficial though (so GHC applies
372     some heuristics to decide when to apply it). The details get
373     complicated but a simple example is that it is often beneficial to
374     move let bindings outwards so that multiple let bindings can be
375     grouped into a larger single let binding, effectively batching their
376     allocation and helping the garbage collector and allocator.
377
378 .. ghc-flag:: -ffull-laziness
379     :shortdesc: Turn on full laziness (floating bindings outwards).
380         Implied by :ghc-flag:`-O`.
381     :type: dynamic
382     :reverse: -fno-full-laziness
383     :category:
384
385     :default: on
386
387     Run the full laziness optimisation (also known as
388     let-floating), which floats let-bindings outside enclosing lambdas,
389     in the hope they will be thereby be computed less often. See
390     `Let-floating: moving bindings to give faster programs
391     (ICFP'96) <http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz>`__.
392     Full laziness increases sharing, which can lead to increased memory
393     residency.
394
395     .. note::
396        GHC doesn't implement complete full-laziness. When
397        optimisation in on, and ``-fno-full-laziness`` is not given, some
398        transformations that increase sharing are performed, such as
399        extracting repeated computations from a loop. These are the same
400        transformations that a fully lazy implementation would do, the
401        difference is that GHC doesn't consistently apply full-laziness, so
402        don't rely on it.
403
404 .. ghc-flag:: -ffun-to-thunk
405     :shortdesc: Allow worker-wrapper to convert a function closure into a thunk
406         if the function does not use any of its arguments. Off by default.
407     :type: dynamic
408     :reverse: -fno-fun-to-thunk
409     :category:
410
411     :default: off
412
413     Worker-wrapper removes unused arguments, but usually we do not
414     remove them all, lest it turn a function closure into a thunk,
415     thereby perhaps creating a space leak and/or disrupting inlining.
416     This flag allows worker/wrapper to remove *all* value lambdas.
417
418 .. ghc-flag:: -fignore-asserts
419     :shortdesc: Ignore assertions in the source. Implied by :ghc-flag:`-O`.
420     :type: dynamic
421     :reverse: -fno-ignore-asserts
422     :category:
423
424     :default: on
425
426     Causes GHC to ignore uses of the function ``Exception.assert`` in source
427     code (in other words, rewriting ``Exception.assert p e`` to ``e`` (see
428     :ref:`assertions`).
429
430 .. ghc-flag:: -fignore-interface-pragmas
431     :shortdesc: Ignore pragmas in interface files. Implied by :ghc-flag:`-O0` only.
432     :type: dynamic
433     :reverse: -fno-ignore-interface-pragmas
434     :category:
435
436     :default: off
437
438     Tells GHC to ignore all inessential information when reading
439     interface files. That is, even if :file:`M.hi` contains unfolding or
440     strictness information for a function, GHC will ignore that
441     information.
442
443 .. ghc-flag:: -flate-dmd-anal
444     :shortdesc: Run demand analysis again, at the end of the
445         simplification pipeline
446     :type: dynamic
447     :reverse: -fno-late-dmd-anal
448     :category:
449
450     :default: off
451
452     Run demand analysis again, at the end of the simplification
453     pipeline. We found some opportunities for discovering strictness
454     that were not visible earlier; and optimisations like
455     :ghc-flag:`-fspec-constr` can create functions with unused arguments which
456     are eliminated by late demand analysis. Improvements are modest, but
457     so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`.
458
459 .. ghc-flag:: -fliberate-case
460     :shortdesc: Turn on the liberate-case transformation. Implied by :ghc-flag:`-O2`.
461     :type: dynamic
462     :reverse: -fno-liberate-case
463     :category:
464
465     :default: off but enabled with :ghc-flag:`-O2`.
466
467     Turn on the liberate-case transformation. This unrolls recursive function
468     once in its own RHS, to avoid repeated case analysis of free variables. It's
469     a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for
470     free variables rather than arguments.
471
472 .. ghc-flag:: -fliberate-case-threshold=⟨n⟩
473     :shortdesc: *default: 2000.* Set the size threshold for the liberate-case
474         transformation to ⟨n⟩
475     :type: dynamic
476     :reverse: -fno-liberate-case-threshold
477     :category:
478
479     :default: 2000
480
481     Set the size threshold for the liberate-case transformation.
482
483 .. ghc-flag:: -floopification
484     :shortdesc: Turn saturated self-recursive tail-calls into local jumps in the
485         generated assembly. Implied by :ghc-flag:`-O`.
486     :type: dynamic
487     :reverse: -fno-loopification
488     :category:
489
490     :default: on
491
492     When this optimisation is enabled the code generator will turn all
493     self-recursive saturated tail calls into local jumps rather than
494     function calls.
495
496 .. ghc-flag:: -fllvm-pass-vectors-in-regs
497     :shortdesc: Pass vector value in vector registers for function calls
498     :type: dynamic
499     :reverse: -fno-llvm-pass-vectors-in-regs
500     :category:
501
502     :default: on
503
504     Instructs GHC to use the platform's native vector registers to pass vector
505     arguments during function calls. As with all vector support, this requires
506     :ghc-flag:`-fllvm`.
507
508 .. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩
509     :shortdesc: *default: 128.* Set the maximum size of inline array allocations
510         to ⟨n⟩ bytes (default: 128).
511     :type: dynamic
512     :category:
513
514     :default: 128
515
516     Set the maximum size of inline array allocations to n bytes.
517     GHC will allocate non-pinned arrays of statically known size in the current
518     nursery block if they're no bigger than n bytes, ignoring GC overheap. This
519     value should be quite a bit smaller than the block size (typically: 4096).
520
521 .. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩
522     :shortdesc: *default: 32.* Inline ``memcpy`` calls if they would generate no
523         more than ⟨n⟩ pseudo instructions.
524     :type: dynamic
525     :category:
526
527     :default: 32
528
529     Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions.
530
531 .. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩
532     :shortdesc: *default: 32.* Inline ``memset`` calls if they would generate no
533         more than ⟨n⟩ pseudo instructions
534     :type: dynamic
535     :category:
536
537     :default: 32
538
539     Inline ``memset`` calls if they would generate no more than n pseudo
540     instructions.
541
542 .. ghc-flag:: -fmax-relevant-binds=⟨n⟩
543     :shortdesc: *default: 6.* Set the maximum number of bindings to display in
544         type error messages.
545     :type: dynamic
546     :reverse: -fno-max-relevant-bindings
547     :category:
548
549     :default: 6
550
551     The type checker sometimes displays a fragment of the type
552     environment in error messages, but only up to some maximum number,
553     set by this flag. Turning it off with
554     ``-fno-max-relevant-bindings`` gives an unlimited number.
555     Syntactically top-level bindings are also usually excluded (since
556     they may be numerous), but ``-fno-max-relevant-bindings`` includes
557     them too.
558
559 .. ghc-flag:: -fmax-valid-substitutions=⟨n⟩
560     :shortdesc: *default: 6.* Set the maximum number of valid substitutions for
561         typed holes to display in type error messages.
562     :type: dynamic
563     :reverse: -fno-max-valid-substitutions
564     :category:
565
566     :default: 6
567
568     The type checker sometimes displays a list of valid substitutions
569     for typed holes in error messages, but only up to some maximum number,
570     set by this flag. Turning it off with
571     ``-fno-max-valid-substitutions`` gives an unlimited number.
572
573 .. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩
574     :shortdesc: *default: 4.* Set the maximum number of patterns to display in
575         warnings about non-exhaustive ones.
576     :type: dynamic
577     :category:
578
579     :default: 4
580
581     Maximum number of unmatched patterns to be shown in warnings generated by
582     :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`.
583
584 .. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩
585     :shortdesc: *default: 4.* Set the max iterations for the simplifier.
586     :type: dynamic
587     :category:
588
589     :default: 4
590
591     Sets the maximal number of iterations for the simplifier.
592
593 .. ghc-flag:: -fmax-worker-args=⟨n⟩
594     :shortdesc: *default: 10.* If a worker has that many arguments, none will
595         be unpacked anymore.
596     :type: dynamic
597     :category:
598
599     :default: 10
600
601     If a worker has that many arguments, none will be unpacked anymore.
602
603 .. ghc-flag:: -fno-opt-coercion
604     :shortdesc: Turn off the coercion optimiser
605     :type: dynamic
606     :category:
607
608     :default: coercion optimisation enabled.
609
610     Turn off the coercion optimiser.
611
612 .. ghc-flag:: -fno-pre-inlining
613     :shortdesc: Turn off pre-inlining
614     :type: dynamic
615     :category:
616
617     :default: pre-inlining enabled
618
619     Turn off pre-inlining.
620
621 .. ghc-flag:: -fno-state-hack
622     :shortdesc: Turn off the \state hack\ whereby any lambda with a real-world
623         state token as argument is considered to be single-entry. Hence
624         OK to inline things inside it.
625     :type: dynamic
626     :category:
627
628     :default: state hack is enabled
629
630     Turn off the "state hack" whereby any lambda with a ``State#`` token
631     as argument is considered to be single-entry, hence it is considered
632     okay to inline things inside it. This can improve performance of IO
633     and ST monad code, but it runs the risk of reducing sharing.
634
635 .. ghc-flag:: -fomit-interface-pragmas
636     :shortdesc: Don't generate interface pragmas. Implied by :ghc-flag:`-O0` only.
637     :type: dynamic
638     :reverse: -fno-omit-interface-pragmas
639     :category:
640
641     :default: Implied by :ghc-flag:`-O0`, otherwise off.
642
643     Tells GHC to omit all inessential information from the interface
644     file generated for the module being compiled (say M). This means
645     that a module importing M will see only the *types* of the functions
646     that M exports, but not their unfoldings, strictness info, etc.
647     Hence, for example, no function exported by M will be inlined into
648     an importing module. The benefit is that modules that import M will
649     need to be recompiled less often (only when M's exports change their
650     type, not when they change their implementation).
651
652 .. ghc-flag:: -fomit-yields
653     :shortdesc: Omit heap checks when no allocation is being performed.
654     :type: dynamic
655     :reverse: -fno-omit-yields
656     :category:
657
658     :default: yield points enabled
659
660     Tells GHC to omit heap checks when no allocation is
661     being performed. While this improves binary sizes by about 5%, it
662     also means that threads run in tight non-allocating loops will not
663     get preempted in a timely fashion. If it is important to always be
664     able to interrupt such threads, you should turn this optimization
665     off. Consider also recompiling all libraries with this optimization
666     turned off, if you need to guarantee interruptibility.
667
668 .. ghc-flag:: -fpedantic-bottoms
669     :shortdesc: Make GHC be more precise about its treatment of bottom (but see
670         also :ghc-flag:`-fno-state-hack`). In particular, GHC will not
671         eta-expand through a case expression.
672     :type: dynamic
673     :reverse: -fno-pedantic-bottoms
674     :category:
675
676     :default: off
677
678     Make GHC be more precise about its treatment of bottom (but see also
679     :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through
680     a case expression, which is good for performance, but bad if you are
681     using ``seq`` on partial applications.
682
683 .. ghc-flag:: -fregs-graph
684     :shortdesc: Use the graph colouring register allocator for register
685         allocation in the native code generator. Implied by :ghc-flag:`-O2`.
686     :type: dynamic
687     :reverse: -fno-regs-graph
688     :category:
689
690     :default: off due to a performance regression bug (:ghc-ticket:`7679`)
691
692     *Only applies in combination with the native code generator.* Use the graph
693     colouring register allocator for register allocation in the native code
694     generator. By default, GHC uses a simpler, faster linear register allocator.
695     The downside being that the linear register allocator usually generates
696     worse code.
697
698     Note that the graph colouring allocator is a bit experimental and may fail
699     when faced with code with high register pressure :ghc-ticket:`8657`.
700
701 .. ghc-flag:: -fregs-iterative
702     :shortdesc: Use the iterative coalescing graph colouring register allocator
703         in the native code generator.
704     :type: dynamic
705     :reverse: -fno-regs-iterative
706     :category:
707
708     :default: off
709
710     *Only applies in combination with the native code generator.* Use the
711     iterative coalescing graph colouring register allocator for register
712     allocation in the native code generator. This is the same register allocator
713     as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing
714     during register allocation.
715
716 .. ghc-flag:: -fsimplifier-phases=⟨n⟩
717     :shortdesc: *default: 2.* Set the number of phases for the simplifier.
718         Ignored with :ghc-flag:`-O0`.
719     :type: dynamic
720     :category:
721
722     :default: 2
723
724     Set the number of phases for the simplifier. Ignored with ``-O0``.
725
726 .. ghc-flag:: -fsimpl-tick-factor=⟨n⟩
727     :shortdesc: *default: 100.* Set the percentage factor for simplifier ticks.
728     :type: dynamic
729     :category:
730
731     :default: 100
732
733     GHC's optimiser can diverge if you write rewrite rules
734     (:ref:`rewrite-rules`) that don't terminate, or (less satisfactorily)
735     if you code up recursion through data types (:ref:`bugs-ghc`). To
736     avoid making the compiler fall into an infinite loop, the optimiser
737     carries a "tick count" and stops inlining and applying rewrite rules
738     when this count is exceeded. The limit is set as a multiple of the
739     program size, so bigger programs get more ticks. The
740     ``-fsimpl-tick-factor`` flag lets you change the multiplier. The
741     default is 100; numbers larger than 100 give more ticks, and numbers
742     smaller than 100 give fewer.
743
744     If the tick-count expires, GHC summarises what simplifier steps it
745     has done; you can use ``-fddump-simpl-stats`` to generate a much
746     more detailed list. Usually that identifies the loop quite
747     accurately, because some numbers are very large.
748
749 .. ghc-flag:: -fspec-constr
750     :shortdesc: Turn on the SpecConstr transformation. Implied by :ghc-flag:`-O2`.
751     :type: dynamic
752     :reverse: -fno-spec-constr
753     :category:
754
755     :default: off but enabled by :ghc-flag:`-O2`.
756
757     Turn on call-pattern specialisation; see `Call-pattern specialisation for
758     Haskell programs
759     <https://www.microsoft.com/en-us/research/publication/system-f-with-type-equality-coercions-2/>`__.
760
761     This optimisation specializes recursive functions according to their
762     argument "shapes". This is best explained by example so consider: ::
763
764         last :: [a] -> a
765         last [] = error "last"
766         last (x : []) = x
767         last (x : xs) = last xs
768
769     In this code, once we pass the initial check for an empty list we
770     know that in the recursive case this pattern match is redundant. As
771     such ``-fspec-constr`` will transform the above code to: ::
772
773         last :: [a] -> a
774         last []       = error "last"
775         last (x : xs) = last' x xs
776             where
777               last' x []       = x
778               last' x (y : ys) = last' y ys
779
780     As well avoid unnecessary pattern matching it also helps avoid
781     unnecessary allocation. This applies when a argument is strict in
782     the recursive call to itself but not on the initial entry. As strict
783     recursive branch of the function is created similar to the above
784     example.
785
786     It is also possible for library writers to instruct GHC to perform
787     call-pattern specialisation extremely aggressively. This is
788     necessary for some highly optimized libraries, where we may want to
789     specialize regardless of the number of specialisations, or the size
790     of the code. As an example, consider a simplified use-case from the
791     ``vector`` library: ::
792
793         import GHC.Types (SPEC(..))
794
795         foldl :: (a -> b -> a) -> a -> Stream b -> a
796         {-# INLINE foldl #-}
797         foldl f z (Stream step s _) = foldl_loop SPEC z s
798           where
799             foldl_loop !sPEC z s = case step s of
800                                     Yield x s' -> foldl_loop sPEC (f z x) s'
801                                     Skip       -> foldl_loop sPEC z s'
802                                     Done       -> z
803
804     Here, after GHC inlines the body of ``foldl`` to a call site, it
805     will perform call-pattern specialisation very aggressively on
806     ``foldl_loop`` due to the use of ``SPEC`` in the argument of the
807     loop body. ``SPEC`` from ``GHC.Types`` is specifically recognised by
808     the compiler.
809
810     (NB: it is extremely important you use ``seq`` or a bang pattern on
811     the ``SPEC`` argument!)
812
813     In particular, after inlining this will expose ``f`` to the loop
814     body directly, allowing heavy specialisation over the recursive
815     cases.
816
817 .. ghc-flag:: -fspec-constr-keen
818     :shortdesc: Specialize a call with an explicit constructor argument,
819         even if the argument is not scrutinised in the body of the function
820     :type: dynamic
821     :reverse: -fno-spec-constr-keen
822     :category:
823
824     :default: off
825
826     If this flag is on, call-pattern specialisation will specialise a call
827     ``(f (Just x))`` with an explicit constructor argument, even if the argument
828     is not scrutinised in the body of the function. This is sometimes
829     beneficial; e.g. the argument might be given to some other function
830     that can itself be specialised.
831
832 .. ghc-flag:: -fspec-constr-count=⟨n⟩
833     :shortdesc: default: 3.* Set to ⟨n⟩ the maximum number of specialisations that
834         will be created for any one function by the SpecConstr
835         transformation.
836     :type: dynamic
837     :reverse: -fno-spec-constr-count
838     :category:
839
840     :default: 3
841
842     Set the maximum number of specialisations that will be created for
843     any one function by the SpecConstr transformation.
844
845 .. ghc-flag:: -fspec-constr-threshold=⟨n⟩
846     :shortdesc: *default: 2000.* Set the size threshold for the SpecConstr
847         transformation to ⟨n⟩.
848     :type: dynamic
849     :reverse: -fno-spec-constr-threshold
850     :category:
851
852     :default: 2000
853
854     Set the size threshold for the SpecConstr transformation.
855
856 .. ghc-flag:: -fspecialise
857     :shortdesc: Turn on specialisation of overloaded functions. Implied by :ghc-flag:`-O`.
858     :type: dynamic
859     :reverse: -fno-specialise
860     :category:
861
862     :default: on
863
864     Specialise each type-class-overloaded function
865     defined in this module for the types at which it is called in this
866     module. If :ghc-flag:`-fcross-module-specialise` is set imported functions
867     that have an INLINABLE pragma (:ref:`inlinable-pragma`) will be
868     specialised as well.
869
870 .. ghc-flag:: -fspecialise-aggressively
871     :shortdesc: Turn on specialisation of overloaded functions regardless of
872         size, if unfolding is available
873     :type: dynamic
874     :reverse: -fno-specialise-aggressively
875     :category:
876
877     :default: off
878
879     By default only type class methods and methods marked ``INLINABLE`` or
880     ``INLINE`` are specialised. This flag will specialise any overloaded function
881     regardless of size if its unfolding is available. This flag is not
882     included in any optimisation level as it can massively increase code
883     size. It can be used in conjunction with :ghc-flag:`-fexpose-all-unfoldings`
884     if you want to ensure all calls are specialised.
885
886
887 .. ghc-flag:: -fcross-module-specialise
888     :shortdesc: Turn on specialisation of overloaded functions imported from
889         other modules.
890     :type: dynamic
891     :reverse: -fno-cross-module-specialise
892     :category:
893
894     :default: on
895
896     Specialise ``INLINABLE`` (:ref:`inlinable-pragma`)
897     type-class-overloaded functions imported from other modules for the types at
898     which they are called in this module. Note that specialisation must be
899     enabled (by ``-fspecialise``) for this to have any effect.
900
901 .. ghc-flag:: -fsolve-constant-dicts
902     :shortdesc: When solving constraints, try to eagerly solve
903         super classes using available dictionaries.
904     :type: dynamic
905     :reverse: -fno-solve-constant-dicts
906     :category:
907
908     :default: on
909
910     When solving constraints, try to eagerly solve
911     super classes using available dictionaries.
912
913     For example::
914
915       class M a b where m :: a -> b
916
917       type C a b = (Num a, M a b)
918
919       f :: C Int b => b -> Int -> Int
920       f _ x = x + 1
921
922     The body of `f` requires a `Num Int` instance. We could solve this
923     constraint from the context  because we have `C Int b` and that provides us
924     a
925     solution for `Num Int`. However, we can often produce much better code
926     by directly solving for an available `Num Int` dictionary we might have at
927     hand. This removes potentially many layers of indirection and crucially
928     allows other optimisations to fire as the dictionary will be statically
929     known and selector functions can be inlined.
930
931     The optimisation also works for GADTs which bind dictionaries. If we
932     statically know which class dictionary we need then we will solve it
933     directly rather than indirectly using the one passed in at run time.
934
935
936
937 .. ghc-flag:: -fstatic-argument-transformation
938     :shortdesc: Turn on the static argument transformation.
939     :type: dynamic
940     :reverse: -fno-static-argument-transformation
941     :category:
942
943     :default: off
944
945     Turn on the static argument transformation, which turns a recursive
946     function into a non-recursive one with a local recursive loop. See
947     Chapter 7 of `Andre Santos's PhD
948     thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__
949
950 .. ghc-flag:: -fstrictness
951     :shortdesc: Turn on strictness analysis.
952         Implied by :ghc-flag:`-O`. Implies :ghc-flag:`-fworker-wrapper`
953     :type: dynamic
954     :reverse: -fno-strictness
955     :category:
956
957     :default: on
958
959     Switch on the strictness analyser. The
960     implementation is described in the paper `Theory and Practice of Demand Analysis in Haskell`<https://www.microsoft.com/en-us/research/wp-content/uploads/2017/03/demand-jfp-draft.pdf>`__.
961
962     The strictness analyser figures out when arguments and variables in
963     a function can be treated 'strictly' (that is they are always
964     evaluated in the function at some point). This allow GHC to apply
965     certain optimisations such as unboxing that otherwise don't apply as
966     they change the semantics of the program when applied to lazy
967     arguments.
968
969 .. ghc-flag:: -fstrictness-before=⟨n⟩
970     :shortdesc: Run an additional strictness analysis before simplifier phase ⟨n⟩
971     :type: dynamic
972     :category:
973
974     Run an additional strictness analysis before simplifier phase ⟨n⟩.
975
976 .. ghc-flag:: -funbox-small-strict-fields
977     :shortdesc: Flatten strict constructor fields with a pointer-sized
978         representation. Implied by :ghc-flag:`-O`.
979     :type: dynamic
980     :reverse: -fno-unbox-small-strict-fields
981     :category:
982
983     :default: on
984
985     .. index::
986        single: strict constructor fields
987        single: constructor fields, strict
988
989     This option causes all constructor fields which
990     are marked strict (i.e. “!”) and which representation is smaller or
991     equal to the size of a pointer to be unpacked, if possible. It is
992     equivalent to adding an ``UNPACK`` pragma (see :ref:`unpack-pragma`)
993     to every strict constructor field that fulfils the size restriction.
994
995     For example, the constructor fields in the following data types ::
996
997         data A = A !Int
998         data B = B !A
999         newtype C = C B
1000         data D = D !C
1001
1002     would all be represented by a single ``Int#`` (see
1003     :ref:`primitives`) value with ``-funbox-small-strict-fields``
1004     enabled.
1005
1006     This option is less of a sledgehammer than
1007     ``-funbox-strict-fields``: it should rarely make things worse. If
1008     you use ``-funbox-small-strict-fields`` to turn on unboxing by
1009     default you can disable it for certain constructor fields using the
1010     ``NOUNPACK`` pragma (see :ref:`nounpack-pragma`).
1011
1012     Note that for consistency ``Double``, ``Word64``, and ``Int64``
1013     constructor fields are unpacked on 32-bit platforms, even though
1014     they are technically larger than a pointer on those platforms.
1015
1016 .. ghc-flag:: -funbox-strict-fields
1017     :shortdesc: Flatten strict constructor fields
1018     :type: dynamic
1019     :reverse: -fno-unbox-strict-fields
1020     :category:
1021
1022     :default: off
1023
1024     .. index::
1025        single: strict constructor fields
1026        single: constructor fields, strict
1027
1028     This option causes all constructor fields which are marked strict
1029     (i.e. ``!``) to be unpacked if possible. It is equivalent to adding an
1030     ``UNPACK`` pragma to every strict constructor field (see
1031     :ref:`unpack-pragma`).
1032
1033     This option is a bit of a sledgehammer: it might sometimes make
1034     things worse. Selectively unboxing fields by using ``UNPACK``
1035     pragmas might be better. An alternative is to use
1036     ``-funbox-strict-fields`` to turn on unboxing by default but disable
1037     it for certain constructor fields using the ``NOUNPACK`` pragma (see
1038     :ref:`nounpack-pragma`).
1039
1040     Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only
1041     unbox strict fields which are "small".
1042
1043 .. ghc-flag:: -funfolding-creation-threshold=⟨n⟩
1044     :shortdesc: *default: 750.* Tweak unfolding settings.
1045     :type: dynamic
1046     :category:
1047
1048     :default: 750
1049
1050     .. index::
1051        single: inlining, controlling
1052        single: unfolding, controlling
1053
1054     Governs the maximum size that GHC will allow a
1055     function unfolding to be. (An unfolding has a “size” that reflects
1056     the cost in terms of “code bloat” of expanding (aka inlining) that
1057     unfolding at a call site. A bigger function would be assigned a
1058     bigger cost.)
1059
1060     Consequences:
1061
1062     a. nothing larger than this will be inlined (unless it has an ``INLINE`` pragma)
1063     b. nothing larger than this will be spewed into an interface file.
1064
1065     Increasing this figure is more likely to result in longer compile times
1066     than faster code. The :ghc-flag:`-funfolding-use-threshold=⟨n⟩` is more
1067     useful.
1068
1069 .. ghc-flag:: -funfolding-dict-discount=⟨n⟩
1070     :shortdesc: *default: 30.* Tweak unfolding settings.
1071     :type: dynamic
1072     :category:
1073
1074     :default: 30
1075
1076     .. index::
1077        single: inlining, controlling
1078        single: unfolding, controlling
1079
1080     How eager should the compiler be to inline dictionaries?
1081
1082 .. ghc-flag:: -funfolding-fun-discount=⟨n⟩
1083     :shortdesc: *default: 60.* Tweak unfolding settings.
1084     :type: dynamic
1085     :category:
1086
1087     :default: 60
1088
1089     .. index::
1090        single: inlining, controlling
1091        single: unfolding, controlling
1092
1093     How eager should the compiler be to inline functions?
1094
1095 .. ghc-flag:: -funfolding-keeness-factor=⟨n⟩
1096     :shortdesc: *default: 1.5.* Tweak unfolding settings.
1097     :type: dynamic
1098     :category:
1099
1100     :default: 1.5
1101
1102     .. index::
1103        single: inlining, controlling
1104        single: unfolding, controlling
1105
1106     How eager should the compiler be to inline functions?
1107
1108 .. ghc-flag:: -funfolding-use-threshold=⟨n⟩
1109     :shortdesc: *default: 60.* Tweak unfolding settings.
1110     :type: dynamic
1111     :category:
1112
1113     :default: 60
1114
1115     .. index::
1116        single: inlining, controlling
1117        single: unfolding, controlling
1118
1119     This is the magic cut-off figure for unfolding (aka
1120     inlining): below this size, a function definition will be unfolded
1121     at the call-site, any bigger and it won't. The size computed for a
1122     function depends on two things: the actual size of the expression
1123     minus any discounts that apply depending on the context into which
1124     the expression is to be inlined.
1125
1126     The difference between this and
1127     :ghc-flag:`-funfolding-creation-threshold=⟨n⟩` is that this one determines
1128     if a function definition will be inlined *at a call site*. The other option
1129     determines if a function definition will be kept around at all for
1130     potential inlining.
1131
1132 .. ghc-flag:: -fvectorisation-avoidance
1133     :shortdesc: Enable vectorisation avoidance. Always enabled by default.
1134     :type: dynamic
1135     :reverse: -fno-vectorisation-avoidance
1136     :category:
1137
1138     :default: on
1139
1140     .. index::
1141        single: -fvectorisation-avoidance
1142
1143     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
1144
1145     Enable the *vectorisation* avoidance optimisation.
1146     This optimisation only works when used in combination with the
1147     ``-fvectorise`` transformation.
1148
1149     While vectorisation of code using DPH is often a big win, it can
1150     also produce worse results for some kinds of code. This optimisation
1151     modifies the vectorisation transformation to try to determine if a
1152     function would be better of unvectorised and if so, do just that.
1153
1154 .. ghc-flag:: -fvectorise
1155     :shortdesc: Enable vectorisation of nested data parallelism
1156     :type: dynamic
1157     :reverse: -fno-vectorise
1158     :category:
1159
1160     :default: off
1161
1162     Part of :ref:`Data Parallel Haskell (DPH) <dph>`.
1163
1164     Enable the *vectorisation* optimisation
1165     transformation. This optimisation transforms the nested data
1166     parallelism code of programs using DPH into flat data parallelism.
1167     Flat data parallel programs should have better load balancing,
1168     enable SIMD parallelism and friendlier cache behaviour.