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

[Alexander Monakov]

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?

Thanks.
Alexander

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

[Martin Sebor]

On 11/05/2015 10:10 AM, Joseph Myers wrote:

On Thu, 5 Nov 2015, Martin Sebor wrote:


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.


There are several options marked Optimization that are actually matters of
language semantics that I don't think have anything to do with -O options,
e.g. -fexceptions and -fcx-limited-range.  The Optimization tag really
just means that it's saved and restored under certain circumstances.


Both -fexceptions and -fcx-limited-range are reported as disabled
at -O0, so they're not the examples I'm looking for. The set of
options that are reported as disabled by -O0 with the patched GCC
and that, IIUC, are of concern (i.e., that may not need -O to take
effect) are a subset of those below.

Quickly scanning the list, I would guess -frtti, -fshort-enums,
-fsigned-zeros, and -frtapping-math should be in that category,
but there could very well be others.

If it's relatively straightforward to enumerate all such options
then maybe the way to go is to add a bit to struct cl_option to
make it possible to distinguish them from the others in the -O0
-Q --help=optimizers output.

Thanks
Martin

  -faggressive-loop-optimizations   [disabled by -O0]
  -fasynchronous-unwind-tables  [disabled by -O0]
  -fauto-inc-dec[disabled by -O0]
  -fdce [disabled by -O0]
  -fdelete-null-pointer-checks  [disabled by -O0]
  -fdse [disabled by -O0]
  -fearly-inlining  [disabled by -O0]
  -ffunction-cse[disabled by -O0]
  -fgcse-lm [disabled by -O0]
  -finline  [disabled by -O0]
  -finline-atomics  [disabled by -O0]
  -fira-hoist-pressure  [disabled by -O0]
  -fira-share-save-slots[disabled by -O0]
  -fira-share-spill-slots   [disabled by -O0]
  -fivopts  [disabled by -O0]
  -fjump-tables [disabled by -O0]
  -flifetime-dse[disabled by -O0]
  -fmath-errno  [disabled by -O0]
  -fpeephole[disabled by -O0]
  -fplt [disabled by -O0]
  -fprefetch-loop-arrays[disabled by -O0]
  -frename-registers[disabled by -O0]
  -frtti[disabled by -O0]
  -fsched-critical-path-heuristic   [disabled by -O0]
  -fsched-dep-count-heuristic   [disabled by -O0]
  -fsched-group-heuristic   [disabled by -O0]
  -fsched-interblock[disabled by -O0]
  -fsched-last-insn-heuristic   [disabled by -O0]
  -fsched-rank-heuristic[disabled by -O0]
  -fsched-spec  [disabled by -O0]
  -fsched-spec-insn-heuristic   [disabled by -O0]
  -fsched-stalled-insns-dep [disabled by -O0]
  -fschedule-fusion [disabled by -O0]
  -fshort-enums [disabled by -O0]
  -fsigned-zeros[disabled by -O0]
  -fsplit-ivs-in-unroller   [disabled by -O0]
  -fssa-backprop[disabled by -O0]
  -fstdarg-opt  [disabled by -O0]
  -fstrict-volatile-bitfields   [disabled by -O0]
  -fno-threadsafe-statics   [disabled by -O0]
  -ftrapping-math   [disabled by -O0]
  -ftree-cselim [disabled by -O0]
  -ftree-forwprop   [disabled by -O0]
  -ftree-loop-if-convert[disabled by -O0]
  -ftree-loop-im[disabled by -O0]
  -ftree-loop-ivcanon   [disabled by -O0]
  -ftree-loop-optimize  [disabled by -O0]
  -ftree-phiprop[disabled by -O0]
  -ftree-reassoc[disabled by -O0]
  -ftree-scev-cprop [disabled by -O0]
  -fvar-tracking[disabled by -O0]
  -fvar-tracking-assignments[disabled by -O0]
  -fweb [disabled by -O0]

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

[Joseph Myers]

On Thu, 5 Nov 2015, Martin Sebor wrote:

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

There are several options marked Optimization that are actually matters of 
language semantics that I don't think have anything to do with -O options, 
e.g. -fexceptions and -fcx-limited-range.  The Optimization tag really 
just means that it's saved and restored under certain circumstances.

-- 
Joseph S. Myers
jos...@codesourcery.com

Re: [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

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

[Segher Boessenkool]

On Thu, Nov 05, 2015 at 08:58:25AM -0700, Martin Sebor wrote:
> 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.

The -Q --help* output is primarily aimed at GCC developers, just
like plain -Q is.  The main problem here seems to be that the
documentation pushes beginner GCC users to use this.

Perhaps we should have a higher-level, more easy to use way to query
what flags will do what, possibly integrated with the pass manager.

> Those who are in doubt and
> ask on gcc-help are then told by GCC experts that -O0 disables
> all optimizations without exception,

And it does, for the plain meaning of "optimization"; anything else
is arguably a bug.  But people have many different understandings
of what a "compiler optimization" is, all the way to "anything the
compiler does".


Segher

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

[Joseph Myers]

On Thu, 5 Nov 2015, Martin Sebor wrote:

> Yes, I agree that printing "disabled by -O0" when -fexceptions is
> explicitly enabled on the command line is not right if the option
> isn't actually affected by -O0. This would be prevented if we knew
> which of the -fxxx options are or aren't controlled by -O0. Can you
> help identify them?

I don't think there's any simple way to do so; it requires checking all 
the "if (optimize)" conditions to see what is or is not conditioned that 
way.

-- 
Joseph S. Myers
jos...@codesourcery.com

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

[Martin Sebor]

On 11/05/2015 11:07 AM, Joseph Myers wrote:

On Thu, 5 Nov 2015, Martin Sebor wrote:


There are several options marked Optimization that are actually matters of
language semantics that I don't think have anything to do with -O options,
e.g. -fexceptions and -fcx-limited-range.  The Optimization tag really
just means that it's saved and restored under certain circumstances.


Both -fexceptions and -fcx-limited-range are reported as disabled
at -O0, so they're not the examples I'm looking for. The set of


But reporting that is nonsense.


What I said (meant) was that they are reported as "[disabled]" when
-O0 is used (and they are not explicitly enabled on the command line).
It took me a while to see that you're talking about something slightly
different.


They are disabled by default for C.  If
you pass the option on the command line, it's enabled regardless of -O
options, and should not be reported as disabled.


Yes, I agree that printing "disabled by -O0" when -fexceptions is
explicitly enabled on the command line is not right if the option
isn't actually affected by -O0. This would be prevented if we knew
which of the -fxxx options are or aren't controlled by -O0. Can you
help identify them?

Martin

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

[Joseph Myers]

On Thu, 5 Nov 2015, Martin Sebor wrote:

> > There are several options marked Optimization that are actually matters of
> > language semantics that I don't think have anything to do with -O options,
> > e.g. -fexceptions and -fcx-limited-range.  The Optimization tag really
> > just means that it's saved and restored under certain circumstances.
> 
> Both -fexceptions and -fcx-limited-range are reported as disabled
> at -O0, so they're not the examples I'm looking for. The set of

But reporting that is nonsense.  They are disabled by default for C.  If 
you pass the option on the command line, it's enabled regardless of -O 
options, and should not be reported as disabled.

-- 
Joseph S. Myers
jos...@codesourcery.com

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

[Martin Sebor]

On 11/05/2015 10:09 AM, Segher Boessenkool wrote:

On Thu, Nov 05, 2015 at 08:58:25AM -0700, Martin Sebor wrote:

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.


The -Q --help* output is primarily aimed at GCC developers, just
like plain -Q is.  The main problem here seems to be that the
documentation pushes beginner GCC users to use this.

Perhaps we should have a higher-level, more easy to use way to query
what flags will do what, possibly integrated with the pass manager.


I think that would be ideal (i.e., hiding each flag_xxx under
a get_flag_xxx() and set_flag_xxx() interface that would make
it possible to compute and dynamically query individual option
settings based on non-trivial dependencies). It strikes me as
quite a project.




Those who are in doubt and
ask on gcc-help are then told by GCC experts that -O0 disables
all optimizations without exception,


And it does, for the plain meaning of "optimization"; anything else
is arguably a bug.  But people have many different understandings
of what a "compiler optimization" is, all the way to "anything the
compiler does".


Yes, that also sometimes causes confusion, though it's not something
I'm trying to solve with this patch.

Martin

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

[Segher Boessenkool]

On Thu, Nov 05, 2015 at 02:04:47PM -0700, Martin Sebor wrote:
> On 11/05/2015 10:09 AM, Segher Boessenkool wrote:
> >On Thu, Nov 05, 2015 at 08:58:25AM -0700, Martin Sebor wrote:
> >>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.
> >
> >The -Q --help* output is primarily aimed at GCC developers, just
> >like plain -Q is.  The main problem here seems to be that the
> >documentation pushes beginner GCC users to use this.
> >
> >Perhaps we should have a higher-level, more easy to use way to query
> >what flags will do what, possibly integrated with the pass manager.
> 
> I think that would be ideal (i.e., hiding each flag_xxx under
> a get_flag_xxx() and set_flag_xxx() interface that would make
> it possible to compute and dynamically query individual option
> settings based on non-trivial dependencies). It strikes me as
> quite a project.

I was thinking more of showing at every flag whether it is relevant at
all, or maybe not showing irrelevant ones except maybe when some
--verbose or so option is given; and if you want to get really fancy
(but also very helpful to both users and developers), have some option
that shows all dependencies for a flag to take effect.

This of course requires expressing some dependencies manually in the
.opt files, but hopefully most can be done automatically with some
magic.

> >>Those who are in doubt and
> >>ask on gcc-help are then told by GCC experts that -O0 disables
> >>all optimizations without exception,
> >
> >And it does, for the plain meaning of "optimization"; anything else
> >is arguably a bug.  But people have many different understandings
> >of what a "compiler optimization" is, all the way to "anything the
> >compiler does".
> 
> Yes, that also sometimes causes confusion, though it's not something
> I'm trying to solve with this patch.

It's not something you _can_ solve as far as I see.  There is a
considerable gap between what beginner and advanced users expect from
the compiler, understand about the compiler, and worst of all, think
they understand about the compiler.  GCC should be a useful compiler
to that whole spectrum of audiences.  Currently -Q --help shows just
the gory details, which is functionality we want to keep IMO, but not
something we want to recommend everyone to use.

Does that make sense?  I'm not sure I'm expressing myself well here,
you cannot see my frantic handwaving :-)


Segher

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

[Martin Sebor]

On 11/05/2015 04:30 PM, Segher Boessenkool wrote:

On Thu, Nov 05, 2015 at 02:04:47PM -0700, Martin Sebor wrote:

On 11/05/2015 10:09 AM, Segher Boessenkool wrote:

On Thu, Nov 05, 2015 at 08:58:25AM -0700, Martin Sebor wrote:

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.


The -Q --help* output is primarily aimed at GCC developers, just
like plain -Q is.  The main problem here seems to be that the
documentation pushes beginner GCC users to use this.

Perhaps we should have a higher-level, more easy to use way to query
what flags will do what, possibly integrated with the pass manager.


I think that would be ideal (i.e., hiding each flag_xxx under
a get_flag_xxx() and set_flag_xxx() interface that would make
it possible to compute and dynamically query individual option
settings based on non-trivial dependencies). It strikes me as
quite a project.


I was thinking more of showing at every flag whether it is relevant at
all, or maybe not showing irrelevant ones except maybe when some
--verbose or so option is given; and if you want to get really fancy
(but also very helpful to both users and developers), have some option
that shows all dependencies for a flag to take effect.

This of course requires expressing some dependencies manually in the
.opt files, but hopefully most can be done automatically with some
magic.


Yes, the dependencies would have to be encoded somewhere, somehow
(once they were discovered, which seems like a challenge in and
if itself). Since they could be non-trivial (one option being
enabled by several others), to be sufficiently general, the data
structure itself would need to be able to express that any given
option is can be enabled or disabled by any combination of others.




Those who are in doubt and
ask on gcc-help are then told by GCC experts that -O0 disables
all optimizations without exception,


And it does, for the plain meaning of "optimization"; anything else
is arguably a bug.  But people have many different understandings
of what a "compiler optimization" is, all the way to "anything the
compiler does".


Yes, that also sometimes causes confusion, though it's not something
I'm trying to solve with this patch.


It's not something you _can_ solve as far as I see.  There is a
considerable gap between what beginner and advanced users expect from
the compiler, understand about the compiler, and worst of all, think
they understand about the compiler.  GCC should be a useful compiler
to that whole spectrum of audiences.  Currently -Q --help shows just
the gory details, which is functionality we want to keep IMO, but not
something we want to recommend everyone to use.

Does that make sense?  I'm not sure I'm expressing myself well here,
you cannot see my frantic handwaving :-)


It does make sense (even without the handwaving, though picturing
it in my mind was a big help :) I agree that solving this bigger
problem is well beyond what can be accomplished by changing the
compiler or its documentation.

Martin

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

[Joseph Myers]

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.

-- 
Joseph S. Myers
jos...@codesourcery.com

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

[Martin Sebor]

On 11/03/2015 03:19 AM, Alexander Monakov wrote:

On Thu, 22 Oct 2015, Martin Sebor wrote:


[Sending to the right list this time]

The documentation of the -Q --help=optimizers options leads some
to expect that when options are reported as enabled imply the
corresponding optimization will take place.  (See the following
question on gcc-help:
https://gcc.gnu.org/ml/gcc-help/2015-10/msg00133.html)

The patch below tries to make it clear that that's not always
the case.


Hi,

The issue is due to optimization passes being skipped at -O0, and yet
corresponding optimization options not explicitely disabled.  The effect of -O
is an old source of confusion, and now the intro to "Optimization Options"
says,

 Most optimizations are only enabled if an -O level is set on the command
 line.  Otherwise they are disabled, even if individual optimization flags
 are specified.

(added with this patch:
https://gcc.gnu.org/ml/gcc-patches/2009-10/msg00739.html )


Thanks for the reference! Despite the improvement, this continues
to be a recurring problem. Users tend to miss the added text, maybe
because it's on a different HTML page than the --help option. That
certainly seemed to be the case in this post:

  https://gcc.gnu.org/ml/gcc-help/2015-10/msg00135.html

It's also possible that it's because the caveat is mentioned in
a context that doesn't match their use case. In the originally
referenced thread, the user wasn't looking to enable additional
optimizations. Rather, they were trying to see what (if any)
optimizations are enabled by default, with -O0.



As we observe, it's not visible enough, and I'm not sure saying that again in
the documentation (in a different section) is a good way to go.  Maybe we'd
warn for attempts to enable optimizations at -O0, but that's not trivial.
Perhaps go with Richard's suggestion in the end of this mail ("Thus, at the
end of --help-optimizers print ...")?
https://gcc.gnu.org/ml/gcc-patches/2012-05/msg00113.html


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.

The patch also further clarifies the wording in the documentation
to help users avoid falling into the trap of assuming, based on
an incomplete reading of the manual, that some optimizations are
performed even at -O0.

Martin
gcc/ChangeLog:
2015-11-04  Martin Sebor  

	* opts.c (print_filtered_help): Indicate when an optimization option
	is disabled as a result of -O0.
	* doc/invoke.texi: Further clarify the effect of -O options
	on individual optimization options.

gcc/testsuite/ChangeLog:
2015-11-04  Martin Sebor  

	* testsuite/gcc.misc-tests/help.exp: Verify that optimization options
	are printed as disabled when -O0 is specified and enabled otherwise.

Index: doc/invoke.texi
===
--- doc/invoke.texi	(revision 229716)
+++ doc/invoke.texi	(working copy)
@@ -1509,6 +1509,14 @@
 disabled or set to a specific value (assuming that the compiler
 knows this at the point where the @option{--help=} option is used).

+It's important to remember that when a given optimization option is
+enabled, either explicitly on the command line or implicitly, whether
+or not the optimization it controls will be performed during an
+invocation of the compiler may depend on other options, most commonly
+one of the @option{-O} options.  This is because many options control
+various finer aspects of other more general optimizations that must
+be enabled in order for the former option to have any effect.
+
 Here is a truncated example from the ARM port of @command{gcc}:

 @smallexample
@@ -1524,7 +1532,7 @@
 are enabled at @option{-O2} by using:

 @smallexample
--Q -O2 --help=optimizers
+  % gcc -Q -O2 --help=optimizers
 @end smallexample

 Alternatively you can discover which binary optimizations are enabled
@@ -1531,11 +1539,22 @@
 by @option{-O3} by using:

 @smallexample
-gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
-gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
-diff /tmp/O2-opts /tmp/O3-opts | grep enabled
+  % gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
+  % gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
+  % diff /tmp/O2-opts /tmp/O3-opts | grep enabled
 @end smallexample

+Finally, the following example shows the difference in output for
+an option that, while technically enabled, is disabled as a consequence
+of the implicit @option{-O0} option, and for one that is disabled by
+default.  This distinction is typically only of interest to GCC developers.
+@smallexample
+  % gcc -Q --help=optimizers
+  The following options control optimizations:
+  -faggressive-loop-optimizations 	[disabled by -O0]
+  -falign-functions   		[disabled]
+@end smallexample
+
 @item -no-canonical-prefixes
 @opindex no-canonical-prefixes
 Do not expand any 

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

[Sandra Loosemore]

On 11/04/2015 04:52 PM, Martin Sebor wrote:


gcc/ChangeLog:
2015-11-04  Martin Sebor  

* opts.c (print_filtered_help): Indicate when an optimization option
is disabled as a result of -O0.
* doc/invoke.texi: Further clarify the effect of -O options
on individual optimization options.


invoke.texi is a huge file.  In ChangeLogs, please use (node name) to 
indicate which sections have been changed unless the changes really do 
apply throughout the whole file.



@@ -1509,6 +1509,14 @@
 disabled or set to a specific value (assuming that the compiler
 knows this at the point where the @option{--help=} option is used).

+It's important to remember that when a given optimization option is
+enabled, either explicitly on the command line or implicitly, whether
+or not the optimization it controls will be performed during an


s/will be performed/is performed/


+Finally, the following example shows the difference in output for
+an option that, while technically enabled, is disabled as a consequence
+of the implicit @option{-O0} option, and for one that is disabled by
+default.  This distinction is typically only of interest to GCC developers.


If the distinction is only interesting to developers, why does it need 
an example in GCC's user documentation?  :-S


I don't have any other comments on the writing aspects of the patch, but 
others may want to comment on technical accuracy, etc.


-Sandra

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

[Martin Sebor]

On 11/04/2015 06:09 PM, Sandra Loosemore wrote:

On 11/04/2015 04:52 PM, Martin Sebor wrote:


gcc/ChangeLog:
2015-11-04  Martin Sebor  

* opts.c (print_filtered_help): Indicate when an optimization option
is disabled as a result of -O0.
* doc/invoke.texi: Further clarify the effect of -O options
on individual optimization options.


invoke.texi is a huge file.  In ChangeLogs, please use (node name) to
indicate which sections have been changed unless the changes really do
apply throughout the whole file.


@@ -1509,6 +1509,14 @@
 disabled or set to a specific value (assuming that the compiler
 knows this at the point where the @option{--help=} option is used).

+It's important to remember that when a given optimization option is
+enabled, either explicitly on the command line or implicitly, whether
+or not the optimization it controls will be performed during an


s/will be performed/is performed/


+Finally, the following example shows the difference in output for
+an option that, while technically enabled, is disabled as a consequence
+of the implicit @option{-O0} option, and for one that is disabled by
+default.  This distinction is typically only of interest to GCC
developers.


If the distinction is only interesting to developers, why does it need
an example in GCC's user documentation?  :-S


Thank you for the feedback. I'll incorporate it into the next version
of the patch.

The point of the example is to make it clear to users that despite
the different output the effect of both kinds of options on
optimization is the same (i.e., none). I made the output different
only because I expect the distinction between the state of the two
kinds of options to be of interest to GCC developers. Otherwise,
it could just say [disabled] for both.

Martin

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

[Alexander Monakov]

On Thu, 22 Oct 2015, Martin Sebor wrote:

> [Sending to the right list this time]
> 
> The documentation of the -Q --help=optimizers options leads some
> to expect that when options are reported as enabled imply the
> corresponding optimization will take place.  (See the following
> question on gcc-help:
> https://gcc.gnu.org/ml/gcc-help/2015-10/msg00133.html)
> 
> The patch below tries to make it clear that that's not always
> the case.

Hi,

The issue is due to optimization passes being skipped at -O0, and yet
corresponding optimization options not explicitely disabled.  The effect of -O
is an old source of confusion, and now the intro to "Optimization Options"
says,

Most optimizations are only enabled if an -O level is set on the command
line.  Otherwise they are disabled, even if individual optimization flags
are specified.

(added with this patch:
https://gcc.gnu.org/ml/gcc-patches/2009-10/msg00739.html )

As we observe, it's not visible enough, and I'm not sure saying that again in
the documentation (in a different section) is a good way to go.  Maybe we'd
warn for attempts to enable optimizations at -O0, but that's not trivial.
Perhaps go with Richard's suggestion in the end of this mail ("Thus, at the
end of --help-optimizers print ...")?
https://gcc.gnu.org/ml/gcc-patches/2012-05/msg00113.html

Thanks.
Alexander

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

[Martin Sebor]

Ping. Thanks in advance for a review.

On 10/22/2015 08:12 PM, Martin Sebor wrote:

[Sending to the right list this time]

The documentation of the -Q --help=optimizers options leads some
to expect that when options are reported as enabled imply the
corresponding optimization will take place.  (See the following
question on gcc-help:
https://gcc.gnu.org/ml/gcc-help/2015-10/msg00133.html)

The patch below tries to make it clear that that's not always
the case.

Martin

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4f89fa1..337639e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1506,6 +1506,16 @@ options, an indication is given as to whether the
option is enabled,
  disabled or set to a specific value (assuming that the compiler
  knows this at the point where the @option{--help=} option is used).

+It's important to note that when a given optimization option is
+enabled, either explicitly on the command line or implicitly, whether
+or not the optimization it controls will be performed during an
+invocation of the compiler may depend on other options.  This is
+so because many options control various finer aspects of other more
+general optimizations that must be enabled in order for the former
+option to have any effect.  There is currently no command line
+interface to determine such dependencies between optimization
+options.
+
  Here is a truncated example from the ARM port of @command{gcc}:

  @smallexample

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

[Martin Sebor]

[Sending to the right list this time]

The documentation of the -Q --help=optimizers options leads some
to expect that when options are reported as enabled imply the
corresponding optimization will take place.  (See the following
question on gcc-help:
https://gcc.gnu.org/ml/gcc-help/2015-10/msg00133.html)

The patch below tries to make it clear that that's not always
the case.

Martin

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4f89fa1..337639e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1506,6 +1506,16 @@ options, an indication is given as to whether the
option is enabled,
 disabled or set to a specific value (assuming that the compiler
 knows this at the point where the @option{--help=} option is used).

+It's important to note that when a given optimization option is
+enabled, either explicitly on the command line or implicitly, whether
+or not the optimization it controls will be performed during an
+invocation of the compiler may depend on other options.  This is
+so because many options control various finer aspects of other more
+general optimizations that must be enabled in order for the former
+option to have any effect.  There is currently no command line
+interface to determine such dependencies between optimization
+options.
+
 Here is a truncated example from the ARM port of @command{gcc}:

 @smallexample