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.
>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
+@option{-fvar-tracking} which handle debug information in the prologue
+and epilogue of functions better than @option{-O0}.
-Like @option{-O0}, @option{-Og} completely disables a number of
+Like @option{-O0}, @option{-Og} completely skips a number of
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:
@gccoptlist{-fbranch-count-reg -fdelayed-branch
-fdse -fif-conversion -fif-conversion2
--
2.43.0
