user-guide: Clarify default optimization flags
authorBen Gamari <bgamari.foss@gmail.com>
Wed, 25 Oct 2017 19:53:40 +0000 (15:53 -0400)
committerBen Gamari <ben@smart-cactus.org>
Wed, 25 Oct 2017 20:44:23 +0000 (16:44 -0400)
Begins to fix #14214.

[skip ci]

Test Plan: Read it.

Reviewers: austin

Subscribers: rwbarton, thomie

GHC Trac Issues: #14214

Differential Revision: https://phabricator.haskell.org/D4098

docs/users_guide/using-optimisation.rst

index 763c778..ccf9ac5 100644 (file)
@@ -52,7 +52,6 @@ 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
@@ -584,7 +583,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: coercion optimisation enabled.
 
     Turn off the coercion optimiser.
 
@@ -593,7 +592,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: pre-inlining enabled
 
     Turn off pre-inlining.
 
@@ -604,7 +603,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: state hack is enabled
 
     Turn off the "state hack" whereby any lambda with a ``State#`` token
     as argument is considered to be single-entry, hence it is considered
@@ -617,7 +616,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-omit-interface-pragmas
     :category:
 
-    :default: off
+    :default: Implied by :ghc-flag:`-O0`, otherwise off.
 
     Tells GHC to omit all inessential information from the interface
     file generated for the module being compiled (say M). This means
@@ -634,7 +633,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-omit-yields
     :category:
 
-    :default: on
+    :default: yield points enabled
 
     Tells GHC to omit heap checks when no allocation is
     being performed. While this improves binary sizes by about 5%, it
@@ -652,6 +651,8 @@ by saying ``-fno-wombat``.
     :reverse: -fno-pedantic-bottoms
     :category:
 
+    :default: off
+
     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
     a case expression, which is good for performance, but bad if you are