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