[GHC] #9358: Improve flag description in the user guide
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: low | Milestone: 7.10.1 Component: Documentation | Version: 7.8.3 Keywords: | Operating System: Architecture: Unknown/Multiple | Unknown/Multiple Difficulty: Easy (less than 1 | Type of failure: hour) | Documentation bug Blocked By: | Test Case: Related Tickets: | Blocking: | Differential Revisions: -------------------------------------+------------------------------------- Sections 4.20 (Flag reference) and 4.10.2 (-f*: platform-independent flags) of the User Guide could use some updating: - `-floopification` is mentioned in 4.20 but not in 4.10.2 (which, sadly, is my fault), - Section 4.10.2 says: "These flags turn on and off individual optimisations. They are normally set via the -O options (...) The flags below are off by default, except where noted below." Does the last sentence mean they are on by default for `-O` or that they are enabled even with `-O0` (which is the default optimisation level)? - What is the default value of `-fmax-simplifier-iterations`? - 4.20 mentions `-fmax-simplifier-iterations`, `-fmax-relevant-bindings` and `-fmax-worker-args` but only the first one is described in 4.10.2 I suspect there are more inconsistencies. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: low | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by simonpj): Good points. Would someone be willing to make a patch? Not a difficult task. Thanks! Simon -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: low | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): I just checked the source code and `-fmax-simplifier-iterations` default value is 4. Using `-Odph` bumps it to 20. Another issue: - Both 4.20 and 4.20.1 mention the incorrect `-fmax-relevant-bindings` flag name. The correct is `-fmax-relevant-binds` -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: low | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): From ghc-devs: jstolarek:
How can I observe the effects of `-ddump-simpl-phases`? I tried compiling several different programs and this flag seems to have no effect (ie. nothing gets printed).
simonpj:
I had to read the source code. I think you say "-ddump-simpl-phases=A,B,C" to dump the output of phases called A,B,C. But no, it seems that it only affects output of simplifier statistics (see simplifyPgmIO). I have never used this flag. Maybe it can go. Looks strange to me.
-- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Changes (by jstolarek): * priority: low => normal Comment: `-fstatic-argument-transformation` description in 4.20.15 says it is implied by `-O2` but that is not the case. It looks like these two sections of the user guide really need updating - bumping priority. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by simonpj): Excellent -- would you feel able to submit a patch? Thanks! -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): If no one steps up then I'll probably do it before 7.10 gets released. This is a simple thing to fix but I estimate that checking all the flags and fixing their descriptions is about 4 hours of work. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-frule-check` flag is not described at all. Here's an excerpt from `Rules.lhs`: {{{ We want to know what sites have rules that could have fired but didn't. This pass runs over the tree (without changing it) and reports such. \begin{code} -- | Report partial matches for rules beginning with the specified -- string for the purposes of error reporting }}} -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:7 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-flate-dmd-anal` description in 4.10.2 has incorrect link to the Trac wiki page. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:8 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-fdo-lambda-eta-expansion` description in 4.20.15 says: "Enable lambda eta-reduction". Obviously, it does the opposite. Ugh... what a mess. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:9 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-Odph` is not listed in the flag reference section. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:10 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Changes (by thomie): * related: => #1880 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:11 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-ddump-simpl-phases` and `-ddump-simpl-phases` look like a no-op. Investigate. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:12 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): `-funbox-strict-fields` is enabled with `-O` and `-O2`, which is not mentioned in 4.20 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:13 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by simonpj): Jan, you said you'd be willing to do this updating before 7.10 which would be excellent. So far as I can see, there simply is no list of what is enabled by -O or -O2. I'm not sure if there should be. It's more than a simple on/off thing because the order matters. Almost anything would be an improvement! -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:14 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Changes (by jstolarek): * owner: => jstolarek -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:15 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): Note to self: document `-fllvm-pass-vectors-in-regs` and `fllvm-tbaa` -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:16 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): Note to self: `-msse4.2` mentioned in the section 4.16 seems to have been removed. There are also some new flags added by Geoffrey: `-mavx2`, `-mavx512cd`, `-mavx512er`, `-mavx512f` and `-mavx512pf`. I'm unable to document these, need to ask Geoffrey. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:17 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by carter): @jan, the -mavx2 and -mavx512* flags are currently unused in practice. They SHOULD NOT be documented in a user facing way till they actually do anything meaningful. Which they currently dont in practice. wrt -msse4.2, austin has generalized things so that GHC now has proper -march etc style flags afaict, the msse4.2 stuff should be there afaik -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:18 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: | -------------------------------------+------------------------------------- Comment (by jstolarek): Carter: thanks. Indeed, `-msse4.2` is still there, it's just that auto- completion doesn't show it for some reason. Note to self: ask Nicolas Frisby about `-fdmd-tx-dict-sel` -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:19 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: Phab:D444 | -------------------------------------+------------------------------------- Changes (by jstolarek): * differential: => Phab:D444 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:20 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: jstolarek Type: bug | Status: closed Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: fixed | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: Phab:D444 | -------------------------------------+------------------------------------- Changes (by jstolarek): * status: new => closed * resolution: => fixed Comment: The main chunk of work on this has been done in 303776ab1ff8e192fe42374c8547b7c77305796e There is still some work to do [https://www.haskell.org/pipermail/ghc- devs/2014-November/007169.html as described on ghc-devs]. Nevertheless I'm closing this ticket as fixed because issues raised here have been addressed. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:21 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#9358: Improve flag description in the user guide -------------------------------------+------------------------------------- Reporter: jstolarek | Owner: Type: bug | Status: new Priority: normal | Milestone: 7.10.1 Component: | Version: 7.8.3 Documentation | Keywords: Resolution: | Architecture: Unknown/Multiple Operating System: | Difficulty: Easy (less than 1 Unknown/Multiple | hour) Type of failure: | Blocked By: Documentation bug | Related Tickets: #1880 Test Case: | Blocking: | Differential Revisions: Phab:D444 | -------------------------------------+------------------------------------- Changes (by jstolarek): * owner: jstolarek => * status: closed => new * resolution: fixed => Old description:
Sections 4.20 (Flag reference) and 4.10.2 (-f*: platform-independent flags) of the User Guide could use some updating:
- `-floopification` is mentioned in 4.20 but not in 4.10.2 (which, sadly, is my fault), - Section 4.10.2 says: "These flags turn on and off individual optimisations. They are normally set via the -O options (...) The flags below are off by default, except where noted below." Does the last sentence mean they are on by default for `-O` or that they are enabled even with `-O0` (which is the default optimisation level)? - What is the default value of `-fmax-simplifier-iterations`? - 4.20 mentions `-fmax-simplifier-iterations`, `-fmax-relevant- bindings` and `-fmax-worker-args` but only the first one is described in 4.10.2
I suspect there are more inconsistencies.
New description: These flags are currently completely missing from the User's Guide: -fbuilding-cabal-package -fflat-cache -fhpc-no-auto -fkill-absence -fkill-one-shot -fsimple-list-literals -fspecialise-aggressively -fuse-rpaths -fspec-constr-recursive -ffloat-lam-args -ffloat-all-lams If you can provide description for any of these flags please edit flags.xml and using.xml. Following flags are listed in Flag Reference section (4.19) with a brief one sentence description but they don't have a detailed description in section 4.10 (using.xml): -fcall-arity -funfolding-fun-discount -funfolding-dict-discount -funfolding-keeness-factor -frule-check (see #9776) Following flags have a detailed description but it is confusing: -fdo-eta-reduction -fdo-lambda-eta-expansion Following flags have a description but it is too brief. We should have more details: -fdicts-cheap -fdicts-strict -fdmd-tx-dict-sel -fmax-inline-memcpy-insns -fmax-inline-memset-insns -fmax-worker-args -fno-opt-coercion -fno-pre-inlining -fsimplifier-phases -fspec-constr-threshold -fspec-constr-count -fstrictness-before For these flags Flag Reference section provides the description of their -fno-* version: -fembed-manifest -fgen-manifest -fghci-history -fghci-sandbox -fpre-inlining -fprint-bind-contents -fprof-count-entries -fshared-implib This seems to go against our convention of describing the flags. Should we revert to desribing their normal version (ie. ones that enable something, not disable)? We should also make sure that documentation of remaining flags is up to date, especially the -d* ones. -- Comment: After some thought perhaps it's not a good idea to close this ticket. I'm changing the description to contain a list of flags to document and reopening. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/9358#comment:22 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC