[commit: ghc] master: users-guide: Document defaults for remaining optimization flags (41c7437)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/41c7437e13494c548de83f10154ff35940748aaf/ghc

>---------------------------------------------------------------

commit 41c7437e13494c548de83f10154ff35940748aaf
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Wed Feb 8 15:49:46 2017 -0500

    users-guide: Document defaults for remaining optimization flags


>---------------------------------------------------------------

41c7437e13494c548de83f10154ff35940748aaf
 docs/users_guide/using-optimisation.rst | 52 ++++++++++++++++++++++++++-------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index 123d74b..9436832 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -196,16 +196,20 @@ list.
 
 .. ghc-flag:: -fdicts-cheap
 
+    :default: off
+
     A very experimental flag that makes dictionary-valued expressions
     seem cheap to the optimiser.
 
 .. ghc-flag:: -fdicts-strict
 
+    :default: off
+
     Make dictionaries strict.
 
 .. ghc-flag:: -fdmd-tx-dict-sel
 
-    *On by default for ``-O0``, ``-O``, ``-O2``.*
+    :default: on
 
     Use a special demand transformer for dictionary selectors.
 
@@ -224,6 +228,8 @@ list.
 
 .. ghc-flag:: -feager-blackholing
 
+    :default: off
+
     Usually GHC black-holes a thunk only when it switches threads. This
     flag makes it do so as soon as the thunk is entered. See `Haskell on
     a shared-memory
@@ -231,6 +237,8 @@ list.
 
 .. ghc-flag:: -fexcess-precision
 
+    :default: off
+
     When this option is given, intermediate floating point values can
     have a *greater* precision/range than the final type. Generally this
     is a good thing, but some programs may rely on the exact
@@ -244,6 +252,8 @@ list.
 
 .. ghc-flag:: -fexpose-all-unfoldings
 
+    :default: off
+
     An experimental flag to expose all unfoldings, even for very large
     or recursive functions. This allows for all functions to be inlined
     while usually GHC would avoid inlining larger functions.
@@ -309,6 +319,8 @@ list.
 
 .. ghc-flag:: -fignore-interface-pragmas
 
+    :default: off
+
     Tells GHC to ignore all inessential information when reading
     interface files. That is, even if :file:`M.hi` contains unfolding or
     strictness information for a function, GHC will ignore that
@@ -316,6 +328,8 @@ list.
 
 .. ghc-flag:: -flate-dmd-anal
 
+    :default: off
+
     Run demand analysis again, at the end of the simplification
     pipeline. We found some opportunities for discovering strictness
     that were not visible earlier; and optimisations like
@@ -325,11 +339,12 @@ list.
 
 .. ghc-flag:: -fliberate-case
 
-    *Off by default, but enabled by -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 a bit like
-    the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for free
-    variables rather than arguments.
+    :default: off but enabled with :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
+    a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for
+    free variables rather than arguments.
 
 .. ghc-flag:: -fliberate-case-threshold=<n>
 
@@ -401,14 +416,20 @@ list.
 
 .. ghc-flag:: -fno-opt-coercion
 
+    :default: off
+
     Turn off the coercion optimiser.
 
 .. ghc-flag:: -fno-pre-inlining
 
+    :default: off
+
     Turn off pre-inlining.
 
 .. ghc-flag:: -fno-state-hack
 
+    :default: off
+
     Turn off the "state hack" whereby any lambda with a ``State#`` token
     as argument is considered to be single-entry, hence it is considered
     okay to inline things inside it. This can improve performance of IO
@@ -416,6 +437,8 @@ list.
 
 .. ghc-flag:: -fomit-interface-pragmas
 
+    :default: off
+
     Tells GHC to omit all inessential information from the interface
     file generated for the module being compiled (say M). This means
     that a module importing M will see only the *types* of the functions
@@ -495,9 +518,11 @@ list.
 
 .. ghc-flag:: -fspec-constr
 
-    *Off by default, but enabled by -O2.* Turn on call-pattern
-    specialisation; see `Call-pattern specialisation for Haskell
-    programs <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__.
+    :default: off but enabled by :ghc-flag:`-O2`.
+
+    Turn on call-pattern specialisation; see `Call-pattern specialisation for
+    Haskell programs
+    <http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm>`__.
 
     This optimisation specializes recursive functions according to their
     argument "shapes". This is best explained by example so consider: ::
@@ -601,7 +626,7 @@ list.
 
 .. ghc-flag:: -fsolve-constant-dicts
 
-    :default on
+    :default: on
 
     When solving constraints, try to eagerly solve
     super classes using availible dictionaries.
@@ -632,6 +657,8 @@ list.
 
 .. ghc-flag:: -fstatic-argument-transformation
 
+    :default: off
+
     Turn on the static argument transformation, which turns a recursive
     function into a non-recursive one with a local recursive loop. See
     Chapter 7 of `Andre Santos's PhD
@@ -695,6 +722,8 @@ list.
 
 .. ghc-flag:: -funbox-strict-fields
 
+    :default: off
+
     .. index::
        single: strict constructor fields
        single: constructor fields, strict
@@ -711,6 +740,9 @@ list.
     it for certain constructor fields using the ``NOUNPACK`` pragma (see
     :ref:`nounpack-pragma`).
 
+    Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only
+    unbox strict fields which are "small".
+
 .. ghc-flag:: -funfolding-creation-threshold=<n>
 
     :default: 750