Update User's Guide, cleanup DynFlags
authorJan Stolarek <jan.stolarek@p.lodz.pl>
Wed, 5 Nov 2014 12:44:32 +0000 (13:44 +0100)
committerJan Stolarek <jan.stolarek@p.lodz.pl>
Thu, 6 Nov 2014 11:50:17 +0000 (12:50 +0100)
compiler/cmm/CmmCallConv.hs
compiler/main/DynFlags.hs
compiler/main/StaticFlags.hs
docs/users_guide/7.10.1-notes.xml
docs/users_guide/flags.xml
docs/users_guide/using.xml
testsuite/tests/ghci/scripts/ghci057.stdout

index f36fc0b..440ee56 100644 (file)
@@ -106,7 +106,7 @@ passFloatArgsInXmm dflags = case platformArch (targetPlatform dflags) of
 
 -- On X86_64, we always pass 128-bit-wide vectors in registers. On 32-bit X86
 -- and for all larger vector sizes on X86_64, LLVM's GHC calling convention
--- doesn't currently passing vectors in registers. The patch to update the GHC
+-- does not currently pass vectors in registers. The patch to update the GHC
 -- calling convention to support passing SIMD vectors in registers is small and
 -- well-contained, so it may make it into LLVM 3.4. The hidden
 -- -fllvm-pass-vectors-in-regs flag will generate LLVM code that attempts to
index d5362f3..eb5bb77 100644 (file)
@@ -197,10 +197,24 @@ import qualified Data.IntSet as IntSet
 
 import GHC.Foreign (withCString, peekCString)
 
+-- Note [Updating flag description in the User's Guide]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--
+-- If you modify anything in this file please make sure that your changes are
+-- described in the User's Guide. Usually at least two sections need to be
+-- updated:
+--
+--  * Flag Reference section in docs/users-guide/flags.xml lists all available
+--    flags together with a short description
+--
+--  * Flag description in docs/users_guide/using.xml provides a detailed
+--    explanation of flags' usage.
+
 -- -----------------------------------------------------------------------------
 -- DynFlags
 
 data DumpFlag
+-- See Note [Updating flag description in the User's Guide]
 
    -- debugging flags
    = Opt_D_dump_cmm
@@ -276,6 +290,7 @@ data DumpFlag
 
 -- | Enumerates the simple on-or-off dynamic flags
 data GeneralFlag
+-- See Note [Updating flag description in the User's Guide]
 
    = Opt_DumpToFile                     -- ^ Append dump output to files instead of stdout.
    | Opt_D_faststring_stats
@@ -428,6 +443,7 @@ data GeneralFlag
    deriving (Eq, Show, Enum)
 
 data WarningFlag =
+-- See Note [Updating flag description in the User's Guide]
      Opt_WarnDuplicateExports
    | Opt_WarnDuplicateConstraints
    | Opt_WarnHiShadows
@@ -494,6 +510,7 @@ instance Outputable SafeHaskellMode where
     ppr = text . show
 
 data ExtensionFlag
+-- See Note [Updating flag description in the User's Guide]
    = Opt_Cpp
    | Opt_OverlappingInstances
    | Opt_UndecidableInstances
@@ -1335,10 +1352,11 @@ initDynFlags dflags = do
         rtccInfo      = refRtccInfo
         }
 
--- | The normal 'DynFlags'. Note that they is not suitable for use in this form
+-- | The normal 'DynFlags'. Note that they are not suitable for use in this form
 -- and must be fully initialized by 'GHC.runGhc' first.
 defaultDynFlags :: Settings -> DynFlags
 defaultDynFlags mySettings =
+-- See Note [Updating flag description in the User's Guide]
      DynFlags {
         ghcMode                 = CompManager,
         ghcLink                 = LinkBinary,
@@ -2143,6 +2161,7 @@ flagsPackage :: [Flag (CmdLineP DynFlags)]
 flagsPackage = package_flags
 
 --------------- The main flags themselves ------------------
+-- See Note [Updating flag description in the User's Guide]
 dynamic_flags :: [Flag (CmdLineP DynFlags)]
 dynamic_flags = [
     Flag "n"        (NoArg (addWarn "The -n flag is deprecated and no longer has any effect"))
@@ -2602,51 +2621,53 @@ nop _ = return ()
 -- | These @-f\<blah\>@ flags can all be reversed with @-fno-\<blah\>@
 fWarningFlags :: [FlagSpec WarningFlag]
 fWarningFlags = [
-  ( "warn-dodgy-foreign-imports",       Opt_WarnDodgyForeignImports, nop ),
+-- See Note [Updating flag description in the User's Guide]
+-- Please keep the list of flags below sorted alphabetically
+  ( "warn-alternative-layout-rule-transitional", Opt_WarnAlternativeLayoutRuleTransitional, nop ),
+  ( "warn-amp",                         Opt_WarnAMP,
+    \_ -> deprecate "it has no effect, and will be removed in GHC 7.12" ),
+  ( "warn-auto-orphans",                Opt_WarnAutoOrphans, nop ),
+  ( "warn-deprecations",                Opt_WarnWarningsDeprecations, nop ),
+  ( "warn-deprecated-flags",            Opt_WarnDeprecatedFlags, nop ),
   ( "warn-dodgy-exports",               Opt_WarnDodgyExports, nop ),
+  ( "warn-dodgy-foreign-imports",       Opt_WarnDodgyForeignImports, nop ),
   ( "warn-dodgy-imports",               Opt_WarnDodgyImports, nop ),
-  ( "warn-overflowed-literals",         Opt_WarnOverflowedLiterals, nop ),
   ( "warn-empty-enumerations",          Opt_WarnEmptyEnumerations, nop ),
-  ( "warn-duplicate-exports",           Opt_WarnDuplicateExports, nop ),
+  ( "warn-context-quantification",      Opt_WarnContextQuantification, nop ),
   ( "warn-duplicate-constraints",       Opt_WarnDuplicateConstraints, nop ),
+  ( "warn-duplicate-exports",           Opt_WarnDuplicateExports, nop ),
   ( "warn-hi-shadowing",                Opt_WarnHiShadows, nop ),
   ( "warn-implicit-prelude",            Opt_WarnImplicitPrelude, nop ),
   ( "warn-incomplete-patterns",         Opt_WarnIncompletePatterns, nop ),
-  ( "warn-incomplete-uni-patterns",     Opt_WarnIncompleteUniPatterns, nop ),
   ( "warn-incomplete-record-updates",   Opt_WarnIncompletePatternsRecUpd, nop ),
+  ( "warn-incomplete-uni-patterns",     Opt_WarnIncompleteUniPatterns, nop ),
+  ( "warn-inline-rule-shadowing",       Opt_WarnInlineRuleShadowing, nop ),
+  ( "warn-identities",                  Opt_WarnIdentities, nop ),
   ( "warn-missing-fields",              Opt_WarnMissingFields, nop ),
   ( "warn-missing-import-lists",        Opt_WarnMissingImportList, nop ),
+  ( "warn-missing-local-sigs",          Opt_WarnMissingLocalSigs, nop ),
   ( "warn-missing-methods",             Opt_WarnMissingMethods, nop ),
   ( "warn-missing-signatures",          Opt_WarnMissingSigs, nop ),
-  ( "warn-missing-local-sigs",          Opt_WarnMissingLocalSigs, nop ),
-  ( "warn-name-shadowing",              Opt_WarnNameShadowing, nop ),
-  ( "warn-overlapping-patterns",        Opt_WarnOverlappingPatterns, nop ),
-  ( "warn-type-defaults",               Opt_WarnTypeDefaults, nop ),
   ( "warn-monomorphism-restriction",    Opt_WarnMonomorphism, nop ),
-  ( "warn-unused-binds",                Opt_WarnUnusedBinds, nop ),
-  ( "warn-unused-imports",              Opt_WarnUnusedImports, nop ),
-  ( "warn-unused-matches",              Opt_WarnUnusedMatches, nop ),
-  ( "warn-context-quantification",      Opt_WarnContextQuantification, nop ),
-  ( "warn-warnings-deprecations",       Opt_WarnWarningsDeprecations, nop ),
-  ( "warn-deprecations",                Opt_WarnWarningsDeprecations, nop ),
-  ( "warn-deprecated-flags",            Opt_WarnDeprecatedFlags, nop ),
-  ( "warn-amp",                         Opt_WarnAMP,
-    \_ -> deprecate "it has no effect, and will be removed in GHC 7.12" ),
+  ( "warn-name-shadowing",              Opt_WarnNameShadowing, nop ),
   ( "warn-orphans",                     Opt_WarnOrphans, nop ),
-  ( "warn-identities",                  Opt_WarnIdentities, nop ),
-  ( "warn-auto-orphans",                Opt_WarnAutoOrphans, nop ),
+  ( "warn-overflowed-literals",         Opt_WarnOverflowedLiterals, nop ),
+  ( "warn-overlapping-patterns",        Opt_WarnOverlappingPatterns, nop ),
+  ( "warn-pointless-pragmas",           Opt_WarnPointlessPragmas, nop ),
+  ( "warn-safe",                        Opt_WarnSafe, setWarnSafe ),
   ( "warn-tabs",                        Opt_WarnTabs, nop ),
+  ( "warn-type-defaults",               Opt_WarnTypeDefaults, nop ),
   ( "warn-typed-holes",                 Opt_WarnTypedHoles, nop ),
   ( "warn-unrecognised-pragmas",        Opt_WarnUnrecognisedPragmas, nop ),
-  ( "warn-unused-do-bind",              Opt_WarnUnusedDoBind, nop ),
-  ( "warn-wrong-do-bind",               Opt_WarnWrongDoBind, nop ),
-  ( "warn-alternative-layout-rule-transitional", Opt_WarnAlternativeLayoutRuleTransitional, nop ),
   ( "warn-unsafe",                      Opt_WarnUnsafe, setWarnUnsafe ),
-  ( "warn-safe",                        Opt_WarnSafe, setWarnSafe ),
-  ( "warn-pointless-pragmas",           Opt_WarnPointlessPragmas, nop ),
   ( "warn-unsupported-calling-conventions", Opt_WarnUnsupportedCallingConventions, nop ),
-  ( "warn-inline-rule-shadowing",       Opt_WarnInlineRuleShadowing, nop ),
-  ( "warn-unsupported-llvm-version",    Opt_WarnUnsupportedLlvmVersion, nop ) ]
+  ( "warn-unsupported-llvm-version",    Opt_WarnUnsupportedLlvmVersion, nop ),
+  ( "warn-unused-binds",                Opt_WarnUnusedBinds, nop ),
+  ( "warn-unused-do-bind",              Opt_WarnUnusedDoBind, nop ),
+  ( "warn-unused-imports",              Opt_WarnUnusedImports, nop ),
+  ( "warn-unused-matches",              Opt_WarnUnusedMatches, nop ),
+  ( "warn-warnings-deprecations",       Opt_WarnWarningsDeprecations, nop ),
+  ( "warn-wrong-do-bind",               Opt_WarnWrongDoBind, nop ) ]
 
 -- | These @-\<blah\>@ flags can all be reversed with @-no-\<blah\>@
 negatableFlags :: [FlagSpec GeneralFlag]
@@ -2656,94 +2677,99 @@ negatableFlags = [
 -- | These @-d\<blah\>@ flags can all be reversed with @-dno-\<blah\>@
 dFlags :: [FlagSpec GeneralFlag]
 dFlags = [
+-- See Note [Updating flag description in the User's Guide]
+-- Please keep the list of flags below sorted alphabetically
+  ( "ppr-case-as-let",                  Opt_PprCaseAsLet,               nop),
   ( "suppress-coercions",               Opt_SuppressCoercions,          nop),
-  ( "suppress-var-kinds",               Opt_SuppressVarKinds,           nop),
+  ( "suppress-idinfo",                  Opt_SuppressIdInfo,             nop),
   ( "suppress-module-prefixes",         Opt_SuppressModulePrefixes,     nop),
   ( "suppress-type-applications",       Opt_SuppressTypeApplications,   nop),
-  ( "suppress-idinfo",                  Opt_SuppressIdInfo,             nop),
   ( "suppress-type-signatures",         Opt_SuppressTypeSignatures,     nop),
   ( "suppress-uniques",                 Opt_SuppressUniques,            nop),
-  ( "ppr-case-as-let",                  Opt_PprCaseAsLet,               nop)]
+  ( "suppress-var-kinds",               Opt_SuppressVarKinds,           nop)]
 
 -- | These @-f\<blah\>@ flags can all be reversed with @-fno-\<blah\>@
 fFlags :: [FlagSpec GeneralFlag]
 fFlags = [
-  ( "error-spans",                      Opt_ErrorSpans, nop ),
-  ( "print-explicit-foralls",           Opt_PrintExplicitForalls, nop ),
-  ( "print-explicit-kinds",             Opt_PrintExplicitKinds, nop ),
+-- See Note [Updating flag description in the User's Guide]
+-- Please keep the list of flags below sorted alphabetically
+  ( "break-on-error",                   Opt_BreakOnError, nop ),
+  ( "break-on-exception",               Opt_BreakOnException, nop ),
+  ( "building-cabal-package",           Opt_BuildingCabalPackage, nop ),
   ( "call-arity",                       Opt_CallArity, nop ),
-  ( "strictness",                       Opt_Strictness, nop ),
-  ( "late-dmd-anal",                    Opt_LateDmdAnal, nop ),
-  ( "specialise",                       Opt_Specialise, nop ),
-  ( "specialise-aggressively",          Opt_SpecialiseAggressively, nop ),
-  ( "float-in",                         Opt_FloatIn, nop ),
-  ( "static-argument-transformation",   Opt_StaticArgumentTransformation, nop ),
-  ( "full-laziness",                    Opt_FullLaziness, nop ),
-  ( "liberate-case",                    Opt_LiberateCase, nop ),
-  ( "spec-constr",                      Opt_SpecConstr, nop ),
-  ( "cse",                              Opt_CSE, nop ),
-  ( "pedantic-bottoms",                 Opt_PedanticBottoms, nop ),
-  ( "ignore-interface-pragmas",         Opt_IgnoreInterfacePragmas, nop ),
-  ( "omit-interface-pragmas",           Opt_OmitInterfacePragmas, nop ),
-  ( "write-interface",                  Opt_WriteInterface, nop ),
-  ( "expose-all-unfoldings",            Opt_ExposeAllUnfoldings, nop ),
-  ( "do-lambda-eta-expansion",          Opt_DoLambdaEtaExpansion, nop ),
-  ( "ignore-asserts",                   Opt_IgnoreAsserts, nop ),
-  ( "do-eta-reduction",                 Opt_DoEtaReduction, nop ),
   ( "case-merge",                       Opt_CaseMerge, nop ),
-  ( "unbox-strict-fields",              Opt_UnboxStrictFields, nop ),
-  ( "unbox-small-strict-fields",        Opt_UnboxSmallStrictFields, nop ),
+  ( "cmm-elim-common-blocks",           Opt_CmmElimCommonBlocks, nop ),
+  ( "cmm-sink",                         Opt_CmmSink, nop ),
+  ( "cse",                              Opt_CSE, nop ),
+  ( "defer-type-errors",                Opt_DeferTypeErrors, nop ),
   ( "dicts-cheap",                      Opt_DictsCheap, nop ),
-  ( "excess-precision",                 Opt_ExcessPrecision, nop ),
+  ( "dicts-strict",                     Opt_DictsStrict, nop ),
+  ( "dmd-tx-dict-sel",                  Opt_DmdTxDictSel, nop ),
+  ( "do-eta-reduction",                 Opt_DoEtaReduction, nop ),
+  ( "do-lambda-eta-expansion",          Opt_DoLambdaEtaExpansion, nop ),
   ( "eager-blackholing",                Opt_EagerBlackHoling, nop ),
-  ( "print-bind-result",                Opt_PrintBindResult, nop ),
-  ( "force-recomp",                     Opt_ForceRecomp, nop ),
-  ( "hpc-no-auto",                      Opt_Hpc_No_Auto, nop ),
-  ( "rewrite-rules",                    Opt_EnableRewriteRules, useInstead "enable-rewrite-rules" ),
-  ( "enable-rewrite-rules",             Opt_EnableRewriteRules, nop ),
-  ( "break-on-exception",               Opt_BreakOnException, nop ),
-  ( "break-on-error",                   Opt_BreakOnError, nop ),
-  ( "print-evld-with-show",             Opt_PrintEvldWithShow, nop ),
-  ( "print-bind-contents",              Opt_PrintBindContents, nop ),
-  ( "vectorise",                        Opt_Vectorise, nop ),
-  ( "vectorisation-avoidance",          Opt_VectorisationAvoidance, nop ),
-  ( "regs-graph",                       Opt_RegsGraph, nop ),
-  ( "regs-iterative",                   Opt_RegsIterative, nop ),
-  ( "llvm-tbaa",                        Opt_LlvmTBAA, nop), -- hidden flag
-  ( "llvm-pass-vectors-in-regs",        Opt_LlvmPassVectorsInRegisters, nop), -- hidden flag
-  ( "irrefutable-tuples",               Opt_IrrefutableTuples, nop ),
-  ( "cmm-sink",                         Opt_CmmSink, nop ),
-  ( "cmm-elim-common-blocks",           Opt_CmmElimCommonBlocks, nop ),
-  ( "omit-yields",                      Opt_OmitYields, nop ),
-  ( "simple-list-literals",             Opt_SimpleListLiterals, nop ),
-  ( "fun-to-thunk",                     Opt_FunToThunk, nop ),
-  ( "gen-manifest",                     Opt_GenManifest, nop ),
   ( "embed-manifest",                   Opt_EmbedManifest, nop ),
+  ( "enable-rewrite-rules",             Opt_EnableRewriteRules, nop ),
+  ( "error-spans",                      Opt_ErrorSpans, nop ),
+  ( "excess-precision",                 Opt_ExcessPrecision, nop ),
+  ( "expose-all-unfoldings",            Opt_ExposeAllUnfoldings, nop ),
   ( "ext-core",                         Opt_EmitExternalCore,
     \_ -> deprecate "it has no effect, and will be removed in GHC 7.12" ),
-  ( "shared-implib",                    Opt_SharedImplib, nop ),
-  ( "ghci-sandbox",                     Opt_GhciSandbox, nop ),
+  ( "flat-cache",                       Opt_FlatCache, nop ),
+  ( "float-in",                         Opt_FloatIn, nop ),
+  ( "force-recomp",                     Opt_ForceRecomp, nop ),
+  ( "full-laziness",                    Opt_FullLaziness, nop ),
+  ( "fun-to-thunk",                     Opt_FunToThunk, nop ),
+  ( "gen-manifest",                     Opt_GenManifest, nop ),
   ( "ghci-history",                     Opt_GhciHistory, nop ),
+  ( "ghci-sandbox",                     Opt_GhciSandbox, nop ),
   ( "helpful-errors",                   Opt_HelpfulErrors, nop ),
-  ( "defer-type-errors",                Opt_DeferTypeErrors, nop ),
-  ( "building-cabal-package",           Opt_BuildingCabalPackage, nop ),
-  ( "implicit-import-qualified",        Opt_ImplicitImportQualified, nop ),
-  ( "prof-count-entries",               Opt_ProfCountEntries, nop ),
-  ( "prof-cafs",                        Opt_AutoSccsOnIndividualCafs, nop ),
   ( "hpc",                              Opt_Hpc, nop ),
-  ( "pre-inlining",                     Opt_SimplPreInlining, nop ),
-  ( "flat-cache",                       Opt_FlatCache, nop ),
-  ( "use-rpaths",                       Opt_RPath, nop ),
+  ( "hpc-no-auto",                      Opt_Hpc_No_Auto, nop ),
+  ( "ignore-asserts",                   Opt_IgnoreAsserts, nop ),
+  ( "ignore-interface-pragmas",         Opt_IgnoreInterfacePragmas, nop ),
+  ( "implicit-import-qualified",        Opt_ImplicitImportQualified, nop ),
+  ( "irrefutable-tuples",               Opt_IrrefutableTuples, nop ),
   ( "kill-absence",                     Opt_KillAbsence, nop),
   ( "kill-one-shot",                    Opt_KillOneShot, nop),
-  ( "dicts-strict",                     Opt_DictsStrict, nop ),
-  ( "dmd-tx-dict-sel",                  Opt_DmdTxDictSel, nop ),
-  ( "loopification",                    Opt_Loopification, nop )
+  ( "late-dmd-anal",                    Opt_LateDmdAnal, nop ),
+  ( "liberate-case",                    Opt_LiberateCase, nop ),
+  ( "llvm-pass-vectors-in-regs",        Opt_LlvmPassVectorsInRegisters, nop),
+  ( "llvm-tbaa",                        Opt_LlvmTBAA, nop),
+  ( "loopification",                    Opt_Loopification, nop ),
+  ( "omit-interface-pragmas",           Opt_OmitInterfacePragmas, nop ),
+  ( "omit-yields",                      Opt_OmitYields, nop ),
+  ( "pedantic-bottoms",                 Opt_PedanticBottoms, nop ),
+  ( "pre-inlining",                     Opt_SimplPreInlining, nop ),
+  ( "print-bind-contents",              Opt_PrintBindContents, nop ),
+  ( "print-bind-result",                Opt_PrintBindResult, nop ),
+  ( "print-evld-with-show",             Opt_PrintEvldWithShow, nop ),
+  ( "print-explicit-foralls",           Opt_PrintExplicitForalls, nop ),
+  ( "print-explicit-kinds",             Opt_PrintExplicitKinds, nop ),
+  ( "prof-cafs",                        Opt_AutoSccsOnIndividualCafs, nop ),
+  ( "prof-count-entries",               Opt_ProfCountEntries, nop ),
+  ( "regs-graph",                       Opt_RegsGraph, nop ),
+  ( "regs-iterative",                   Opt_RegsIterative, nop ),
+  ( "rewrite-rules",                    Opt_EnableRewriteRules, useInstead "enable-rewrite-rules" ),
+  ( "shared-implib",                    Opt_SharedImplib, nop ),
+  ( "simple-list-literals",             Opt_SimpleListLiterals, nop ),
+  ( "spec-constr",                      Opt_SpecConstr, nop ),
+  ( "specialise",                       Opt_Specialise, nop ),
+  ( "specialise-aggressively",          Opt_SpecialiseAggressively, nop ),
+  ( "static-argument-transformation",   Opt_StaticArgumentTransformation, nop ),
+  ( "strictness",                       Opt_Strictness, nop ),
+  ( "use-rpaths",                       Opt_RPath, nop ),
+  ( "write-interface",                  Opt_WriteInterface, nop ),
+  ( "unbox-small-strict-fields",        Opt_UnboxSmallStrictFields, nop ),
+  ( "unbox-strict-fields",              Opt_UnboxStrictFields, nop ),
+  ( "vectorisation-avoidance",          Opt_VectorisationAvoidance, nop ),
+  ( "vectorise",                        Opt_Vectorise, nop )
   ]
 
 -- | These @-f\<blah\>@ flags can all be reversed with @-fno-\<blah\>@
 fLangFlags :: [FlagSpec ExtensionFlag]
 fLangFlags = [
+-- See Note [Updating flag description in the User's Guide]
   ( "th",                               Opt_TemplateHaskell,
     \on -> deprecatedForExtension "TemplateHaskell" on
         >> checkTemplateHaskellOk on ),
@@ -2809,135 +2835,136 @@ safeHaskellFlags = [mkF Sf_Unsafe, mkF Sf_Trustworthy, mkF Sf_Safe]
 -- | These -X<blah> flags can all be reversed with -XNo<blah>
 xFlags :: [FlagSpec ExtensionFlag]
 xFlags = [
+-- See Note [Updating flag description in the User's Guide]
+-- Please keep the list of flags below sorted alphabetically
+  ( "AllowAmbiguousTypes",              Opt_AllowAmbiguousTypes, nop),
+  ( "AlternativeLayoutRule",            Opt_AlternativeLayoutRule, nop ),
+  ( "AlternativeLayoutRuleTransitional",Opt_AlternativeLayoutRuleTransitional, nop ),
+  ( "Arrows",                           Opt_Arrows, nop ),
+  ( "AutoDeriveTypeable",               Opt_AutoDeriveTypeable, nop ),
+  ( "BangPatterns",                     Opt_BangPatterns, nop ),
+  ( "BinaryLiterals",                   Opt_BinaryLiterals, nop ),
+  ( "CApiFFI",                          Opt_CApiFFI, nop ),
   ( "CPP",                              Opt_Cpp, nop ),
-  ( "PostfixOperators",                 Opt_PostfixOperators, nop ),
-  ( "TupleSections",                    Opt_TupleSections, nop ),
-  ( "PatternGuards",                    Opt_PatternGuards, nop ),
-  ( "UnicodeSyntax",                    Opt_UnicodeSyntax, nop ),
-  ( "MagicHash",                        Opt_MagicHash, nop ),
-  ( "ExistentialQuantification",        Opt_ExistentialQuantification, nop ),
-  ( "KindSignatures",                   Opt_KindSignatures, nop ),
-  ( "RoleAnnotations",                  Opt_RoleAnnotations, nop ),
+  ( "ConstrainedClassMethods",          Opt_ConstrainedClassMethods, nop ),
+  ( "ConstraintKinds",                  Opt_ConstraintKinds, nop ),
+  ( "DataKinds",                        Opt_DataKinds, nop ),
+  ( "DatatypeContexts",                 Opt_DatatypeContexts,
+     \ turn_on -> when turn_on
+             $ deprecate $ "It was widely considered a misfeature, " ++
+                           "and has been removed from the Haskell language." ),
+  ( "DefaultSignatures",                Opt_DefaultSignatures, nop ),
+  ( "DeriveDataTypeable",               Opt_DeriveDataTypeable, nop ),
+  ( "DeriveFoldable",                   Opt_DeriveFoldable, nop ),
+  ( "DeriveFunctor",                    Opt_DeriveFunctor, nop ),
+  ( "DeriveGeneric",                    Opt_DeriveGeneric, nop ),
+  ( "DeriveTraversable",                Opt_DeriveTraversable, nop ),
+  ( "DisambiguateRecordFields",         Opt_DisambiguateRecordFields, nop ),
+  ( "DoAndIfThenElse",                  Opt_DoAndIfThenElse, nop ),
+  ( "DoRec",                            Opt_RecursiveDo,
+           deprecatedForExtension "RecursiveDo" ),
+  ( "EmptyCase",                        Opt_EmptyCase, nop ),
   ( "EmptyDataDecls",                   Opt_EmptyDataDecls, nop ),
-  ( "ParallelListComp",                 Opt_ParallelListComp, nop ),
-  ( "TransformListComp",                Opt_TransformListComp, nop ),
-  ( "MonadComprehensions",              Opt_MonadComprehensions, nop),
+  ( "ExistentialQuantification",        Opt_ExistentialQuantification, nop ),
+  ( "ExplicitForAll",                   Opt_ExplicitForAll, nop ),
+  ( "ExplicitNamespaces",               Opt_ExplicitNamespaces, nop ),
+  ( "ExtendedDefaultRules",             Opt_ExtendedDefaultRules, nop ),
+  ( "FlexibleContexts",                 Opt_FlexibleContexts, nop ),
+  ( "FlexibleInstances",                Opt_FlexibleInstances, nop ),
   ( "ForeignFunctionInterface",         Opt_ForeignFunctionInterface, nop ),
-  ( "UnliftedFFITypes",                 Opt_UnliftedFFITypes, nop ),
-  ( "InterruptibleFFI",                 Opt_InterruptibleFFI, nop ),
-  ( "CApiFFI",                          Opt_CApiFFI, nop ),
+  ( "FunctionalDependencies",           Opt_FunctionalDependencies, nop ),
+  ( "GADTSyntax",                       Opt_GADTSyntax, nop ),
+  ( "GADTs",                            Opt_GADTs, nop ),
   ( "GHCForeignImportPrim",             Opt_GHCForeignImportPrim, nop ),
+  ( "GeneralizedNewtypeDeriving",       Opt_GeneralizedNewtypeDeriving,
+                                setGenDeriving ),
+  ( "ImplicitParams",                   Opt_ImplicitParams, nop ),
+  ( "ImplicitPrelude",                  Opt_ImplicitPrelude, nop ),
+  ( "ImpredicativeTypes",               Opt_ImpredicativeTypes, nop),
+  ( "IncoherentInstances",              Opt_IncoherentInstances, nop ),
+  ( "InstanceSigs",                     Opt_InstanceSigs, nop ),
+  ( "InterruptibleFFI",                 Opt_InterruptibleFFI, nop ),
   ( "JavaScriptFFI",                    Opt_JavaScriptFFI, nop ),
+  ( "KindSignatures",                   Opt_KindSignatures, nop ),
+  ( "LambdaCase",                       Opt_LambdaCase, nop ),
   ( "LiberalTypeSynonyms",              Opt_LiberalTypeSynonyms, nop ),
-
-  ( "PolymorphicComponents",            Opt_RankNTypes, nop),
-  ( "Rank2Types",                       Opt_RankNTypes, nop),
-  ( "RankNTypes",                       Opt_RankNTypes, nop ),
-
-  ( "ImpredicativeTypes",               Opt_ImpredicativeTypes, nop),
-  ( "TypeOperators",                    Opt_TypeOperators, nop ),
-  ( "ExplicitNamespaces",               Opt_ExplicitNamespaces, nop ),
-  ( "RecursiveDo",                      Opt_RecursiveDo, nop ),  -- Enables 'mdo' and 'rec'
-  ( "DoRec",                            Opt_RecursiveDo,
-     deprecatedForExtension "RecursiveDo" ),
-  ( "Arrows",                           Opt_Arrows, nop ),
-  ( "ParallelArrays",                   Opt_ParallelArrays, nop ),
-  ( "TemplateHaskell",                  Opt_TemplateHaskell, checkTemplateHaskellOk ),
-  ( "QuasiQuotes",                      Opt_QuasiQuotes, nop ),
-  ( "ImplicitPrelude",                  Opt_ImplicitPrelude, nop ),
-  ( "RecordWildCards",                  Opt_RecordWildCards, nop ),
+  ( "MagicHash",                        Opt_MagicHash, nop ),
+  ( "MonadComprehensions",              Opt_MonadComprehensions, nop),
+  ( "MonoLocalBinds",                   Opt_MonoLocalBinds, nop ),
+  ( "MonoPatBinds",                     Opt_MonoPatBinds,
+     \ turn_on -> when turn_on
+                $ deprecate "Experimental feature now removed; has no effect" ),
+  ( "MonomorphismRestriction",          Opt_MonomorphismRestriction, nop ),
+  ( "MultiParamTypeClasses",            Opt_MultiParamTypeClasses, nop ),
+  ( "MultiWayIf",                       Opt_MultiWayIf, nop ),
+  ( "NPlusKPatterns",                   Opt_NPlusKPatterns, nop ),
   ( "NamedFieldPuns",                   Opt_RecordPuns, nop ),
-  ( "RecordPuns",                       Opt_RecordPuns,
-    deprecatedForExtension "NamedFieldPuns" ),
-  ( "DisambiguateRecordFields",         Opt_DisambiguateRecordFields, nop ),
-  ( "OverloadedStrings",                Opt_OverloadedStrings, nop ),
+  ( "NegativeLiterals",                 Opt_NegativeLiterals, nop ),
+  ( "NondecreasingIndentation",         Opt_NondecreasingIndentation, nop ),
+  ( "NullaryTypeClasses",               Opt_NullaryTypeClasses,
+                        deprecatedForExtension "MultiParamTypeClasses" ),
   ( "NumDecimals",                      Opt_NumDecimals, nop),
+  ( "OverlappingInstances",             Opt_OverlappingInstances,
+        \ turn_on -> when turn_on
+             $ deprecate "instead use per-instance pragmas OVERLAPPING/OVERLAPPABLE/OVERLAPS" ),
   ( "OverloadedLists",                  Opt_OverloadedLists, nop),
-  ( "GADTs",                            Opt_GADTs, nop ),
-  ( "GADTSyntax",                       Opt_GADTSyntax, nop ),
-  ( "ViewPatterns",                     Opt_ViewPatterns, nop ),
-  ( "TypeFamilies",                     Opt_TypeFamilies, nop ),
-  ( "BangPatterns",                     Opt_BangPatterns, nop ),
-  ( "MonomorphismRestriction",          Opt_MonomorphismRestriction, nop ),
-  ( "NPlusKPatterns",                   Opt_NPlusKPatterns, nop ),
-  ( "DoAndIfThenElse",                  Opt_DoAndIfThenElse, nop ),
-  ( "RebindableSyntax",                 Opt_RebindableSyntax, nop ),
-  ( "ConstraintKinds",                  Opt_ConstraintKinds, nop ),
+  ( "OverloadedStrings",                Opt_OverloadedStrings, nop ),
+  ( "PackageImports",                   Opt_PackageImports, nop ),
+  ( "ParallelArrays",                   Opt_ParallelArrays, nop ),
+  ( "ParallelListComp",                 Opt_ParallelListComp, nop ),
+  ( "PatternGuards",                    Opt_PatternGuards, nop ),
+  ( "PatternSignatures",                Opt_ScopedTypeVariables,
+                       deprecatedForExtension "ScopedTypeVariables" ),
+  ( "PatternSynonyms",                  Opt_PatternSynonyms, nop ),
   ( "PolyKinds",                        Opt_PolyKinds, nop ),
-  ( "DataKinds",                        Opt_DataKinds, nop ),
-  ( "InstanceSigs",                     Opt_InstanceSigs, nop ),
-  ( "MonoPatBinds",                     Opt_MonoPatBinds,
-    \ turn_on -> when turn_on $ deprecate "Experimental feature now removed; has no effect" ),
-  ( "ExplicitForAll",                   Opt_ExplicitForAll, nop ),
-  ( "AlternativeLayoutRule",            Opt_AlternativeLayoutRule, nop ),
-  ( "AlternativeLayoutRuleTransitional",Opt_AlternativeLayoutRuleTransitional, nop ),
-  ( "DatatypeContexts",                 Opt_DatatypeContexts,
-    \ turn_on -> when turn_on $ deprecate "It was widely considered a misfeature, and has been removed from the Haskell language." ),
-  ( "NondecreasingIndentation",         Opt_NondecreasingIndentation, nop ),
+  ( "PolymorphicComponents",            Opt_RankNTypes, nop),
+  ( "PostfixOperators",                 Opt_PostfixOperators, nop ),
+  ( "QuasiQuotes",                      Opt_QuasiQuotes, nop ),
+  ( "Rank2Types",                       Opt_RankNTypes, nop),
+  ( "RankNTypes",                       Opt_RankNTypes, nop ),
+  ( "RebindableSyntax",                 Opt_RebindableSyntax, nop ),
+  ( "RecordPuns",                       Opt_RecordPuns,
+                deprecatedForExtension "NamedFieldPuns" ),
+  ( "RecordWildCards",                  Opt_RecordWildCards, nop ),
+  ( "RecursiveDo",                      Opt_RecursiveDo, nop ),
   ( "RelaxedLayout",                    Opt_RelaxedLayout, nop ),
-  ( "TraditionalRecordSyntax",          Opt_TraditionalRecordSyntax, nop ),
-  ( "LambdaCase",                       Opt_LambdaCase, nop ),
-  ( "MultiWayIf",                       Opt_MultiWayIf, nop ),
-  ( "MonoLocalBinds",                   Opt_MonoLocalBinds, nop ),
   ( "RelaxedPolyRec",                   Opt_RelaxedPolyRec,
-    \ turn_on -> unless turn_on
-               $ deprecate "You can't turn off RelaxedPolyRec any more" ),
-  ( "ExtendedDefaultRules",             Opt_ExtendedDefaultRules, nop ),
-  ( "ImplicitParams",                   Opt_ImplicitParams, nop ),
+        \ turn_on -> unless turn_on
+                     $ deprecate "You can't turn off RelaxedPolyRec any more" ),
+  ( "RoleAnnotations",                  Opt_RoleAnnotations, nop ),
   ( "ScopedTypeVariables",              Opt_ScopedTypeVariables, nop ),
-  ( "AllowAmbiguousTypes",              Opt_AllowAmbiguousTypes, nop),
-
-  ( "PatternSignatures",                Opt_ScopedTypeVariables,
-    deprecatedForExtension "ScopedTypeVariables" ),
-
-  ( "UnboxedTuples",                    Opt_UnboxedTuples, nop ),
   ( "StandaloneDeriving",               Opt_StandaloneDeriving, nop ),
-  ( "DeriveDataTypeable",               Opt_DeriveDataTypeable, nop ),
-  ( "AutoDeriveTypeable",               Opt_AutoDeriveTypeable, nop ),
-  ( "DeriveFunctor",                    Opt_DeriveFunctor, nop ),
-  ( "DeriveTraversable",                Opt_DeriveTraversable, nop ),
-  ( "DeriveFoldable",                   Opt_DeriveFoldable, nop ),
-  ( "DeriveGeneric",                    Opt_DeriveGeneric, nop ),
-  ( "DefaultSignatures",                Opt_DefaultSignatures, nop ),
+  ( "TemplateHaskell",                  Opt_TemplateHaskell,
+                     checkTemplateHaskellOk ),
+  ( "TraditionalRecordSyntax",          Opt_TraditionalRecordSyntax, nop ),
+  ( "TransformListComp",                Opt_TransformListComp, nop ),
+  ( "TupleSections",                    Opt_TupleSections, nop ),
+  ( "TypeFamilies",                     Opt_TypeFamilies, nop ),
+  ( "TypeOperators",                    Opt_TypeOperators, nop ),
   ( "TypeSynonymInstances",             Opt_TypeSynonymInstances, nop ),
-  ( "FlexibleContexts",                 Opt_FlexibleContexts, nop ),
-  ( "FlexibleInstances",                Opt_FlexibleInstances, nop ),
-  ( "ConstrainedClassMethods",          Opt_ConstrainedClassMethods, nop ),
-  ( "MultiParamTypeClasses",            Opt_MultiParamTypeClasses, nop ),
-  ( "NullaryTypeClasses",               Opt_NullaryTypeClasses,
-    deprecatedForExtension "MultiParamTypeClasses" ),
-  ( "FunctionalDependencies",           Opt_FunctionalDependencies, nop ),
-  ( "GeneralizedNewtypeDeriving",       Opt_GeneralizedNewtypeDeriving, setGenDeriving ),
-  ( "OverlappingInstances",             Opt_OverlappingInstances,
-    \ turn_on -> when turn_on
-               $ deprecate "instead use per-instance pragmas OVERLAPPING/OVERLAPPABLE/OVERLAPS" ),
+  ( "UnboxedTuples",                    Opt_UnboxedTuples, nop ),
   ( "UndecidableInstances",             Opt_UndecidableInstances, nop ),
-  ( "IncoherentInstances",              Opt_IncoherentInstances, nop ),
-  ( "PackageImports",                   Opt_PackageImports, nop ),
-  ( "BinaryLiterals",                   Opt_BinaryLiterals, nop ),
-  ( "NegativeLiterals",                 Opt_NegativeLiterals, nop ),
-  ( "EmptyCase",                        Opt_EmptyCase, nop ),
-  ( "PatternSynonyms",                  Opt_PatternSynonyms, nop )
+  ( "UnicodeSyntax",                    Opt_UnicodeSyntax, nop ),
+  ( "UnliftedFFITypes",                 Opt_UnliftedFFITypes, nop ),
+  ( "ViewPatterns",                     Opt_ViewPatterns, nop )
   ]
 
 defaultFlags :: Settings -> [GeneralFlag]
 defaultFlags settings
+-- See Note [Updating flag description in the User's Guide]
   = [ Opt_AutoLinkPackages,
-
-      Opt_SharedImplib,
-
-      Opt_OmitYields,
-
-      Opt_GenManifest,
       Opt_EmbedManifest,
-      Opt_PrintBindContents,
-      Opt_GhciSandbox,
+      Opt_FlatCache,
+      Opt_GenManifest,
       Opt_GhciHistory,
+      Opt_GhciSandbox,
       Opt_HelpfulErrors,
+      Opt_OmitYields,
+      Opt_PrintBindContents,
       Opt_ProfCountEntries,
-      Opt_SimplPreInlining,
-      Opt_FlatCache,
-      Opt_RPath
+      Opt_RPath,
+      Opt_SharedImplib,
+      Opt_SimplPreInlining
     ]
 
     ++ [f | (ns,f) <- optLevelFlags, 0 `elem` ns]
@@ -2959,6 +2986,7 @@ default_PIC platform =
 
 impliedFlags :: [(ExtensionFlag, TurnOnFlag, ExtensionFlag)]
 impliedFlags
+-- See Note [Updating flag description in the User's Guide]
   = [ (Opt_RankNTypes,                turnOn, Opt_ExplicitForAll)
     , (Opt_ScopedTypeVariables,       turnOn, Opt_ExplicitForAll)
     , (Opt_LiberalTypeSynonyms,       turnOn, Opt_ExplicitForAll)
@@ -3004,58 +3032,71 @@ impliedFlags
     , (Opt_DeriveTraversable, turnOn, Opt_DeriveFoldable)
   ]
 
+-- Note [Documenting optimisation flags]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--
+-- If you change the list of flags enabled for particular optimisation levels
+-- please remember to update the User's Guide. The relevant files are:
+--
+--  * docs/users_guide/flags.xml
+--  * docs/users_guide/using.xml
+--
+-- The first contains the Flag Refrence section, which breifly lists all
+-- available flags. The second contains a detailed description of the
+-- flags. Both places should contain information whether a flag is implied by
+-- -O0, -O or -O2.
+
 optLevelFlags :: [([Int], GeneralFlag)]
-optLevelFlags
-  = [ ([0],     Opt_IgnoreInterfacePragmas)
+optLevelFlags -- see Note [Documenting optimisation flags]
+  = [ ([0,1,2], Opt_DoLambdaEtaExpansion)
+    , ([0,1,2], Opt_DmdTxDictSel)
+    , ([0,1,2], Opt_LlvmTBAA)
+    , ([0,1,2], Opt_VectorisationAvoidance)
+                -- This one is important for a tiresome reason:
+                -- we want to make sure that the bindings for data
+                -- constructors are eta-expanded.  This is probably
+                -- a good thing anyway, but it seems fragile.
+
+    , ([0],     Opt_IgnoreInterfacePragmas)
     , ([0],     Opt_OmitInterfacePragmas)
 
-    , ([1,2],   Opt_IgnoreAsserts)
-    , ([1,2],   Opt_EnableRewriteRules)  -- Off for -O0; see Note [Scoping for Builtin rules]
-                                         --              in PrelRules
-    , ([1,2],   Opt_DoEtaReduction)
-    , ([1,2],   Opt_CaseMerge)
     , ([1,2],   Opt_CallArity)
-    , ([1,2],   Opt_Strictness)
+    , ([1,2],   Opt_CaseMerge)
+    , ([1,2],   Opt_CmmElimCommonBlocks)
+    , ([1,2],   Opt_CmmSink)
     , ([1,2],   Opt_CSE)
+    , ([1,2],   Opt_DoEtaReduction)
+    , ([1,2],   Opt_EnableRewriteRules)  -- Off for -O0; see Note [Scoping for Builtin rules]
+                                         --              in PrelRules
+    , ([1,2],   Opt_FloatIn)
     , ([1,2],   Opt_FullLaziness)
+    , ([1,2],   Opt_IgnoreAsserts)
+    , ([1,2],   Opt_Loopification)
     , ([1,2],   Opt_Specialise)
-    , ([1,2],   Opt_FloatIn)
+    , ([1,2],   Opt_Strictness)
     , ([1,2],   Opt_UnboxSmallStrictFields)
 
     , ([2],     Opt_LiberateCase)
     , ([2],     Opt_SpecConstr)
--- XXX disabled, see #7192
---    , ([2],     Opt_RegsGraph)
-    , ([0,1,2], Opt_LlvmTBAA)
-    , ([1,2],   Opt_CmmSink)
-    , ([1,2],   Opt_CmmElimCommonBlocks)
-    , ([1,2],   Opt_Loopification)
-
-    , ([0,1,2],     Opt_DmdTxDictSel)
-
---     , ([2],     Opt_StaticArgumentTransformation)
--- Max writes: I think it's probably best not to enable SAT with -O2 for the
--- 6.10 release. The version of SAT in HEAD at the moment doesn't incorporate
--- several improvements to the heuristics, and I'm concerned that without
--- those changes SAT will interfere with some attempts to write "high
--- performance Haskell", as we saw in some posts on Haskell-Cafe earlier
--- this year. In particular, the version in HEAD lacks the tail call
--- criterion, so many things that look like reasonable loops will be
--- turned into functions with extra (unneccesary) thunk creation.
-
-    , ([0,1,2], Opt_DoLambdaEtaExpansion)
-                -- This one is important for a tiresome reason:
-                -- we want to make sure that the bindings for data
-                -- constructors are eta-expanded.  This is probably
-                -- a good thing anyway, but it seems fragile.
-    , ([0,1,2], Opt_VectorisationAvoidance)
+--  , ([2],     Opt_RegsGraph)
+--   RegsGraph suffers performance regression. See #7679
+--  , ([2],     Opt_StaticArgumentTransformation)
+--   Static Argument Transformation needs investigation. See #9374
     ]
 
 -- -----------------------------------------------------------------------------
 -- Standard sets of warning options
 
+-- Note [Documenting warning flags]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--
+-- If you change the list of warning enabled by default
+-- please remember to update the User's Guide. The relevant file is:
+--
+--  * docs/users_guide/using.xml
+
 standardWarnings :: [WarningFlag]
-standardWarnings
+standardWarnings -- see Note [Documenting warning flags]
     = [ Opt_WarnOverlappingPatterns,
         Opt_WarnWarningsDeprecations,
         Opt_WarnDeprecatedFlags,
@@ -3112,37 +3153,37 @@ disableGlasgowExts = do unSetGeneralFlag Opt_PrintExplicitForalls
 
 glasgowExtsFlags :: [ExtensionFlag]
 glasgowExtsFlags = [
-             Opt_ForeignFunctionInterface
-           , Opt_UnliftedFFITypes
-           , Opt_ImplicitParams
-           , Opt_ScopedTypeVariables
-           , Opt_UnboxedTuples
-           , Opt_TypeSynonymInstances
-           , Opt_StandaloneDeriving
+             Opt_ConstrainedClassMethods
            , Opt_DeriveDataTypeable
-           , Opt_DeriveFunctor
            , Opt_DeriveFoldable
-           , Opt_DeriveTraversable
+           , Opt_DeriveFunctor
            , Opt_DeriveGeneric
+           , Opt_DeriveTraversable
+           , Opt_EmptyDataDecls
+           , Opt_ExistentialQuantification
+           , Opt_ExplicitNamespaces
            , Opt_FlexibleContexts
            , Opt_FlexibleInstances
-           , Opt_ConstrainedClassMethods
-           , Opt_MultiParamTypeClasses
+           , Opt_ForeignFunctionInterface
            , Opt_FunctionalDependencies
+           , Opt_GeneralizedNewtypeDeriving
+           , Opt_ImplicitParams
+           , Opt_KindSignatures
+           , Opt_LiberalTypeSynonyms
            , Opt_MagicHash
-           , Opt_ExistentialQuantification
-           , Opt_UnicodeSyntax
-           , Opt_PostfixOperators
+           , Opt_MultiParamTypeClasses
+           , Opt_ParallelListComp
            , Opt_PatternGuards
-           , Opt_LiberalTypeSynonyms
+           , Opt_PostfixOperators
            , Opt_RankNTypes
-           , Opt_TypeOperators
-           , Opt_ExplicitNamespaces
            , Opt_RecursiveDo
-           , Opt_ParallelListComp
-           , Opt_EmptyDataDecls
-           , Opt_KindSignatures
-           , Opt_GeneralizedNewtypeDeriving ]
+           , Opt_ScopedTypeVariables
+           , Opt_StandaloneDeriving
+           , Opt_TypeOperators
+           , Opt_TypeSynonymInstances
+           , Opt_UnboxedTuples
+           , Opt_UnicodeSyntax
+           , Opt_UnliftedFFITypes ]
 
 #ifdef GHCI
 -- Consult the RTS to find whether GHC itself has been built profiled
index eb7ede0..123db17 100644 (file)
@@ -115,6 +115,7 @@ staticFlags = unsafePerformIO $ do
 -- is a prefix flag (i.e. HasArg, Prefix, OptPrefix, AnySuffix) will override
 -- flags further down the list with the same prefix.
 
+-- see Note [Updating flag description in the User's Guide] in DynFlags
 flagsStatic :: [Flag IO]
 flagsStatic = [
   ------ Debugging ----------------------------------------------------
@@ -137,6 +138,7 @@ isStaticFlag :: String -> Bool
 isStaticFlag f = f `elem` flagsStaticNames
 
 
+-- see Note [Updating flag description in the User's Guide] in DynFlags
 flagsStaticNames :: [String]
 flagsStaticNames = [
     "fno-state-hack",
@@ -149,7 +151,7 @@ flagsStaticNames = [
 -- the existing flags do nothing other than control debugging and some low-level
 -- optimizer phases, so for the most part this is OK.
 --
--- See GHC issue #8267: http://ghc.haskell.org/trac/ghc/ticket/8276#comment:37
+-- See GHC issue #8276: http://ghc.haskell.org/trac/ghc/ticket/8276#comment:37
 discardStaticFlags :: [String] -> [String]
 discardStaticFlags = filter (\x -> x `notElem` flags)
   where flags = [ "-fno-state-hack"
@@ -187,6 +189,8 @@ lookUp sw = sw `elem` packed_static_opts
 
 -- debugging options
 
+-- see Note [Updating flag description in the User's Guide] in DynFlags
+
 opt_PprStyle_Debug :: Bool
 opt_PprStyle_Debug = lookUp  (fsLit "-dppr-debug")
 
index c7954a7..7c1e65a 100644 (file)
@@ -81,6 +81,8 @@
                     <option>-XTypeFamilies</option>, <option>-XGADTs</option> or
                     <option>-XFlexibleContexts</option>).
                 </para>
+           </listitem>
+           <listitem>
                 <para>
                     <option>-fwarn-tabs</option> warning flag is turned on by
                     default with this release of GHC. It can be suppressed
index 6e005d5..ac3cc04 100644 (file)
           <row>
             <entry><option>-H</option><replaceable>size</replaceable></entry>
             <entry>Set the minimum heap size to <replaceable>size</replaceable></entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-Rghc-timing</option></entry>
             <entry>Summarise timing stats for GHC (same as <literal>+RTS -tstderr</literal>)</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
         </tbody>
           <row>
             <entry><option>-x</option> <replaceable>suffix</replaceable></entry>
             <entry>Override default behaviour for source files</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
         </tbody>
             <entry><option>-i</option><replaceable>dir1</replaceable>:<replaceable>dir2</replaceable>:...</entry>
             <entry>add <replaceable>dir</replaceable>,
               <replaceable>dir2</replaceable>, etc. to import path</entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-i</option></entry>
             <entry>Empty the import directory list</entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
         </tbody>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-fbreak-on-exception</option></entry>
-            <entry><link linkend="ghci-debugger-exceptions">Break on any exception thrown</link></entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-break-on-exception</option></entry>
-          </row>
-          <row>
             <entry><option>-fbreak-on-error</option></entry>
             <entry><link linkend="ghci-debugger-exceptions">Break on uncaught exceptions and errors</link></entry>
             <entry>dynamic</entry>
             <entry><option>-fno-break-on-error</option></entry>
           </row>
           <row>
+            <entry><option>-fbreak-on-exception</option></entry>
+            <entry><link linkend="ghci-debugger-exceptions">Break on any exception thrown</link></entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-break-on-exception</option></entry>
+          </row>
+          <row>
             <entry><option>-fghci-hist-size=<replaceable>n</replaceable></option></entry>
             <entry><link linkend="ghci-debugger">Set the number of entries GHCi keeps for <literal>:history</literal></link></entry>
             <entry>dynamic</entry>
           <row>
             <entry><option>-this-package-key</option> <replaceable>P</replaceable></entry>
             <entry>Compile to be part of package <replaceable>P</replaceable></entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-package</option> <replaceable>P</replaceable></entry>
             <entry>Expose package <replaceable>P</replaceable></entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-hide-all-packages</option></entry>
             <entry>Hide all packages by default</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-hide-package</option> <replaceable>name</replaceable></entry>
             <entry>Hide package <replaceable>P</replaceable></entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-ignore-package</option> <replaceable>name</replaceable></entry>
             <entry>Ignore package <replaceable>P</replaceable></entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-package-db</option> <replaceable>file</replaceable></entry>
             <entry>Add <replaceable>file</replaceable> to the package db stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-clear-package-db</option></entry>
             <entry>Clear the package db stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-no-global-package-db</option></entry>
             <entry>Remove the global package db from the stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-global-package-db</option></entry>
             <entry>Add the global package db to the stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-no-user-package-db</option></entry>
             <entry>Remove the user's package db from the stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-user-package-db</option></entry>
             <entry>Add the user's package db to the stack.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-trust</option> <replaceable>P</replaceable></entry>
             <entry>Expose package <replaceable>P</replaceable> and set it to be
               trusted</entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-distrust</option> <replaceable>P</replaceable></entry>
             <entry>Expose package <replaceable>P</replaceable> and set it to be
               distrusted</entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-distrust-all</option> </entry>
             <entry>Distrust all packages by default</entry>
-            <entry>static/<literal>:set</literal></entry>
+            <entry>dynamic/<literal>:set</literal></entry>
             <entry>-</entry>
           </row>
         </tbody>
 
     <para>Language options can be enabled either by a command-line option
       <option>-Xblah</option>, or by a <literal>{-# LANGUAGE blah #-}</literal>
-      pragma in the file itself.  See <xref linkend="options-language"/></para>
+      pragma in the file itself.  See <xref linkend="options-language"/>. Some
+      options are enabled using <option>-f*</option> flags.</para>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
         </thead>
         <tbody>
           <row>
-            <entry><option>-fcontext-stack=N</option><replaceable>n</replaceable></entry>
+            <entry><option>-fcontext-stack=</option><replaceable>n</replaceable></entry>
             <entry>set the <link linkend="undecidable-instances">limit for type-class context reduction</link>. Default is 100.</entry>
             <entry>dynamic</entry>
             <entry></entry>
             <entry><option>-</option></entry>
           </row>
           <row>
-            <entry><option>-ftype-function-depth=N</option><replaceable>n</replaceable></entry>
+            <entry><option>-ftype-function-depth=</option><replaceable>n</replaceable></entry>
             <entry>set the <link linkend="type-families">limit for type function reductions</link>. Default is 200.</entry>
             <entry>dynamic</entry>
             <entry></entry>
         </thead>
         <tbody>
           <row>
+            <entry><option>-O0</option></entry>
+            <entry>Disable optimisations (default)</entry>
+            <entry>dynamic</entry>
             <entry><option>-O</option></entry>
-            <entry>Enable default optimisation (level 1)</entry>
+          </row>
+          <row>
+            <entry><option>-O</option> or <option>-O1</option></entry>
+            <entry>Enable level 1 optimisations</entry>
             <entry>dynamic</entry>
             <entry><option>-O0</option></entry>
           </row>
           <row>
-            <entry><option>-O</option><replaceable>n</replaceable></entry>
-            <entry>Set optimisation level <replaceable>n</replaceable></entry>
+            <entry><option>-O2</option></entry>
+            <entry>Enable level 2 optimisations</entry>
             <entry>dynamic</entry>
             <entry><option>-O0</option></entry>
           </row>
+          <row>
+            <entry><option>-Odph</option></entry>
+            <entry>Enable level 2 optimisations, set <option>-fmax-simplifier-iterations=20</option>
+                   and <option>-fsimplifier-phases=3</option>.</entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
         </tbody>
       </tgroup>
     </informaltable>
 
+    <para>See <xref linkend="options-f-compact"/> for a list of optimisations enabled on level 1 and level 2.</para>
+
   </sect2>
   <sect2 id="options-f-compact">
     <title>Individual optimisations</title>
 
-    <para>These options are described in more detail in <xref linkend="options-f"/>.</para>
+    <para>These options are described in more detail in <xref linkend="options-f"/>.
+          If a flag is implied by <option>-O</option> then it is also implied by
+          <option>-O2</option> (unless flag description explicitly says otherwise).
+          If a flag is implied by <option>-O0</option> only then the flag is not
+          implied by <option>-O</option> and <option>-O2</option>.
+    </para>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
         </thead>
         <tbody>
           <row>
+            <entry><option>-fcall-arity</option></entry>
+            <entry>Enable call-arity optimisation. Implied by <option>-O</option>.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-call-arity</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fcase-merge</option></entry>
             <entry>Enable case-merging. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
+            <entry><option>-fcmm-elim-common-blocks</option></entry>
+            <entry>Enable Cmm common block elimination. Implied by <option>-O</option>.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-cmm-elim-common-blocks</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fcmm-sink</option></entry>
+            <entry>Enable Cmm sinking. Implied by <option>-O</option>.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-cmm-sink</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fcpr-off</option></entry>
+            <entry>Switch off CPR analysis in the demand analyser.</entry>
+            <entry>static</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
             <entry><option>-fcse</option></entry>
-            <entry>Turn on common sub-expression elimination. Implied by <option>-O</option>.</entry>
+            <entry>Enable common sub-expression elimination. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-cse</option></entry>
           </row>
 
           <row>
+            <entry><option>-fdicts-cheap</option></entry>
+            <entry>Make dictionary-valued expressions seem cheap to the optimiser.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-dicts-cheap</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fdicts-strict</option></entry>
             <entry>Make dictionaries strict</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry><option>-fno-dicts-strict</option></entry>
           </row>
 
           <row>
+            <entry><option>-fdmd-tx-dict-sel</option>
+            </entry>
+            <entry>Use a special demand transformer for dictionary selectors.
+                   Always enabled by default.
+            </entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-dmd-tx-dict-sel</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fdo-eta-reduction</option></entry>
             <entry>Enable eta-reduction. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
 
           <row>
             <entry><option>-fdo-lambda-eta-expansion</option></entry>
-            <entry>Enable lambda eta-reduction</entry>
+            <entry>Enable lambda eta-expansion. Always enabled by default.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-do-lambda-eta-expansion</option></entry>
           </row>
           </row>
 
           <row>
-            <entry><option>-fvectorise</option></entry>
-            <entry>Enable vectorisation of nested data parallelism</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-vectorise</option></entry>
-          </row>
-
-          <row>
-            <entry><option>-favoid-vect</option></entry>
-            <entry>Enable vectorisation avoidance (EXPERIMENTAL)</entry>
+            <entry><option>-fexcess-precision</option></entry>
+            <entry>Enable excess intermediate precision</entry>
             <entry>dynamic</entry>
-            <entry><option>-fno-avoid-vect</option></entry>
+            <entry><option>-fno-excess-precision</option></entry>
           </row>
 
           <row>
-            <entry><option>-fexcess-precision</option></entry>
-            <entry>Enable excess intermediate precision</entry>
+            <entry><option>-fexpose-all-unfoldings</option></entry>
+            <entry>Expose all unfoldings, even for very large or recursive functions.</entry>
             <entry>dynamic</entry>
-            <entry><option>-fno-excess-precision</option></entry>
+            <entry><option>-fno-expose-all-unfoldings</option></entry>
           </row>
 
           <row>
 
           <row>
             <entry><option>-fignore-asserts</option></entry>
-            <entry>Ignore assertions in the source</entry>
+            <entry>Ignore assertions in the source. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-ignore-asserts</option></entry>
           </row>
 
           <row>
             <entry><option>-fignore-interface-pragmas</option></entry>
-            <entry>Ignore pragmas in interface files</entry>
+            <entry>Ignore pragmas in interface files. Implied by <option>-O0</option> only.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-ignore-interface-pragmas</option></entry>
           </row>
 
           <row>
-            <entry><option>-floopification</option></entry>
-            <entry>Turn saturated self-recursive tail-calls into local jumps in the generated assembly.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-loopification</option></entry>
-          </row>
-
-          <row>
             <entry><option>-flate-dmd-anal</option></entry>
             <entry>Run demand analysis again, at the end of the simplification
             pipeline</entry>
 
           <row>
             <entry><option>-fliberate-case-threshold</option>=<replaceable>n</replaceable></entry>
-            <entry>Set the size threshold for the liberate-case transformation to <replaceable>n</replaceable> (default: 200)</entry>
-            <entry>static</entry>
+            <entry>Set the size threshold for the liberate-case transformation to <replaceable>n</replaceable> (default: 2000)</entry>
+            <entry>dynamis</entry>
             <entry><option>-fno-liberate-case-threshold</option></entry>
           </row>
 
           <row>
-            <entry><option>-fmax-relevant-bindings=N</option></entry>
+            <entry><option>-fllvm-pass-vectors-in-regs</option>
+            </entry>
+            <entry>Attempt to pass SIMD vectors in registers for LLVM backend on 32-bit architectures. This is dangerous.
+                   See full description in <xref linkend="options-f"/> for details.
+            </entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-llvm-pass-vectors-in-regs</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fllvm-tbaa</option>
+            </entry>
+            <entry>Enable type-based alias analysis for LLVM backend.
+                   Always enabled by default.
+            </entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-llvm-tbaa</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-floopification</option></entry>
+            <entry>Turn saturated self-recursive tail-calls into local jumps in the generated assembly.
+                   Implied by <option>-O</option>.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-loopification</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fmax-inline-alloc-size</option>=<replaceable>n</replaceable></entry>
+            <entry>Set the maximum size of inline array allocations to
+            <replaceable>n</replaceable> bytes (default: 128). GHC
+            will allocate non-pinned arrays of statically known size
+            in the current nursery block if they're no bigger than
+            <replaceable>n</replaceable> bytes, ignoring GC overheap.
+            This value should be quite a bit smaller than the block
+            size (typically: 4096).</entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry>
+            <option>-fmax-inline-memcpy-insns</option>=<replaceable>n</replaceable>
+            </entry>
+            <entry>Inline memcpy calls if they would generate no more
+            than <replaceable>n</replaceable> pseudo instructions
+            (default: 32).
+            </entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry>
+            <option>-fmax-inline-memset-insns</option>=<replaceable>n</replaceable>
+            </entry>
+            <entry>Inline memset calls if they would generate no more
+            than <replaceable>n</replaceable> pseudo instructions
+            (default: 32).
+            </entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry><option>-fmax-relevant-binds=<replaceable>n</replaceable></option></entry>
             <entry>Set the maximum number of bindings to display in type error messages (default 6).</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-max-relevant-bindings</option></entry>
           </row>
 
           <row>
-            <entry><option>-fmax-simplifier-iterations=N</option></entry>
-            <entry>Set the max iterations for the simplifier</entry>
+            <entry><option>-fmax-simplifier-iterations=<replaceable>n</replaceable></option></entry>
+            <entry>Set the max iterations for the simplifier (default 4).</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-fmax-worker-args=N</option></entry>
+            <entry><option>-fmax-worker-args=<replaceable>n</replaceable></option></entry>
             <entry>If a worker has that many arguments, none will be
               unpacked anymore (default: 10)</entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
+            <entry><option>-fomit-interface-pragmas</option></entry>
+            <entry>Don't generate interface pragmas. Implied by <option>-O0</option> only.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-omit-interface-pragmas</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fomit-yields</option></entry>
+            <entry>Omit heap checks when no allocation is being performed.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-omit-yields</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fpedantic-bottoms</option></entry>
             <entry>Make GHC be more precise about its treatment of bottom (but see also
               <option>-fno-state-hack</option>). In particular, GHC will not
           </row>
 
           <row>
-            <entry><option>-fomit-interface-pragmas</option></entry>
-            <entry>Don't generate interface pragmas</entry>
+            <entry><option>-fregs-graph</option></entry>
+            <entry>Use the graph colouring register allocator for register allocation
+                   in the native code generator. Implied by <option>-O2</option>.</entry>
             <entry>dynamic</entry>
-            <entry><option>-fno-omit-interface-pragmas</option></entry>
+            <entry><option>-fno-regs-graph</option></entry>
           </row>
 
           <row>
-            <entry><option>-fsimplifier-phases</option></entry>
+            <entry><option>-fregs-iterative</option></entry>
+            <entry>Use the iterative coalescing graph colouring register allocator
+                   in the native code generator.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-regs-iterative</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fsimplifier-phases=<replaceable>n</replaceable></option></entry>
             <entry>Set the number of phases for the simplifier (default 2).
               Ignored with <option>-O0</option>.</entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
-            <entry><option>-fspec-constr-threshold</option>=<replaceable>n</replaceable></entry>
-            <entry>Set the size threshold for the SpecConstr transformation to <replaceable>n</replaceable> (default: 200)</entry>
-            <entry>static</entry>
-            <entry><option>-fno-spec-constr-threshold</option></entry>
-          </row>
-
-          <row>
             <entry><option>-fspec-constr-count</option>=<replaceable>n</replaceable></entry>
             <entry>Set to <replaceable>n</replaceable> (default: 3) the maximum number of
               specialisations that will be created for any one function
               by the SpecConstr transformation</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry><option>-fno-spec-constr-count</option></entry>
           </row>
 
           <row>
+            <entry><option>-fspec-constr-threshold</option>=<replaceable>n</replaceable></entry>
+            <entry>Set the size threshold for the SpecConstr transformation
+                   to <replaceable>n</replaceable> (default: 2000)</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-spec-constr-threshold</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fspecialise</option></entry>
             <entry>Turn on specialisation of overloaded functions. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
+            <entry><option>-fstatic-argument-transformation</option></entry>
+            <entry>Turn on the static argument transformation.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-static-argument-transformation</option></entry>
+          </row>
+
+          <row>
             <entry><option>-fstrictness</option></entry>
             <entry>Turn on strictness analysis. Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
-            <entry><option>-fstrictness=before</option>=<replaceable>n</replaceable></entry>
+            <entry><option>-fstrictness-before</option>=<replaceable>n</replaceable></entry>
             <entry>Run an additional strictness analysis before simplifier
               phase <replaceable>n</replaceable></entry>
             <entry>dynamic</entry>
           </row>
 
           <row>
-            <entry><option>-fstatic-argument-transformation</option></entry>
-            <entry>Turn on the static argument transformation. Implied by <option>-O2</option>.</entry>
+            <entry><option>-funbox-small-strict-fields</option></entry>
+            <entry>Flatten strict constructor fields with a
+              pointer-sized representation.  Implied by <option>-O</option>.</entry>
             <entry>dynamic</entry>
-            <entry><option>-fno-static-argument-transformation</option></entry>
+            <entry><option>-fno-unbox-small-strict-fields</option></entry>
           </row>
 
           <row>
           </row>
 
           <row>
-            <entry><option>-funbox-small-strict-fields</option></entry>
-            <entry>Flatten strict constructor fields with a
-              pointer-sized representation</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-unbox-small-strict-fields</option></entry>
-          </row>
-
-          <row>
-            <entry><option>-funfolding-creation-threshold</option></entry>
-            <entry>Tweak unfolding settings</entry>
+            <entry><option>-funfolding-creation-threshold=<replaceable>n</replaceable></option></entry>
+            <entry>Tweak unfolding settings. Default: 750</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-funfolding-fun-discount</option></entry>
-            <entry>Tweak unfolding settings</entry>
+            <entry><option>-funfolding-dict-discount=<replaceable>n</replaceable></option></entry>
+            <entry>Tweak unfolding settings. Default: 30</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-funfolding-dict-discount</option></entry>
-            <entry>Tweak unfolding settings</entry>
+            <entry><option>-funfolding-fun-discount=<replaceable>n</replaceable></option></entry>
+            <entry>Tweak unfolding settings. Default: 60</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-funfolding-keeness-factor</option></entry>
-            <entry>Tweak unfolding settings</entry>
+            <entry><option>-funfolding-keeness-factor=<replaceable>n</replaceable></option></entry>
+            <entry>Tweak unfolding settings. Default: 1.5</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-funfolding-use-threshold</option></entry>
-            <entry>Tweak unfolding settings</entry>
+            <entry><option>-funfolding-use-threshold=<replaceable>n</replaceable></option></entry>
+            <entry>Tweak unfolding settings. Default: 60</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
 
           <row>
-            <entry><option>-fmax-inline-alloc-size</option>=<replaceable>n</replaceable></entry>
-            <entry>Set the maximum size of inline array allocations to
-            <replaceable>n</replaceable> bytes (default: 128). GHC
-            will allocate non-pinned arrays of statically known size
-            in the current nursery block if they're no bigger than
-            <replaceable>n</replaceable> bytes, ignoring GC overheap.
-            This value should be quite a bit smaller than the block
-            size (typically: 4096).</entry>
+            <entry><option>-fvectorisation-avoidance</option></entry>
+            <entry>Enable vectorisation avoidance. Always enabled by default.</entry>
             <entry>dynamic</entry>
-            <entry>-</entry>
+            <entry><option>-fno-vectorisation-avoidance</option></entry>
           </row>
 
           <row>
-            <entry>
-            <option>-fmax-inline-memcpy-insns</option>=<replaceable>n</replaceable>
-            </entry>
-            <entry>Inline memcpy calls if they would generate no more
-            than <replaceable>n</replaceable> pseudo instructions
-            (default: 32).
-            </entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-
-          <row>
-            <entry>
-            <option>-fmax-inline-memset-insns</option>=<replaceable>n</replaceable>
-            </entry>
-            <entry>Inline memset calls if they would generate no more
-            than <replaceable>n</replaceable> pseudo instructions
-            (default: 32).
-            </entry>
+            <entry><option>-fvectorise</option></entry>
+            <entry>Enable vectorisation of nested data parallelism</entry>
             <entry>dynamic</entry>
-            <entry>-</entry>
+            <entry><option>-fno-vectorise</option></entry>
           </row>
 
         </tbody>
           <row>
             <entry><option>-prof</option></entry>
             <entry>Turn on profiling</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
           <row>
             <entry><option>-ticky</option></entry>
             <entry><link linkend="ticky-ticky">Turn on ticky-ticky profiling</link></entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
         </tbody>
           <row>
             <entry><option>-dynamic</option></entry>
             <entry>Use dynamic Haskell libraries (if available)</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-dynamic-too</option></entry>
             <entry>Build dynamic object files <emphasis>as well as</emphasis> static object files during compilation</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-dyno</option></entry>
             <entry>Set the output path for the <emphasis>dynamically</emphasis> linked objects</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-dynosuf</option></entry>
             <entry>Set the output suffix for dynamic object files</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-dynload</option></entry>
             <entry>Selects one of a number of modes for finding shared
               libraries at runtime.</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
           <row>
             <entry><option>-static</option></entry>
             <entry>Use static Haskell libraries</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-threaded</option></entry>
             <entry>Use the threaded runtime</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-debug</option></entry>
             <entry>Use the debugging runtime</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-eventlog</option></entry>
             <entry>Enable runtime event tracing</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
           <row>
             <entry><option>-fplugin</option>=<replaceable>module</replaceable></entry>
             <entry>Load a plugin exported by a given module</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry><option>-fplugin-opt</option>=<replaceable>module:args</replaceable></entry>
             <entry>Give arguments to a plugin module; module must be specified with <option>-fplugin</option></entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
         </tbody>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-dppr-noprags</option></entry>
-            <entry>Don't output pragma info in dumps</entry>
-            <entry>static</entry>
-            <entry>-</entry>
-          </row>
-          <row>
             <entry><option>-dppr-user-length</option></entry>
             <entry>Set the depth for printing expressions in error msgs</entry>
             <entry>dynamic</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
+          <row>
+            <entry><option>-frule-check</option></entry>
+            <entry>Report sites with rules that could have fired but didn't.
+                   Takes a string argument.</entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
         </tbody>
       </tgroup>
     </informaltable>
           <row>
             <entry><option>-fno-hi-version-check</option></entry>
             <entry>Don't complain about <literal>.hi</literal> file mismatches</entry>
-            <entry>static</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-dno-black-holing</option></entry>
-            <entry>Turn off black holing (probably doesn't work)</entry>
-            <entry>static</entry>
+            <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-funregisterised</option></entry>
-            <entry><link linkend="unreg">Unregisterised</link> compilation (use <option>-unreg</option> instead)</entry>
-            <entry>static</entry>
-            <entry>-</entry>
-          </row>
-          <row>
             <entry><option>-fno-ghci-history</option></entry>
             <entry>Do not use the load/store the GHCi command history from/to <literal>ghci_history</literal>.</entry>
             <entry>dynamic</entry>
index 54c127d..07d487e 100644 (file)
@@ -2006,6 +2006,21 @@ _  = rhs3        -- No warning: lone wild-card pattern
             <option>-O</option>.</para>
           </listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-Odph</option>:
+            <indexterm><primary>-Odph</primary></indexterm>
+            <indexterm><primary>optimise</primary><secondary>DPH</secondary></indexterm>
+          </term>
+          <listitem>
+            <para>Enables all <option>-O2</option> optimisation, sets
+                  <option>-fmax-simplifier-iterations=20</option>
+                  and <option>-fsimplifier-phases=3</option>. Designed for use with
+                  <link linkend="dph">Data Parallel Haskell (DPH)</link>.</para>
+          </listitem>
+        </varlistentry>
+
       </variablelist>
 
       <para>We don't use a <option>-O*</option> flag for day-to-day
@@ -2026,40 +2041,16 @@ _  = rhs3        -- No warning: lone wild-card pattern
       <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
 
       <para>These flags turn on and off individual optimisations.
-      They are normally set via the <option>-O</option> options
-      described above, and as such, you shouldn't need to set any of
-      them explicitly (indeed, doing so could lead to unexpected
-      results).  A flag <option>-fwombat</option> can be negated by 
-      saying <option>-fno-wombat</option>.  The flags below are off
-      by default, except where noted below.  See <xref linkend="options-f-compact"/> 
-      for a compact list.
+      Flags marked as <emphasis>Enabled by default</emphasis> are
+      enabled by <option>-O</option>, and as such you shouldn't
+      need to set any of them explicitly.  A flag <option>-fwombat</option>
+      can be negated by saying <option>-fno-wombat</option>.
+      See <xref linkend="options-f-compact"/> for a compact list.
      </para>
 
       <variablelist>
         <varlistentry>
           <term>
-            <option>-favoid-vect</option>
-            <indexterm><primary><option></option></primary></indexterm>
-          </term>
-          <listitem>
-            <para>Part of <link linkend="dph">Data Parallel Haskell
-            (DPH)</link>.</para>
-
-            <para><emphasis>Off by default.</emphasis> Enable the
-            <emphasis>vectorisation</emphasis> avoidance optimisation. This
-            optimisation only works when used in combination with the
-            <option>-fvectorise</option> transformation.</para>
-
-            <para>While vectorisation of code using DPH is often a big win, it
-            can also produce worse results for some kinds of code. This
-            optimisation modifies the vectorisation transformation to try to
-            determine if a function would be better of unvectorised and if
-            so, do just that.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
             <option>-fcase-merge</option>
             <indexterm><primary><option></option></primary></indexterm>
           </term>
@@ -2084,6 +2075,56 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
+            <option>-fcall-arity</option>
+            <indexterm><primary><option>-fcall-arity</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default.</emphasis>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+         <varlistentry>
+          <term>
+            <option>-fcmm-elim-common-blocks</option>
+            <indexterm><primary><option>-felim-common-blocks</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default.</emphasis>.  Enables the common block
+            elimination optimisation in the code generator. This optimisation
+            attempts to find identical Cmm blocks and eliminate the duplicates.
+            </para>
+          </listitem>
+        </varlistentry>
+
+         <varlistentry>
+          <term>
+            <option>-fcmm-sink</option>
+            <indexterm><primary><option>-fcmm-sink</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default.</emphasis>.  Enables the sinking pass
+            in the code generator. This optimisation
+            attempts to find identical Cmm blocks and eliminate the duplicates
+            attempts to move variable bindings closer to their usage sites. It
+            also inlines simple expressions like literals or registers.
+            </para>
+          </listitem>
+        </varlistentry>
+
+         <varlistentry>
+          <term>
+            <option>-fcpr-off</option>
+            <indexterm><primary><option>-fcpr-Off</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Switch off CPR analysis in the demand analyser.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fcse</option>
             <indexterm><primary><option>-fcse</option></primary></indexterm>
           </term>
@@ -2109,12 +2150,25 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
-            <option>-fdo-lambda-eta-expansion</option>
+            <option>-fdicts-strict</option>
             <indexterm><primary><option></option></primary></indexterm>
           </term>
           <listitem>
-            <para><emphasis>On by default.</emphasis>
-            Eta-expand let-bindings to increase their arity.
+            <para>Make dictionaries strict.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fdmd-tx-dict-sel</option>
+            <indexterm><primary><option>-fdmd-tx-dict-sel</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default for <option>-O0</option>, <option>-O</option>,
+                  <option>-O2</option>.</emphasis>
+            </para>
+            <para>Use a special demand transformer for dictionary selectors.
             </para>
           </listitem>
         </varlistentry>
@@ -2134,6 +2188,18 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
+            <option>-fdo-lambda-eta-expansion</option>
+            <indexterm><primary><option></option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default.</emphasis>
+            Eta-expand let-bindings to increase their arity.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-feager-blackholing</option>
             <indexterm><primary><option></option></primary></indexterm>
           </term>
@@ -2260,12 +2326,12 @@ _  = rhs3        -- No warning: lone wild-card pattern
             <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
           </term>
           <listitem>
-            <para>Causes GHC to ignore uses of the function
+            <para><emphasis>On by default.</emphasis>.
+            Causes GHC to ignore uses of the function
             <literal>Exception.assert</literal> in source code (in
             other words, rewriting <literal>Exception.assert p
             e</literal> to <literal>e</literal> (see <xref
-            linkend="assertions"/>).  This flag is turned on by
-            <option>-O</option>.
+            linkend="assertions"/>).
             </para>
           </listitem>
         </varlistentry>
@@ -2288,12 +2354,12 @@ _  = rhs3        -- No warning: lone wild-card pattern
             <indexterm><primary><option>-flate-dmd-anal</option></primary></indexterm>
           </term>
           <listitem>
-            <para><emphasis>Off by default.</emphasis>Run demand analysis
+            <para>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
             <literal>-fspec-constr</literal> can create functions with unused arguments which
             are eliminated by late demand analysis.  Improvements are modest, but so is the
-            cost.  See notes on the <ulink href="http://ghc.haskell.org/trac/ghc/wiki/LateDmd">Trac wiki page</ulink>.
+            cost.  See notes on the <ulink url="http://ghc.haskell.org/trac/ghc/wiki/LateDmd">Trac wiki page</ulink>.
             </para>
             </listitem>
         </varlistentry>
@@ -2316,26 +2382,107 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
-            <option>-fliberate-case-threshold=N</option>
+            <option>-fliberate-case-threshold=<replaceable>n</replaceable></option>
             <indexterm><primary><option>-fliberate-case-threshold</option></primary></indexterm>
           </term>
           <listitem>
-            <para>Set the size threshold for the liberate-case transformation.
+            <para>Set the size threshold for the liberate-case transformation. Default: 2000
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fllvm-pass-vectors-in-regs</option>
+            <indexterm><primary><option>-fllvm-pass-vectors-in-regs</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>On 32-bit machines it changes calling convention used with LLVM backend
+             to pass 128-bit vectors in SIMD registers. At the moment this does not work
+             because this is not supported by LLVM. We strongly suggest you don't use this flag.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fllvm-tbaa</option>
+            <indexterm><primary><option>-fllvm-tbaa</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default for <option>-O0</option>, <option>-O</option>,
+                  <option>-O2</option>.</emphasis>
+            </para>
+            <para>Enables type-based alias analysis for LLVM backend.
+                  At the moment this has limited usefullness since we pass
+                  very little information to LLVM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-floopification</option>
+            <indexterm><primary><option>-floopification</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para><emphasis>On by default.</emphasis>
+            </para>
+            <para>When this optimisation is enabled the code generator will turn
+                  all self-recursive saturated tail calls into local jumps rather
+                  than function calls.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fmax-inline-alloc-size=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fmax-inline-alloc-size</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Set the maximum size of inline array allocations to n bytes
+                 (default: 128). GHC will allocate non-pinned arrays of statically
+                 known size in the current nursery block if they're no bigger
+                 than n bytes, ignoring GC overheap. This value should be quite
+                 a bit smaller than the block size (typically: 4096).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fmax-inline-memcpy-insn=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fmax-inline-memcpy-insn</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Inline memcpy calls if they would generate no more than n pseudo instructions (default: 32).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fmax-inline-memset-insns=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fmax-inline-memset-insns</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Inline memset calls if they would generate no more than n pseudo instructions (default: 32).
             </para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term>
-            <option>-fmax-relevant-bindings=N</option>
+            <option>-fmax-relevant-binds=<replaceable>n</replaceable></option>
             <indexterm><primary><option>-fmax-relevant-bindings</option></primary></indexterm>
           </term>
           <listitem>
             <para>The type checker sometimes displays a fragment of the type environment
                   in error messages, but only up to some maximum number, set by this flag.
-                  The default is 6.  Turning it off with <option>-fno-max-relevant-bindings</option> 
-                   gives an unlimited number. Syntactically top-level bindings are also 
-                   usually excluded (since they may be numerous), but 
+                  The default is 6.  Turning it off with <option>-fno-max-relevant-bindings</option>
+                   gives an unlimited number. Syntactically top-level bindings are also
+                   usually excluded (since they may be numerous), but
                    <option>-fno-max-relevant-bindings</option> includes them too.
             </para>
           </listitem>
@@ -2343,6 +2490,50 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
+            <option>-fmax-simplifier-iterations=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fmax-simplifier-iterations</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Sets the maximal number of iterations for the simplifier. Defult: 4.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fmax-worker-args=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fmax-worker-args</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>If a worker has that many arguments, none will be unpacked anymore (default: 10)
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fno-opt-coercion</option>
+            <indexterm><primary><option>-fno-opt-coercion</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Turn off the coercion optimiser.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fno-pre-inlining</option>
+            <indexterm><primary><option>-fno-pre-inlining</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Turn off pre-inlining.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fno-state-hack</option>
             <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
           </term>
@@ -2410,11 +2601,11 @@ _  = rhs3        -- No warning: lone wild-card pattern
         <varlistentry>
           <term>
             <option>-fregs-graph</option>
-            <indexterm><primary><option></option></primary></indexterm>
+            <indexterm><primary><option>-fregs-graph</option></primary></indexterm>
           </term>
           <listitem>
-            <para><emphasis>Off by default, but enabled by -O2. Only applies in
-              combination with the native code generator.</emphasis>
+            <para><emphasis>Off by default due to a performance regression bug.
+            Only applies in combination with the native code generator.</emphasis>
             Use the graph colouring register allocator for register allocation
             in the native code generator. By default, GHC uses a simpler,
             faster linear register allocator. The downside being that the
@@ -2426,14 +2617,14 @@ _  = rhs3        -- No warning: lone wild-card pattern
         <varlistentry>
           <term>
             <option>-fregs-iterative</option>
-            <indexterm><primary><option></option></primary></indexterm>
+            <indexterm><primary><option>-fregs-iterative</option></primary></indexterm>
           </term>
           <listitem>
             <para><emphasis>Off by default, only applies in combination with
               the native code generator.</emphasis>
             Use the iterative coalescing graph colouring register allocator for
             register allocation in the native code generator. This is the same
-            register allocator as the <option>-freg-graph</option> one but also
+            register allocator as the <option>-fregs-graph</option> one but also
             enables iterative coalescing during register allocation.
             </para>
           </listitem>
@@ -2441,6 +2632,17 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
+            <option>-fsimplifier-phases=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fsimplifier-phases</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Set the number of phases for the simplifier (default 2). Ignored with -O0.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fsimpl-tick-factor=<replaceable>n</replaceable></option>
             <indexterm><primary><option>-fsimpl-tick-factor</option></primary></indexterm>
           </term>
@@ -2469,77 +2671,6 @@ _  = rhs3        -- No warning: lone wild-card pattern
 
         <varlistentry>
           <term>
-            <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
-            <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
-            <indexterm><primary>inlining, controlling</primary></indexterm>
-            <indexterm><primary>unfolding, controlling</primary></indexterm>
-          </term>
-          <listitem>
-            <para>(Default: 750) Governs the maximum size that GHC will allow a
-            function unfolding to be. (An unfolding has a &ldquo;size&rdquo;
-            that reflects the cost in terms of &ldquo;code bloat&rdquo; of
-            expanding (aka inlining) that unfolding at a call site. A bigger
-            function would be assigned a bigger cost.)
-            </para>
-
-            <para>Consequences: (a) nothing larger than this will be inlined
-            (unless it has an INLINE pragma); (b) nothing larger than this
-            will be spewed into an interface file.
-            </para>
-
-            <para>Increasing this figure is more likely to result in longer
-            compile times than faster code. The
-            <option>-funfolding-use-threshold</option> is more useful.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <option>-funfolding-use-threshold=<replaceable>n</replaceable></option>
-            <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
-            <indexterm><primary>inlining, controlling</primary></indexterm>
-            <indexterm><primary>unfolding, controlling</primary></indexterm>
-          </term>
-          <listitem>
-            <para>(Default: 60) This is the magic cut-off figure for unfolding
-            (aka inlining): below this size, a function definition will be
-            unfolded at the call-site, any bigger and it won't. The size
-            computed for a function depends on two things: the actual size of
-            the expression minus any discounts that apply depending on the
-            context into which the expression is to be inlined.
-            </para>
-
-            <para>The difference between this and
-            <option>-funfolding-creation-threshold</option> is that this one
-            determines if a function definition will be inlined <emphasis>at
-              a call site</emphasis>. The other option determines if a
-            function definition will be kept around at all for potential
-            inlining.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
-            <option>-fvectorise</option>
-            <indexterm><primary><option></option></primary></indexterm>
-          </term>
-          <listitem>
-            <para>Part of <link linkend="dph">Data Parallel Haskell
-            (DPH)</link>.</para>
-
-            <para><emphasis>Off by default.</emphasis> Enable the
-            <emphasis>vectorisation</emphasis> optimisation transformation. This
-            optimisation transforms the nested data parallelism code of programs
-            using DPH into flat data parallelism. Flat data parallel programs
-            should have better load balancing, enable SIMD parallelism and
-            friendlier cache behaviour.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>
             <option>-fspec-constr</option>
             <indexterm><primary><option>-fspec-constr</option></primary></indexterm>
           </term>
@@ -2622,6 +2753,30 @@ foldl f z (Stream step s _) = foldl_loop SPEC z s
 
         <varlistentry>
           <term>
+            <option>-fspec-constr-count=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fspec-constr-count</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Set the maximum number of specialisations
+                  that will be created for any one function by the SpecConstr
+                  transformation (default: 3).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fspec-constr-threshold=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fspec-constr-threshold</option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Set the size threshold for the SpecConstr transformation (default: 2000).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fspecialise</option>
             <indexterm><primary><option>-fspecialise</option></primary></indexterm>
           </term>
@@ -2676,25 +2831,12 @@ foldl f z (Stream step s _) = foldl_loop SPEC z s
 
         <varlistentry>
           <term>
-            <option>-funbox-strict-fields</option>:
-            <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
-            <indexterm><primary>strict constructor fields</primary></indexterm>
-            <indexterm><primary>constructor fields, strict</primary></indexterm>
+            <option>-fstrictness-before=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-fstrictness-before</option></primary></indexterm>
           </term>
           <listitem>
-            <para>This option causes all constructor fields which are marked
-            strict (i.e. &ldquo;!&rdquo;) to be unpacked if possible. It is
-            equivalent to adding an <literal>UNPACK</literal> pragma to every
-            strict constructor field (see <xref linkend="unpack-pragma"/>).
+            <para>Run an additional strictness analysis before simplifier phase n.
             </para>
-
-            <para>This option is a bit of a sledgehammer: it might sometimes
-            make things worse. Selectively unboxing fields by using
-            <literal>UNPACK</literal> pragmas might be better. An alternative
-            is to use <option>-funbox-strict-fields</option> to turn on
-            unboxing by default but disable it for certain constructor
-            fields using the <literal>NOUNPACK</literal> pragma (see
-            <xref linkend="nounpack-pragma"/>).</para>
           </listitem>
         </varlistentry>
 
@@ -2746,6 +2888,162 @@ data D = D !C
           </listitem>
         </varlistentry>
 
+        <varlistentry>
+          <term>
+            <option>-funbox-strict-fields</option>:
+            <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
+            <indexterm><primary>strict constructor fields</primary></indexterm>
+            <indexterm><primary>constructor fields, strict</primary></indexterm>
+          </term>
+          <listitem>
+            <para>This option causes all constructor fields which are marked
+            strict (i.e. &ldquo;!&rdquo;) to be unpacked if possible. It is
+            equivalent to adding an <literal>UNPACK</literal> pragma to every
+            strict constructor field (see <xref linkend="unpack-pragma"/>).
+            </para>
+
+            <para>This option is a bit of a sledgehammer: it might sometimes
+            make things worse. Selectively unboxing fields by using
+            <literal>UNPACK</literal> pragmas might be better. An alternative
+            is to use <option>-funbox-strict-fields</option> to turn on
+            unboxing by default but disable it for certain constructor
+            fields using the <literal>NOUNPACK</literal> pragma (see
+            <xref linkend="nounpack-pragma"/>).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
+            <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
+            <indexterm><primary>inlining, controlling</primary></indexterm>
+            <indexterm><primary>unfolding, controlling</primary></indexterm>
+          </term>
+          <listitem>
+            <para>(Default: 750) Governs the maximum size that GHC will allow a
+            function unfolding to be. (An unfolding has a &ldquo;size&rdquo;
+            that reflects the cost in terms of &ldquo;code bloat&rdquo; of
+            expanding (aka inlining) that unfolding at a call site. A bigger
+            function would be assigned a bigger cost.)
+            </para>
+
+            <para>Consequences: (a) nothing larger than this will be inlined
+            (unless it has an INLINE pragma); (b) nothing larger than this
+            will be spewed into an interface file.
+            </para>
+
+            <para>Increasing this figure is more likely to result in longer
+            compile times than faster code. The
+            <option>-funfolding-use-threshold</option> is more useful.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-funfolding-dict-discount=<replaceable>n</replaceable></option>:
+            <indexterm><primary><option>-funfolding-dict-discount</option></primary></indexterm>
+            <indexterm><primary>inlining, controlling</primary></indexterm>
+            <indexterm><primary>unfolding, controlling</primary></indexterm>
+          </term>
+          <listitem>
+            <para>Default: 30
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-funfolding-fun-discount=<replaceable>n</replaceable></option>:
+            <indexterm><primary><option>-funfolding-fun-discount</option></primary></indexterm>
+            <indexterm><primary>inlining, controlling</primary></indexterm>
+            <indexterm><primary>unfolding, controlling</primary></indexterm>
+          </term>
+          <listitem>
+            <para>Default: 60
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-funfolding-keeness-factor=<replaceable>n</replaceable></option>:
+            <indexterm><primary><option>-funfolding-keeness-factor</option></primary></indexterm>
+            <indexterm><primary>inlining, controlling</primary></indexterm>
+            <indexterm><primary>unfolding, controlling</primary></indexterm>
+          </term>
+          <listitem>
+            <para>Default: 1.5
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-funfolding-use-threshold=<replaceable>n</replaceable></option>
+            <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
+            <indexterm><primary>inlining, controlling</primary></indexterm>
+            <indexterm><primary>unfolding, controlling</primary></indexterm>
+          </term>
+          <listitem>
+            <para>(Default: 60) This is the magic cut-off figure for unfolding
+            (aka inlining): below this size, a function definition will be
+            unfolded at the call-site, any bigger and it won't. The size
+            computed for a function depends on two things: the actual size of
+            the expression minus any discounts that apply depending on the
+            context into which the expression is to be inlined.
+            </para>
+
+            <para>The difference between this and
+            <option>-funfolding-creation-threshold</option> is that this one
+            determines if a function definition will be inlined <emphasis>at
+              a call site</emphasis>. The other option determines if a
+            function definition will be kept around at all for potential
+            inlining.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fvectorisation-avoidance</option>
+            <indexterm><primary><option></option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Part of <link linkend="dph">Data Parallel Haskell
+            (DPH)</link>.</para>
+
+            <para><emphasis>On by default.</emphasis> Enable the
+            <emphasis>vectorisation</emphasis> avoidance optimisation. This
+            optimisation only works when used in combination with the
+            <option>-fvectorise</option> transformation.</para>
+
+            <para>While vectorisation of code using DPH is often a big win, it
+            can also produce worse results for some kinds of code. This
+            optimisation modifies the vectorisation transformation to try to
+            determine if a function would be better of unvectorised and if
+            so, do just that.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>-fvectorise</option>
+            <indexterm><primary><option></option></primary></indexterm>
+          </term>
+          <listitem>
+            <para>Part of <link linkend="dph">Data Parallel Haskell
+            (DPH)</link>.</para>
+
+            <para><emphasis>Off by default.</emphasis> Enable the
+            <emphasis>vectorisation</emphasis> optimisation transformation. This
+            optimisation transforms the nested data parallelism code of programs
+            using DPH into flat data parallelism. Flat data parallel programs
+            should have better load balancing, enable SIMD parallelism and
+            friendlier cache behaviour.</para>
+          </listitem>
+        </varlistentry>
+
       </variablelist>
 
     </sect2>
index ef6644d..67fc630 100644 (file)
@@ -12,11 +12,11 @@ Should fail, GADTs is not enabled
 options currently set: none.
 base language is: Haskell2010
 with the following modifiers:
-  -XGADTs
-  -XGADTSyntax
   -XNoDatatypeContexts
-  -XNondecreasingIndentation
+  -XGADTSyntax
+  -XGADTs
   -XMonoLocalBinds
+  -XNondecreasingIndentation
 GHCi-specific dynamic flag settings:
 other dynamic, non-language, flag settings:
   -fno-ghci-history
@@ -26,10 +26,10 @@ Should work, GADTs is in force from :set
 options currently set: none.
 base language is: Haskell2010
 with the following modifiers:
-  -XGADTSyntax
   -XNoDatatypeContexts
-  -XNondecreasingIndentation
+  -XGADTSyntax
   -XMonoLocalBinds
+  -XNondecreasingIndentation
 GHCi-specific dynamic flag settings:
 other dynamic, non-language, flag settings:
   -fno-ghci-history
@@ -38,13 +38,13 @@ warning settings:
 Should fail, GADTs is now disabled
 base language is: Haskell2010
 with the following modifiers:
-  -XGADTs
+  -XNoDatatypeContexts
+  -XExtendedDefaultRules
   -XGADTSyntax
+  -XGADTs
+  -XMonoLocalBinds
   -XNoMonomorphismRestriction
-  -XNoDatatypeContexts
   -XNondecreasingIndentation
-  -XMonoLocalBinds
-  -XExtendedDefaultRules
 GHCi-specific dynamic flag settings:
 other dynamic, non-language, flag settings:
   -fno-ghci-history