On Mon, 28 Apr 2025, Sam James wrote:
> 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
> ^^^^
> ,
>
Fixed.
> 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.
Jakub, are the var-tracking -O0 vs. -On bits accurate?
Richard.
--
Richard Biener <rguent...@suse.de>
SUSE Software Solutions Germany GmbH,
Frankenstrasse 146, 90461 Nuernberg, Germany;
GF: Ivo Totev, Andrew McDonald, Werner Knoblich; (HRB 36809, AG Nuernberg)
