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