diff options
Diffstat (limited to 'docs/users_guide/using-optimisation.rst')
| -rw-r--r-- | docs/users_guide/using-optimisation.rst | 285 |
1 files changed, 283 insertions, 2 deletions
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index 15916b2690..763c778872 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -50,6 +50,10 @@ compile quickly; I'm not over-bothered about compiled-code quality.” So, for example, ``ghc -c Foo.hs`` .. ghc-flag:: -O0 + :shortdesc: Disable optimisations (default) + :type: dynamic + :reverse: -O + :category: optimization-levels Means "turn off all optimisation", reverting to the same settings as if no ``-O`` options had been specified. Saying ``-O0`` can be @@ -58,6 +62,10 @@ So, for example, ``ghc -c Foo.hs`` .. ghc-flag:: -O -O1 + :shortdesc: Enable level 1 optimisations + :type: dynamic + :reverse: -O0 + :category: optimization-levels .. index:: single: optimise; normally @@ -66,6 +74,10 @@ So, for example, ``ghc -c Foo.hs`` it." Thus, for example: ``ghc -c -O Main.lhs`` .. ghc-flag:: -O2 + :shortdesc: Enable level 2 optimisations + :type: dynamic + :reverse: -O0 + :category: optimization-levels .. index:: single: optimise; aggressively @@ -78,6 +90,11 @@ So, for example, ``ghc -c Foo.hs`` on or off individually. .. ghc-flag:: -Odph + :shortdesc: Enable level 2 optimisations, set + ``-fmax-simplifier-iterations=20`` + and ``-fsimplifier-phases=3``. + :type: dynamic + :category: optimization-levels .. index:: single: optimise; DPH @@ -109,6 +126,10 @@ need to set any of them explicitly. A flag ``-fwombat`` can be negated by saying ``-fno-wombat``. .. ghc-flag:: -fcase-merge + :shortdesc: Enable case-merging. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-case-merge + :category: :default: on @@ -129,6 +150,10 @@ by saying ``-fno-wombat``. Green -> e2 .. ghc-flag:: -fcase-folding + :shortdesc: Enable constant folding in case expressions. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-case-folding + :category: :default: on @@ -148,12 +173,20 @@ by saying ``-fno-wombat``. _ -> let v = x `minusWord#` 10## in e3 .. ghc-flag:: -fcall-arity + :shortdesc: Enable call-arity optimisation. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-call-arity + :category: :default: on Enable call-arity analysis. .. ghc-flag:: -fcmm-elim-common-blocks + :shortdesc: Enable Cmm common block elimination. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-cmm-elim-common-blocks + :category: :default: on @@ -162,6 +195,10 @@ by saying ``-fno-wombat``. Cmm blocks and eliminate the duplicates. .. ghc-flag:: -fcmm-sink + :shortdesc: Enable Cmm sinking. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-cmm-sink + :category: :default: on @@ -172,12 +209,20 @@ by saying ``-fno-wombat``. literals or registers. .. ghc-flag:: -fcpr-anal + :shortdesc: Turn on CPR analysis in the demand analyser. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-cpr-anal + :category: :default: on Turn on CPR analysis in the demand analyser. .. ghc-flag:: -fcse + :shortdesc: Enable common sub-expression elimination. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-cse + :category: :default: on @@ -186,6 +231,11 @@ by saying ``-fno-wombat``. ``unsafePerformIO`` expressions that you don't want commoned-up. .. ghc-flag:: -fstg-cse + :shortdesc: Enable common sub-expression elimination on the STG + intermediate language + :type: dynamic + :reverse: -fno-stg-cse + :category: :default: on @@ -194,6 +244,10 @@ by saying ``-fno-wombat``. that differ in their types, but not their represetation. .. ghc-flag:: -fdicts-cheap + :shortdesc: Make dictionary-valued expressions seem cheap to the optimiser. + :type: dynamic + :reverse: -fno-dicts-cheap + :category: :default: off @@ -201,18 +255,31 @@ by saying ``-fno-wombat``. seem cheap to the optimiser. .. ghc-flag:: -fdicts-strict + :shortdesc: Make dictionaries strict + :type: dynamic + :reverse: -fno-dicts-strict + :category: :default: off Make dictionaries strict. .. ghc-flag:: -fdmd-tx-dict-sel + :shortdesc: Use a special demand transformer for dictionary selectors. + Always enabled by default. + :type: dynamic + :reverse: -fno-dmd-tx-dict-sel + :category: :default: on Use a special demand transformer for dictionary selectors. .. ghc-flag:: -fdo-eta-reduction + :shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-do-eta-reduction + :category: :default: on @@ -220,12 +287,19 @@ by saying ``-fno-wombat``. lambdas. .. ghc-flag:: -fdo-lambda-eta-expansion + :shortdesc: Enable lambda eta-expansion. Always enabled by default. + :type: dynamic + :reverse: -fno-do-lambda-eta-expansion + :category: :default: on Eta-expand let-bindings to increase their arity. .. ghc-flag:: -feager-blackholing + :shortdesc: Turn on :ref:`eager blackholing <parallel-compile-options>` + :type: dynamic + :category: :default: off @@ -234,7 +308,13 @@ by saying ``-fno-wombat``. a shared-memory multiprocessor <http://community.haskell.org/~simonmar/papers/multiproc.pdf>`__. + See :ref:`parallel-compile-options` for a dicussion on its use. + .. ghc-flag:: -fexcess-precision + :shortdesc: Enable excess intermediate precision + :type: dynamic + :reverse: -fno-excess-precision + :category: :default: off @@ -250,6 +330,10 @@ by saying ``-fno-wombat``. :ref:`bugs-ghc`. .. ghc-flag:: -fexpose-all-unfoldings + :shortdesc: Expose all unfoldings, even for very large or recursive functions. + :type: dynamic + :reverse: -fno-expose-all-unfoldings + :category: :default: off @@ -258,6 +342,10 @@ by saying ``-fno-wombat``. while usually GHC would avoid inlining larger functions. .. ghc-flag:: -ffloat-in + :shortdesc: Turn on the float-in transformation. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-float-in + :category: :default: on @@ -279,6 +367,11 @@ by saying ``-fno-wombat``. allocation and helping the garbage collector and allocator. .. ghc-flag:: -ffull-laziness + :shortdesc: Turn on full laziness (floating bindings outwards). + Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-full-laziness + :category: :default: on @@ -300,6 +393,11 @@ by saying ``-fno-wombat``. don't rely on it. .. ghc-flag:: -ffun-to-thunk + :shortdesc: Allow worker-wrapper to convert a function closure into a thunk + if the function does not use any of its arguments. Off by default. + :type: dynamic + :reverse: -fno-fun-to-thunk + :category: :default: off @@ -309,6 +407,10 @@ by saying ``-fno-wombat``. This flag allows worker/wrapper to remove *all* value lambdas. .. ghc-flag:: -fignore-asserts + :shortdesc: Ignore assertions in the source. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-ignore-asserts + :category: :default: on @@ -317,6 +419,10 @@ by saying ``-fno-wombat``. :ref:`assertions`). .. ghc-flag:: -fignore-interface-pragmas + :shortdesc: Ignore pragmas in interface files. Implied by :ghc-flag:`-O0` only. + :type: dynamic + :reverse: -fno-ignore-interface-pragmas + :category: :default: off @@ -326,6 +432,11 @@ by saying ``-fno-wombat``. information. .. ghc-flag:: -flate-dmd-anal + :shortdesc: Run demand analysis again, at the end of the + simplification pipeline + :type: dynamic + :reverse: -fno-late-dmd-anal + :category: :default: off @@ -337,6 +448,10 @@ by saying ``-fno-wombat``. so is the cost. See notes on the :ghc-wiki:`Trac wiki page <LateDmd>`. .. ghc-flag:: -fliberate-case + :shortdesc: Turn on the liberate-case transformation. Implied by :ghc-flag:`-O2`. + :type: dynamic + :reverse: -fno-liberate-case + :category: :default: off but enabled with :ghc-flag:`-O2`. @@ -346,12 +461,22 @@ by saying ``-fno-wombat``. free variables rather than arguments. .. ghc-flag:: -fliberate-case-threshold=⟨n⟩ + :shortdesc: *default: 2000.* Set the size threshold for the liberate-case + transformation to ⟨n⟩ + :type: dynamic + :reverse: -fno-liberate-case-threshold + :category: :default: 2000 Set the size threshold for the liberate-case transformation. .. ghc-flag:: -floopification + :shortdesc: Turn saturated self-recursive tail-calls into local jumps in the + generated assembly. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-loopification + :category: :default: on @@ -360,6 +485,10 @@ by saying ``-fno-wombat``. function calls. .. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩ + :shortdesc: *default: 128.* Set the maximum size of inline array allocations + to ⟨n⟩ bytes (default: 128). + :type: dynamic + :category: :default: 128 @@ -369,12 +498,20 @@ by saying ``-fno-wombat``. value should be quite a bit smaller than the block size (typically: 4096). .. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩ + :shortdesc: *default: 32.* Inline ``memcpy`` calls if they would generate no + more than ⟨n⟩ pseudo instructions. + :type: dynamic + :category: :default: 32 Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions. .. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩ + :shortdesc: *default: 32.* Inline ``memset`` calls if they would generate no + more than ⟨n⟩ pseudo instructions + :type: dynamic + :category: :default: 32 @@ -382,7 +519,11 @@ by saying ``-fno-wombat``. instructions. .. ghc-flag:: -fmax-relevant-binds=⟨n⟩ - -fno-max-relevant-bindings + :shortdesc: *default: 6.* Set the maximum number of bindings to display in + type error messages. + :type: dynamic + :reverse: -fno-max-relevant-bindings + :category: :default: 6 @@ -395,7 +536,11 @@ by saying ``-fno-wombat``. them too. .. ghc-flag:: -fmax-valid-substitutions=⟨n⟩ - -fno-max-valid-substitutions + :shortdesc: *default: 6.* Set the maximum number of valid substitutions for + typed holes to display in type error messages. + :type: dynamic + :reverse: -fno-max-valid-substitutions + :category: :default: 6 @@ -405,6 +550,10 @@ by saying ``-fno-wombat``. ``-fno-max-valid-substitutions`` gives an unlimited number. .. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩ + :shortdesc: *default: 4.* Set the maximum number of patterns to display in + warnings about non-exhaustive ones. + :type: dynamic + :category: :default: 4 @@ -412,30 +561,48 @@ by saying ``-fno-wombat``. :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`. .. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩ + :shortdesc: *default: 4.* Set the max iterations for the simplifier. + :type: dynamic + :category: :default: 4 Sets the maximal number of iterations for the simplifier. .. ghc-flag:: -fmax-worker-args=⟨n⟩ + :shortdesc: *default: 10.* If a worker has that many arguments, none will + be unpacked anymore. + :type: dynamic + :category: :default: 10 If a worker has that many arguments, none will be unpacked anymore. .. ghc-flag:: -fno-opt-coercion + :shortdesc: Turn off the coercion optimiser + :type: dynamic + :category: :default: off Turn off the coercion optimiser. .. ghc-flag:: -fno-pre-inlining + :shortdesc: Turn off pre-inlining + :type: dynamic + :category: :default: off Turn off pre-inlining. .. ghc-flag:: -fno-state-hack + :shortdesc: Turn off the \state hack\ whereby any lambda with a real-world + state token as argument is considered to be single-entry. Hence + OK to inline things inside it. + :type: dynamic + :category: :default: off @@ -445,6 +612,10 @@ by saying ``-fno-wombat``. and ST monad code, but it runs the risk of reducing sharing. .. ghc-flag:: -fomit-interface-pragmas + :shortdesc: Don't generate interface pragmas. Implied by :ghc-flag:`-O0` only. + :type: dynamic + :reverse: -fno-omit-interface-pragmas + :category: :default: off @@ -458,6 +629,10 @@ by saying ``-fno-wombat``. type, not when they change their implementation). .. ghc-flag:: -fomit-yields + :shortdesc: Omit heap checks when no allocation is being performed. + :type: dynamic + :reverse: -fno-omit-yields + :category: :default: on @@ -470,6 +645,12 @@ by saying ``-fno-wombat``. turned off, if you need to guarantee interruptibility. .. ghc-flag:: -fpedantic-bottoms + :shortdesc: Make GHC be more precise about its treatment of bottom (but see + also :ghc-flag:`-fno-state-hack`). In particular, GHC will not + eta-expand through a case expression. + :type: dynamic + :reverse: -fno-pedantic-bottoms + :category: Make GHC be more precise about its treatment of bottom (but see also :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through @@ -477,6 +658,11 @@ by saying ``-fno-wombat``. using ``seq`` on partial applications. .. ghc-flag:: -fregs-graph + :shortdesc: Use the graph colouring register allocator for register + allocation in the native code generator. Implied by :ghc-flag:`-O2`. + :type: dynamic + :reverse: -fno-regs-graph + :category: :default: off due to a performance regression bug (:ghc-ticket:`7679`) @@ -490,6 +676,11 @@ by saying ``-fno-wombat``. when faced with code with high register pressure :ghc-ticket:`8657`. .. ghc-flag:: -fregs-iterative + :shortdesc: Use the iterative coalescing graph colouring register allocator + in the native code generator. + :type: dynamic + :reverse: -fno-regs-iterative + :category: :default: off @@ -500,12 +691,19 @@ by saying ``-fno-wombat``. during register allocation. .. ghc-flag:: -fsimplifier-phases=⟨n⟩ + :shortdesc: *default: 2.* Set the number of phases for the simplifier. + Ignored with :ghc-flag:`-O0`. + :type: dynamic + :category: :default: 2 Set the number of phases for the simplifier. Ignored with ``-O0``. .. ghc-flag:: -fsimpl-tick-factor=⟨n⟩ + :shortdesc: *default: 100.* Set the percentage factor for simplifier ticks. + :type: dynamic + :category: :default: 100 @@ -526,6 +724,10 @@ by saying ``-fno-wombat``. accurately, because some numbers are very large. .. ghc-flag:: -fspec-constr + :shortdesc: Turn on the SpecConstr transformation. Implied by :ghc-flag:`-O2`. + :type: dynamic + :reverse: -fno-spec-constr + :category: :default: off but enabled by :ghc-flag:`-O2`. @@ -590,6 +792,11 @@ by saying ``-fno-wombat``. cases. .. ghc-flag:: -fspec-constr-keen + :shortdesc: Specialize a call with an explicit constructor argument, + even if the argument is not scrutinised in the body of the function + :type: dynamic + :reverse: -fno-spec-constr-keen + :category: :default: off @@ -600,6 +807,12 @@ by saying ``-fno-wombat``. that can itself be specialised. .. ghc-flag:: -fspec-constr-count=⟨n⟩ + :shortdesc: default: 3.* Set to ⟨n⟩ the maximum number of specialisations that + will be created for any one function by the SpecConstr + transformation. + :type: dynamic + :reverse: -fno-spec-constr-count + :category: :default: 3 @@ -607,12 +820,21 @@ by saying ``-fno-wombat``. any one function by the SpecConstr transformation. .. ghc-flag:: -fspec-constr-threshold=⟨n⟩ + :shortdesc: *default: 2000.* Set the size threshold for the SpecConstr + transformation to ⟨n⟩. + :type: dynamic + :reverse: -fno-spec-constr-threshold + :category: :default: 2000 Set the size threshold for the SpecConstr transformation. .. ghc-flag:: -fspecialise + :shortdesc: Turn on specialisation of overloaded functions. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-specialise + :category: :default: on @@ -623,6 +845,11 @@ by saying ``-fno-wombat``. specialised as well. .. ghc-flag:: -fspecialise-aggressively + :shortdesc: Turn on specialisation of overloaded functions regardless of + size, if unfolding is available + :type: dynamic + :reverse: -fno-specialise-aggressively + :category: :default: off @@ -635,6 +862,11 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fcross-module-specialise + :shortdesc: Turn on specialisation of overloaded functions imported from + other modules. + :type: dynamic + :reverse: -fno-cross-module-specialise + :category: :default: on @@ -644,6 +876,11 @@ by saying ``-fno-wombat``. enabled (by ``-fspecialise``) for this to have any effect. .. ghc-flag:: -fsolve-constant-dicts + :shortdesc: When solving constraints, try to eagerly solve + super classes using available dictionaries. + :type: dynamic + :reverse: -fno-solve-constant-dicts + :category: :default: on @@ -675,6 +912,10 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fstatic-argument-transformation + :shortdesc: Turn on the static argument transformation. + :type: dynamic + :reverse: -fno-static-argument-transformation + :category: :default: off @@ -684,6 +925,11 @@ by saying ``-fno-wombat``. thesis <http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz>`__ .. ghc-flag:: -fstrictness + :shortdesc: Turn on strictness analysis. + Implied by :ghc-flag:`-O`. Implies :ghc-flag:`-fworker-wrapper` + :type: dynamic + :reverse: -fno-strictness + :category: :default: on @@ -698,10 +944,18 @@ by saying ``-fno-wombat``. arguments. .. ghc-flag:: -fstrictness-before=⟨n⟩ + :shortdesc: Run an additional strictness analysis before simplifier phase ⟨n⟩ + :type: dynamic + :category: Run an additional strictness analysis before simplifier phase ⟨n⟩. .. ghc-flag:: -funbox-small-strict-fields + :shortdesc: Flatten strict constructor fields with a pointer-sized + representation. Implied by :ghc-flag:`-O`. + :type: dynamic + :reverse: -fno-unbox-small-strict-fields + :category: :default: on @@ -737,6 +991,10 @@ by saying ``-fno-wombat``. they are technically larger than a pointer on those platforms. .. ghc-flag:: -funbox-strict-fields + :shortdesc: Flatten strict constructor fields + :type: dynamic + :reverse: -fno-unbox-strict-fields + :category: :default: off @@ -760,6 +1018,9 @@ by saying ``-fno-wombat``. unbox strict fields which are "small". .. ghc-flag:: -funfolding-creation-threshold=⟨n⟩ + :shortdesc: *default: 750.* Tweak unfolding settings. + :type: dynamic + :category: :default: 750 @@ -783,6 +1044,9 @@ by saying ``-fno-wombat``. useful. .. ghc-flag:: -funfolding-dict-discount=⟨n⟩ + :shortdesc: *default: 30.* Tweak unfolding settings. + :type: dynamic + :category: :default: 30 @@ -793,6 +1057,9 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline dictionaries? .. ghc-flag:: -funfolding-fun-discount=⟨n⟩ + :shortdesc: *default: 60.* Tweak unfolding settings. + :type: dynamic + :category: :default: 60 @@ -803,6 +1070,9 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? .. ghc-flag:: -funfolding-keeness-factor=⟨n⟩ + :shortdesc: *default: 1.5.* Tweak unfolding settings. + :type: dynamic + :category: :default: 1.5 @@ -813,6 +1083,9 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? .. ghc-flag:: -funfolding-use-threshold=⟨n⟩ + :shortdesc: *default: 60.* Tweak unfolding settings. + :type: dynamic + :category: :default: 60 @@ -834,6 +1107,10 @@ by saying ``-fno-wombat``. potential inlining. .. ghc-flag:: -fvectorisation-avoidance + :shortdesc: Enable vectorisation avoidance. Always enabled by default. + :type: dynamic + :reverse: -fno-vectorisation-avoidance + :category: :default: on @@ -852,6 +1129,10 @@ by saying ``-fno-wombat``. function would be better of unvectorised and if so, do just that. .. ghc-flag:: -fvectorise + :shortdesc: Enable vectorisation of nested data parallelism + :type: dynamic + :reverse: -fno-vectorise + :category: :default: off |