[PATCH] clarify documentation of -Q --help=optimizers

[Martin Sebor]

On 11/05/2015 03:48 AM, Alexander Monakov wrote:
> On Thu, 5 Nov 2015, Joseph Myers wrote:
>> On Wed, 4 Nov 2015, Martin Sebor wrote:
>>
>>> Improving the compiler output is a good idea. The attached patch
>>> prints "[disabled by -O0]" instead of "[enabled]" when an optimization
>>> option is enabled by default but when optimization (i.e., -O1 or
>>> greater) is not enabled.
>>
>> I don't think it's entirely accurate that all options marked as
>> Optimization in *.opt are actually disabled by -O0.  Many are, but it
>> depends on the actual logic controlling each optimization.
>
> Indeed, and Richard already pointed that out when reviewing (my) previous
> attempt.  Martin, please review the thread ending at
> https://gcc.gnu.org/ml/gcc-patches/2012-05/msg00113.html
>
> I guess eventually we can slightly overhaul optimization options to remove
> such ambiguities, but in short term I see no way to accurately determine
> whether a pass/option is ultimately in effect or not.
>
> Martin, what about taking Richard's suggestion, tacking a short explanatory
> sentence onto the end of --help=optimizers output?

I don't think that reiterating in a condensed form what the manual
doesn't make clear in many more words will help. First, even users
who do find the relevant text in the manual often misunderstand it.
Others are misled by the "[enabled]" output into expecting the
optimizations to take place at -O0. Those who are in doubt and
ask on gcc-help are then told by GCC experts that -O0 disables
all optimizations without exception, and to RTFM (see the thread
I referenced in my first post on this topic for an example).

That the individual optimizations -fxxx options have no effect
without -O1 or better is made clear in the FAQ on the Wiki (in
https://gcc.gnu.org/wiki/FAQ#optimization-options). What isn't
mentioned there is the relationship to the --help=optimizers
output.

I'd be happy to tweak the "disabled by -O0" text to something
less definitive if that would make you and Joseph more
comfortable. But the "enabled" output at -O0, even though
strictly correct, is a problem. Users don't care about the
internal state of the options. What they need to know is
whether or not their code may be subject to the corresponding
optimiziation. We seem to have consensus that even though there
might be exceptions (do we know what some of them are?) the vast
majority optimizations that have -fxxx options are in fact not
performed at -O0. I think reflecting that in the output is more
helpful than implying otherwise.

Martin