Opened 5 years ago

Last modified 3 years ago

#9358 new bug

Improve flag description in the user guide

Reported by: jstolarek Owned by:
Priority: normal Milestone:
Component: Documentation Version: 7.8.3
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Test Case:
Blocked By: Blocking:
Related Tickets: #1880 Differential Rev(s): Phab:D444
Wiki Page:

Description (last modified by jstolarek)

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.

Change History (25)

comment:1 Changed 5 years ago by simonpj

Good points.

Would someone be willing to make a patch? Not a difficult task. Thanks!

Simon

comment:2 Changed 5 years ago 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

comment:3 Changed 5 years ago 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.

comment:4 Changed 5 years ago by jstolarek

Priority: lownormal

-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.

comment:5 Changed 5 years ago by simonpj

Excellent -- would you feel able to submit a patch? Thanks!

comment:6 Changed 5 years ago 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.

comment:7 Changed 5 years ago 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

comment:8 Changed 5 years ago by jstolarek

-flate-dmd-anal description in 4.10.2 has incorrect link to the Trac wiki page.

comment:9 Changed 5 years ago 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.

comment:10 Changed 5 years ago by jstolarek

-Odph is not listed in the flag reference section.

comment:11 Changed 4 years ago by thomie

comment:12 Changed 4 years ago by jstolarek

-ddump-simpl-phases and -ddump-core-pipeline look like a no-op. Investigate.

Last edited 4 years ago by jstolarek (previous) (diff)

comment:13 Changed 4 years ago by jstolarek

-funbox-strict-fields is enabled with -O and -O2, which is not mentioned in 4.20

comment:14 Changed 4 years ago 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!

comment:15 Changed 4 years ago by jstolarek

Owner: set to jstolarek

comment:16 Changed 4 years ago by jstolarek

Note to self: document -fllvm-pass-vectors-in-regs and fllvm-tbaa

comment:17 Changed 4 years ago 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.

comment:18 Changed 4 years ago 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

comment:19 Changed 4 years ago 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

comment:20 Changed 4 years ago by jstolarek

Differential Rev(s): Phab:D444

comment:21 Changed 4 years ago by jstolarek

Resolution: fixed
Status: newclosed

The main chunk of work on this has been done in 303776ab1ff8e192fe42374c8547b7c77305796e

There is still some work to do as described on ghc-devs. Nevertheless I'm closing this ticket as fixed because issues raised here have been addressed.

comment:22 Changed 4 years ago by jstolarek

Description: modified (diff)
Owner: jstolarek deleted
Resolution: fixed
Status: closednew

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.

comment:23 Changed 4 years ago by thoughtpolice

Milestone: 7.10.17.12.1

Moving to 7.12.1 milestone; if you feel this is an error and should be addressed sooner, please move it back to the 7.10.1 milestone.

comment:24 Changed 3 years ago by thoughtpolice

Milestone: 7.12.18.0.1

Milestone renamed

comment:25 Changed 3 years ago by thomie

Milestone: 8.0.1
Note: See TracTickets for help on using tickets.