Richard Biener <rguent...@suse.de> writes:
> On Mon, 28 Apr 2025, Alexander Monakov wrote:
>
>>
>> On Mon, 28 Apr 2025, Richard Biener wrote:
>>
>> > The following rewords the documentation for -Og which over-promises
>> > the ability to debug the generated code. While -Og enables
>> > var-tracking and thus improves debugging in some areas the experience
>> > is usually worse than -O0 for standard C code.
>> >
>> > Any other comments/clarifications? OK?
>> >
>> > Thanks,
>> > Richard.
>> >
>> > PR debug/78685
>> > * doc/invoke.texi (-Og): Reword.
>> > ---
>> > gcc/doc/invoke.texi | 14 ++++++++------
>> > 1 file changed, 8 insertions(+), 6 deletions(-)
>> >
>> > diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> > index 7fcf7dee497..7945bacb1ae 100644
>> > --- a/gcc/doc/invoke.texi
>> > +++ b/gcc/doc/invoke.texi
>> > @@ -12888,17 +12888,19 @@ It turns off @option{-fsemantic-interposition}.
>> >
>> > @opindex Og
>> > @item -Og
>> > -Optimize debugging experience. @option{-Og} should be the optimization
>> > +Optimize while keeping in mind debugging experience.
>> > +@option{-Og} should be the optimization
>> > level of choice for the standard edit-compile-debug cycle, offering
>> > -a reasonable level of optimization while maintaining fast compilation
>> > -and a good debugging experience. It is a better choice than @option{-O0}
>> > -for producing debuggable code because some compiler passes
>> > -that collect debug information are disabled at @option{-O0}.
>> > +a reasonable blend of optimization, fast compilation and debugging
>> > experience
>> > +especially for code with a high abstraction penalty. Ontop of
>> > @option{-O0}
>>
>> Typo: "On top" (missing space), but I wonder if "On top of" can be changed to
>> "In contrast to", I assume we don't want to say that -Og is -O0 plus
>> something.
>
> Agreed. We don't want to suggest that -O0 -fvar-tracking is a thing.
>
>> > +this enables @option{-fvar-tracking-assignments} and
>> > @option{-fvar-tracking}
>> > +which handles debug information in the prologue and epilogue of functions
>>
>> "which handle" (plural)?
>
> Fixed.
>
>> > +better than @option{-O0}.
>> >
>> > Like @option{-O0}, @option{-Og} completely disables a number of
>>
>> For me, "completely skips" would be clearer here than "… disables …".
>
> OK.
>
>> > optimization passes so that individual options controlling them have
>> > no effect. Otherwise @option{-Og} enables all @option{-O1}
>> > -optimization flags except for those that may interfere with debugging:
>> > +optimization flags except for those known to greatly interfere with
>> > debugging:
>
> New version below.
>
> Richard.
>
LGTM with some grammar nits:
>
> From edfa25350c949acfd50954a5178cec8722b32444 Mon Sep 17 00:00:00 2001
> From: Richard Biener <rguent...@suse.de>
> Date: Mon, 28 Apr 2025 13:31:16 +0200
> Subject: [PATCH] debug/78685 - reword -Og documentation
> To: gcc-patches@gcc.gnu.org
>
> The following rewords the documentation for -Og which over-promises
> the ability to debug the generated code. While -Og enables
> var-tracking and thus improves debugging in some areas the experience
> is usually worse than -O0 for standard C code.
>
> PR debug/78685
> * doc/invoke.texi (-Og): Reword.
> ---
> gcc/doc/invoke.texi | 16 +++++++++-------
> 1 file changed, 9 insertions(+), 7 deletions(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 7fcf7dee497..6f2d94fc2a0 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -12888,17 +12888,19 @@ It turns off @option{-fsemantic-interposition}.
>
> @opindex Og
> @item -Og
> -Optimize debugging experience. @option{-Og} should be the optimization
> +Optimize while keeping in mind debugging experience.
> +@option{-Og} should be the optimization
> level of choice for the standard edit-compile-debug cycle, offering
> -a reasonable level of optimization while maintaining fast compilation
> -and a good debugging experience. It is a better choice than @option{-O0}
> -for producing debuggable code because some compiler passes
> -that collect debug information are disabled at @option{-O0}.
> +a reasonable blend of optimization, fast compilation and debugging
^^^^
,
> experience
> +especially for code with a high abstraction penalty. In contrast to
> +@option{-O0} this enables @option{-fvar-tracking-assignments} and
^^^^
,
I think the new version is far more honest. It's been bothering me for a
bit but couldn't figure out the right phrasing to edit. Thanks.
