From a856d98eb13401b78fa7eba9a54ea4c501ebb0a2 Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Tue, 9 May 2023 19:47:19 +0200 Subject: Doc: Fix out-of-sync using-optimisation page - Make explicit that default flag values correspond to their -O0 value. - Fix -fignore-interface-pragmas, -fstg-cse, -fdo-eta-reduction, -fcross-module-specialise, -fsolve-constant-dicts, -fworker-wrapper. --- docs/users_guide/using-optimisation.rst | 77 +++++++++++++++++---------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index df87fdb6a3..c75d5e6097 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -117,9 +117,9 @@ The easiest way to see what ``-O`` (etc.) “really mean” is to run with single: -fno-\* options (GHC) These flags turn on and off individual optimisations. Flags marked as -on by default are enabled by ``-O``, and as such you shouldn't -need to set any of them explicitly. A flag ``-fwombat`` can be negated -by saying ``-fno-wombat``. +*on* by default are enabled at all optimisation levels by default, and +as such you shouldn't need to set any of them explicitly. A flag +``-fwombat`` can be negated by saying ``-fno-wombat``. .. ghc-flag:: -fcore-constant-folding :shortdesc: Enable constant folding in Core. Implied by :ghc-flag:`-O`. @@ -127,7 +127,7 @@ by saying ``-fno-wombat``. :reverse: -fno-core-constant-folding :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables Core-level constant folding, i.e. propagation of values that can be computed at compile time. @@ -138,7 +138,7 @@ by saying ``-fno-wombat``. :reverse: -fno-case-merge :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Merge immediately-nested case expressions that scrutinise the same variable. For example, :: @@ -162,7 +162,7 @@ by saying ``-fno-wombat``. :reverse: -fno-case-folding :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Allow constant folding in case expressions that scrutinise some primops: For example, :: @@ -185,7 +185,7 @@ by saying ``-fno-wombat``. :reverse: -fno-call-arity :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enable call-arity analysis. @@ -195,7 +195,7 @@ by saying ``-fno-wombat``. :reverse: -fno-exitification :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables the floating of exit paths out of recursive functions. @@ -205,7 +205,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cmm-elim-common-blocks :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables the common block elimination optimisation in the code generator. This optimisation attempts to find identical @@ -217,7 +217,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cmm-sink :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables the sinking pass in the code generator. This optimisation attempts to find identical Cmm blocks and @@ -231,7 +231,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cmm-static-pred :category: - :default: off but enabled with :ghc-flag:`-O`. + :default: off but enabled by :ghc-flag:`-O`. This enables static control flow prediction on the final Cmm code. If enabled GHC will apply certain heuristics to identify @@ -244,7 +244,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cmm-control-flow :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables some control flow optimisations in the Cmm code generator, merging basic blocks and avoiding jumps right after jumps. @@ -255,7 +255,7 @@ by saying ``-fno-wombat``. :reverse: -fno-asm-shortcutting :category: - :default: off + :default: off but enabled by :ghc-flag:`-O2`. This enables shortcutting at the assembly stage of the code generator. In simpler terms shortcutting means if a block of instructions A only consists @@ -268,12 +268,12 @@ by saying ``-fno-wombat``. does nothing on macOS. .. ghc-flag:: -fblock-layout-cfg - :shortdesc: Use the new cfg based block layout algorithm. + :shortdesc: Use the new cfg based block layout algorithm. Implied by :ghc-flag:`-O`. :type: dynamic :reverse: -fno-block-layout-cfg :category: - :default: off but enabled with :ghc-flag:`-O`. + :default: off but enabled by :ghc-flag:`-O`. The new algorithm considers all outgoing edges of a basic blocks for code layout instead of only the last jump instruction. @@ -326,7 +326,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cpr-anal :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Turn on CPR analysis, which enables the worker/wrapper transformation (cf. :ghc-flag:`-fworker-wrapper`) to unbox the result of a function, such as :: @@ -386,7 +386,7 @@ by saying ``-fno-wombat``. :reverse: -fno-cse :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables the common-sub-expression elimination optimisation. Switching this off can be useful if you have some @@ -394,12 +394,12 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fstg-cse :shortdesc: Enable common sub-expression elimination on the STG - intermediate language + intermediate language. Implied by :ghc-flag:`-O`. :type: dynamic :reverse: -fno-stg-cse :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Enables the common-sub-expression elimination optimisation on the STG intermediate language, where it is able to common up some subexpressions @@ -422,7 +422,7 @@ by saying ``-fno-wombat``. :reverse: -fno-dicts-strict :category: - :default: off + :default: off but enabled by :ghc-flag:`-O2`. Make dictionaries strict. @@ -447,7 +447,7 @@ by saying ``-fno-wombat``. Behaviour is unconditionally enabled starting with 9.2 .. ghc-flag:: -fdo-eta-reduction - :shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`. + :shortdesc: Enable eta-reduction. Always enabled by default. :type: dynamic :reverse: -fno-do-eta-reduction :category: @@ -518,7 +518,7 @@ by saying ``-fno-wombat``. :reverse: -fno-float-in :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Float let-bindings inwards, nearer their binding site. See `Let-floating: moving bindings to give faster programs @@ -544,7 +544,7 @@ by saying ``-fno-wombat``. :reverse: -fno-full-laziness :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Run the full laziness optimisation (also known as let-floating), which floats let-bindings outside enclosing lambdas, @@ -591,7 +591,7 @@ by saying ``-fno-wombat``. :reverse: -fno-ignore-asserts :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Causes GHC to ignore uses of the function ``Exception.assert`` in source code (in other words, rewriting ``Exception.assert p e`` to ``e`` (see @@ -603,7 +603,7 @@ by saying ``-fno-wombat``. :reverse: -fno-ignore-interface-pragmas :category: - :default: off + :default: Implied by :ghc-flag:`-O0`, otherwise off. Tells GHC to ignore all inessential information when reading interface files. That is, even if :file:`M.hi` contains unfolding or @@ -632,7 +632,7 @@ by saying ``-fno-wombat``. :reverse: -fno-liberate-case :category: - :default: off but enabled with :ghc-flag:`-O2`. + :default: off but enabled by :ghc-flag:`-O2`. Turn on the liberate-case transformation. This unrolls recursive function once in its own RHS, to avoid repeated case analysis of free variables. It's @@ -657,7 +657,7 @@ by saying ``-fno-wombat``. :reverse: -fno-loopification :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. When this optimisation is enabled the code generator will turn all self-recursive saturated tail calls into local jumps rather than @@ -1074,7 +1074,7 @@ by saying ``-fno-wombat``. :reverse: -fno-specialise :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Specialise each type-class-overloaded function defined in this module for the types at which it is called in this @@ -1101,12 +1101,12 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fcross-module-specialise :shortdesc: Turn on specialisation of overloaded functions imported from - other modules. + other modules. Implied by :ghc-flag:`-O`. :type: dynamic :reverse: -fno-cross-module-specialise :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Specialise ``INLINABLE`` (:ref:`inlinable-pragma`) type-class-overloaded functions imported from other modules for the types at @@ -1136,7 +1136,7 @@ by saying ``-fno-wombat``. :reverse: -fno-inline-generics :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. :since: 9.2.1 .. index:: @@ -1175,12 +1175,12 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fsolve-constant-dicts :shortdesc: When solving constraints, try to eagerly solve - super classes using available dictionaries. + super classes using available dictionaries. Implied by :ghc-flag:`-O`. :type: dynamic :reverse: -fno-solve-constant-dicts :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. When solving constraints, try to eagerly solve super classes using available dictionaries. @@ -1229,7 +1229,7 @@ by saying ``-fno-wombat``. :reverse: -fno-stg-lift-lams :category: - :default: on + :default: off but enabled by :ghc-flag:`-O2`. Enables the late lambda lifting optimisation on the STG intermediate language. This selectively lifts local functions to @@ -1281,7 +1281,7 @@ by saying ``-fno-wombat``. :reverse: -fno-strictness :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. Turn on demand analysis. @@ -1441,7 +1441,7 @@ by saying ``-fno-wombat``. :reverse: -fno-unbox-small-strict-fields :category: - :default: on + :default: off but enabled by :ghc-flag:`-O`. .. index:: single: strict constructor fields @@ -1654,10 +1654,13 @@ by saying ``-fno-wombat``. .. ghc-flag:: -fworker-wrapper - :shortdesc: Enable the worker/wrapper transformation. + :shortdesc: Enable the worker/wrapper transformation. Implied by :ghc-flag:`-O` + and by :ghc-flag:`-fstrictness`. :type: dynamic :category: + :default: off but enabled by :ghc-flag:`-O`. + Enable the worker/wrapper transformation after a demand analysis pass. Exploits strictness and absence information by unboxing strict arguments -- cgit v1.2.1