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