diff options
author | Patrick Dougherty <patrick.doc@ameritech.net> | 2017-07-23 12:55:37 -0400 |
---|---|---|
committer | Ben Gamari <ben@smart-cactus.org> | 2017-07-23 15:47:21 -0400 |
commit | 44b090be9a6d0165e2281542a7c713da1799e885 (patch) | |
tree | 51bc316cb5a86810efbbe3ee606b9cdf8a82cd6e /docs/users_guide/using-optimisation.rst | |
parent | d4e97212fdcb6127d750577aa7f2d709fee27d56 (diff) | |
download | haskell-44b090be9a6d0165e2281542a7c713da1799e885.tar.gz |
users-guide: Standardize and repair all flag references
This patch does three things:
1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.
2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.
3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.
Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.
Reviewers: austin, bgamari
Reviewed By: bgamari
Subscribers: rwbarton, thomie
GHC Trac Issues: #13980
Differential Revision: https://phabricator.haskell.org/D3778
Diffstat (limited to 'docs/users_guide/using-optimisation.rst')
-rw-r--r-- | docs/users_guide/using-optimisation.rst | 55 |
1 files changed, 29 insertions, 26 deletions
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index 185e590534..15916b2690 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -171,9 +171,11 @@ by saying ``-fno-wombat``. to their usage sites. It also inlines simple expressions like literals or registers. -.. ghc-flag:: -fcpr-off +.. ghc-flag:: -fcpr-anal - Switch off CPR analysis in the demand analyser. + :default: on + + Turn on CPR analysis in the demand analyser. .. ghc-flag:: -fcse @@ -343,7 +345,7 @@ by saying ``-fno-wombat``. a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for free variables rather than arguments. -.. ghc-flag:: -fliberate-case-threshold=<n> +.. ghc-flag:: -fliberate-case-threshold=⟨n⟩ :default: 2000 @@ -357,7 +359,7 @@ by saying ``-fno-wombat``. self-recursive saturated tail calls into local jumps rather than function calls. -.. ghc-flag:: -fmax-inline-alloc-size=<n> +.. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩ :default: 128 @@ -366,20 +368,20 @@ by saying ``-fno-wombat``. 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). -.. ghc-flag:: -fmax-inline-memcpy-insn=<n> +.. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩ :default: 32 Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions. -.. ghc-flag:: -fmax-inline-memset-insns=<n> +.. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩ :default: 32 Inline ``memset`` calls if they would generate no more than n pseudo instructions. -.. ghc-flag:: -fmax-relevant-binds=<n> +.. ghc-flag:: -fmax-relevant-binds=⟨n⟩ -fno-max-relevant-bindings :default: 6 @@ -392,7 +394,7 @@ by saying ``-fno-wombat``. they may be numerous), but ``-fno-max-relevant-bindings`` includes them too. -.. ghc-flag:: -fmax-valid-substitutions=<n> +.. ghc-flag:: -fmax-valid-substitutions=⟨n⟩ -fno-max-valid-substitutions :default: 6 @@ -402,20 +404,20 @@ by saying ``-fno-wombat``. set by this flag. Turning it off with ``-fno-max-valid-substitutions`` gives an unlimited number. -.. ghc-flag:: -fmax-uncovered-patterns=<n> +.. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩ :default: 4 Maximum number of unmatched patterns to be shown in warnings generated by :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`. -.. ghc-flag:: -fmax-simplifier-iterations=<n> +.. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩ :default: 4 Sets the maximal number of iterations for the simplifier. -.. ghc-flag:: -fmax-worker-args=<n> +.. ghc-flag:: -fmax-worker-args=⟨n⟩ :default: 10 @@ -497,13 +499,13 @@ by saying ``-fno-wombat``. as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing during register allocation. -.. ghc-flag:: -fsimplifier-phases=<n> +.. ghc-flag:: -fsimplifier-phases=⟨n⟩ :default: 2 Set the number of phases for the simplifier. Ignored with ``-O0``. -.. ghc-flag:: -fsimpl-tick-factor=<n> +.. ghc-flag:: -fsimpl-tick-factor=⟨n⟩ :default: 100 @@ -597,14 +599,14 @@ by saying ``-fno-wombat``. beneficial; e.g. the argument might be given to some other function that can itself be specialised. -.. ghc-flag:: -fspec-constr-count=<n> +.. ghc-flag:: -fspec-constr-count=⟨n⟩ :default: 3 Set the maximum number of specialisations that will be created for any one function by the SpecConstr transformation. -.. ghc-flag:: -fspec-constr-threshold=<n> +.. ghc-flag:: -fspec-constr-threshold=⟨n⟩ :default: 2000 @@ -757,7 +759,7 @@ by saying ``-fno-wombat``. Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only unbox strict fields which are "small". -.. ghc-flag:: -funfolding-creation-threshold=<n> +.. ghc-flag:: -funfolding-creation-threshold=⟨n⟩ :default: 750 @@ -776,11 +778,11 @@ by saying ``-fno-wombat``. 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. - Increasing this figure is more likely to result in longer compile - times than faster code. The :ghc-flag:`-funfolding-use-threshold` is more + Increasing this figure is more likely to result in longer compile times + than faster code. The :ghc-flag:`-funfolding-use-threshold=⟨n⟩` is more useful. -.. ghc-flag:: -funfolding-dict-discount=<n> +.. ghc-flag:: -funfolding-dict-discount=⟨n⟩ :default: 30 @@ -790,7 +792,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline dictionaries? -.. ghc-flag:: -funfolding-fun-discount=<n> +.. ghc-flag:: -funfolding-fun-discount=⟨n⟩ :default: 60 @@ -800,7 +802,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? -.. ghc-flag:: -funfolding-keeness-factor=<n> +.. ghc-flag:: -funfolding-keeness-factor=⟨n⟩ :default: 1.5 @@ -810,7 +812,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? -.. ghc-flag:: -funfolding-use-threshold=<n> +.. ghc-flag:: -funfolding-use-threshold=⟨n⟩ :default: 60 @@ -825,10 +827,11 @@ by saying ``-fno-wombat``. minus any discounts that apply depending on the context into which the expression is to be inlined. - The difference between this and :ghc-flag:`-funfolding-creation-threshold` - is that this one determines if a function definition will be inlined - *at a call site*. The other option determines if a function - definition will be kept around at all for potential inlining. + The difference between this and + :ghc-flag:`-funfolding-creation-threshold=⟨n⟩` is that this one determines + if a function definition will be inlined *at a call site*. The other option + determines if a function definition will be kept around at all for + potential inlining. .. ghc-flag:: -fvectorisation-avoidance |