Document GHC Optimisation Passes

[dterei]

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

[simonpj]

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

[dterei]

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

• 4.19 (reference table)
• 4.10 (longer description)

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.

[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-*'.

[davidterei@…]

commit d8a30633a60ee9f1e8cf6ffe48bbd672331f9096

Author: David Terei <davidterei@gmail.com>
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(-)

[davidterei@…]

commit 3c66252b3d7e2a3bcd887497eaea48c03200d126

Author: David Terei <davidterei@gmail.com>
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(-)

[simonpj]

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

[simonpj]

commit 4caef1c42dd5b6e4982e7f07162c9a7edc5a1b0b
Author: Simon Peyton Jones <simonpj@microsoft.com>
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(-)

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

[dterei]

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