Opened 3 years ago

Closed 2 years ago

#5801 closed task (fixed)

Document GHC Optimisation Passes

Reported by: dterei Owned by: dterei
Priority: normal Milestone: 7.6.2
Component: Documentation Version:
Keywords: Cc: chak, benl
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Test Case:
Blocked By: Blocking:
Related Tickets: Differential Revisions:

Description

The various GHC optimisations aren't very well documented. Simply a one line description of their name:

http://www.haskell.org/ghc/docs/latest/html/users_guide/flag-reference.html#id494409

It would be nice if we documented them with an explanation of what the pass does, i.e how GCC documents their flags:

http://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html

Change History (14)

comment:1 Changed 3 years ago by simonpj

  • difficulty set to Unknown

I'm all for this. If someone feels like making the framwork, writing text where you are confident and leaving "FILL IN HERE" where you don't, I'd be happy to add some of the missing info.

Simon

comment:2 Changed 3 years ago by dterei

So at the moment in the userguide we document optimisation flags at two locations.

I think we can and should just use the existing section 4.10 for our purposes, no point in having a third location. I'll have an initial pass over the flags. Shout if you think we should document them in a different layout Simon.

comment:3 Changed 3 years ago by igloo

  • Milestone set to 7.6.1

comment:4 Changed 3 years ago by dterei

OK, I had a pass at this. The framework is in the file 'docs/users_guide/using.xml', there are a bunch of 'TODO' markers in the file to indicate what needs to be filled in. I've documented a few optimisation passes myself but many are remaining.

The other change I think we should make is that the existing documentation in that section used a mixture of positive and negative flag specification.

e.g some flags were describe as '-fno-cse' and others as '-fliberate-case'. I think we should just document the positive case and indicate at the top that you can turn all of them into negative cases with '-fno-*'.

comment:5 Changed 3 years ago by davidterei@…

commit d8a30633a60ee9f1e8cf6ffe48bbd672331f9096

Author: David Terei <[email protected]>
Date:   Fri Mar 23 11:30:05 2012 -0700

    Document some optimisations, rearrange order to be more logical (#5801)

 docs/users_guide/using.xml |  364 +++++++++++++++++++++++---------------------
 1 files changed, 193 insertions(+), 171 deletions(-)

comment:6 Changed 3 years ago by davidterei@…

commit 3c66252b3d7e2a3bcd887497eaea48c03200d126

Author: David Terei <[email protected]>
Date:   Fri Mar 23 11:10:50 2012 -0700

    Add TODO entries for missing and unexplained optimisation flags. (#5801)

 docs/users_guide/using.xml |  170 +++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 169 insertions(+), 1 deletions(-)

comment:7 Changed 3 years ago by simonpj

  • Cc chak added

Well I've taken a sweep too. Could still be improved. Remaining TODOs:

  • Manuel: Document DPH flags, at least enough to point to the details elsewhere.
  • David: document -fregs-graph and -fregs-iterative

Simon

comment:8 Changed 3 years ago by simonpj

commit 4caef1c42dd5b6e4982e7f07162c9a7edc5a1b0b
Author: Simon Peyton Jones <[email protected]>
Date:   Wed Apr 4 15:58:37 2012 +0100

    Document optimisation passes, to some extent at least

 docs/users_guide/using.xml |  131 ++++++++++++++++++++------------------------
 1 files changed, 60 insertions(+), 71 deletions(-)

comment:9 Changed 3 years ago by dterei

Awesome!

I can try to document -fregs-graph and -fregs-iterative but the most accurate / qualified person is actually Ben L, he is the one who did that work.

I'll have a stab at it if I get time but let Ben know if you talk to him.

comment:10 Changed 3 years ago by dterei

OK so more update, documented -fregs-graph and -fregs-iterative plus improved others. Just the DPH flags remain.

comment:11 Changed 3 years ago by igloo

  • Milestone changed from 7.6.1 to 7.6.2

comment:12 Changed 2 years ago by dterei

  • Cc benl added

Manuel or Ben are you able to document the DPH flags? Just -vectorise and -void-vect are remaining and then we can close this.

comment:13 Changed 2 years ago by davidterei@…

commit c0f96bdcf16866d91941802649d470176dcf9e7a

Author: David Terei <[email protected]>
Date:   Thu Jan 31 17:48:37 2013 -0800

    Document -fvectorise and -favoid-vect. (#5801)

 docs/users_guide/parallel.xml |    2 +-
 docs/users_guide/using.xml    |   28 ++++++++++++++++++++++------
 2 files changed, 23 insertions(+), 7 deletions(-)

comment:14 Changed 2 years ago by dterei

  • Resolution set to fixed
  • Status changed from new to closed

Hooray!

Note: See TracTickets for help on using tickets.