From: Eric Botcazou <ebotca...@adacore.com>
In particular the most recently added ones, namely -Og and -Oz. But -Ofast
is not documented because it disregards strict compliance with standards.
gcc/ada/ChangeLog:
* usage.adb (Usage): Justify the documentation of common switches
like that of other switches. Rework that of the -O switch.
* doc/gnat_ugn/building_executable_programs_with_gnat.rst (Compiler
switches) <-O>: Rework and document 'z' and 'g' operands.
* doc/gnat_ugn/gnat_and_program_execution.rst (Optimization Levels):
Rework and document -Oz and -Og switches.
* gnat_ugn.texi: Regenerate.
Tested on x86_64-pc-linux-gnu, committed on master.
---
...building_executable_programs_with_gnat.rst | 16 +--
.../gnat_ugn/gnat_and_program_execution.rst | 59 +++++-----
gcc/ada/gnat_ugn.texi | 101 ++++++++++++------
gcc/ada/usage.adb | 10 +-
4 files changed, 119 insertions(+), 67 deletions(-)
diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
index 4f46fba93ae..f5a9b021c4e 100644
--- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
+++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
@@ -2259,15 +2259,17 @@ Alphabetical List of All Switches
======= ==================================================================
*n* Effect
------- ------------------------------------------------------------------
- *0* No optimization, the default setting if no :switch:`-O` appears
- *1* Normal optimization, the default if you specify :switch:`-O`
without an
- operand. A good compromise between code quality and compilation
+ *0* No optimization, the default setting if no :switch:`-O` appears.
+ *1* Moderate optimization, same as :switch:`-O` without an operand.
+ A good compromise between quality of generated code and compilation
time.
- *2* Extensive optimization, may improve execution time, possibly at
+ *2* Extensive optimization, should improve execution time, possibly at
the cost of substantially increased compilation time.
- *3* Same as :switch:`-O2`, and also includes inline expansion for small
- subprograms in the same unit.
- *s* Optimize space usage
+ *3* Full optimization, may further improve execution time, possibly at
+ the cost of substantially larger generated code.
+ *s* Optimize for size (code and data) rather than speed.
+ *z* Optimize aggressively for size (code and data) rather than speed.
+ *g* Optimize for debugging experience rather than speed.
======= ==================================================================
See also :ref:`Optimization_Levels`.
diff --git a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
index 756bc74d3a3..4ecb3cf2e96 100644
--- a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
+++ b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
@@ -1584,18 +1584,16 @@ Turning on optimization makes the compiler attempt to
improve the
performance and/or code size at the expense of compilation time and
possibly the ability to debug the program.
-If you use multiple :switch:`-O` switches, with or without level
-numbers, the last such switch is the one that's used.
-
-You can use the
-:switch:`-O` switch (the permitted forms are :switch:`-O0`, :switch:`-O1`
-:switch:`-O2`, :switch:`-O3`, and :switch:`-Os`)
-to ``gcc`` to control the optimization level:
+You can pass the :switch:`-O` switch, with or without an operand
+(the permitted forms with an operand are :switch:`-O0`, :switch:`-O1`,
+:switch:`-O2`, :switch:`-O3`, :switch:`-Os`, :switch:`-Oz`, and
+:switch:`-Og`) to ``gcc`` to control the optimization level. If you
+pass multiple :switch:`-O` switches, with or without an operand,
+the last such switch is the one that's used:
* :switch:`-O0`
- No optimization (the default);
- generates unoptimized code but has
+ No optimization (the default); generates unoptimized code but has
the fastest compilation time. Debugging is easiest with this switch.
Note that many other compilers do substantial optimization even if
@@ -1606,32 +1604,45 @@ to ``gcc`` to control the optimization level:
mind when doing performance comparisons.
* :switch:`-O1`
- Moderate optimization; optimizes reasonably well but does not
- degrade compilation time significantly. You may not be able to see
- some variables in the debugger and changing the value of some
- variables in the debugger may not have the effect you desire.
+ Moderate optimization (same as :switch:`-O` without an operand);
+ optimizes reasonably well but does not degrade compilation time
+ significantly. You may not be able to see some variables in the
+ debugger, and changing the value of some variables in the debugger
+ may not have the effect you desire.
* :switch:`-O2`
- Full optimization;
- generates highly optimized code and has
- the slowest compilation time. You may see significant impacts on
+ Extensive optimization; generates highly optimized code but has
+ an increased compilation time. You may see significant impacts on
your ability to display and modify variables in the debugger.
* :switch:`-O3`
- Full optimization as in :switch:`-O2`;
- also uses more aggressive automatic inlining of subprograms within a unit
- (:ref:`Inlining_of_Subprograms`) and attempts to vectorize loops.
-
+ Full optimization; attempts more sophisticated transformations, in
+ particular on loops, possibly at the cost of larger generated code.
+ You may be hardly able to use the debugger at this optimization level.
* :switch:`-Os`
- Optimize space usage (code and data) of resulting program.
+ Optimize for size (code and data) of resulting binary rather than
+ speed; based on the :switch:`-O2` optimization level, but disables
+ some of its transformations that often increase code size, as well
+ as performs further optimizations designed to reduce code size.
+
+* :switch:`-Oz`
+ Optimize aggressively for size (code and data) of resulting binary
+ rather than speed; may increase the number of instructions executed
+ if these instructions require fewer bytes to be encoded.
+
+* :switch:`-Og`
+ Optimize for debugging experience rather than speed; based on the
+ :switch:`-O1` optimization level, but attempts to eliminate all the
+ negative effects of optimization on debugging.
+
Higher optimization levels perform more global transformations on the
program and apply more expensive analysis algorithms in order to generate
faster and more compact code. The price in compilation time, and the
-resulting improvement in execution time,
-both depend on the particular application and the hardware environment.
-You should experiment to find the best level for your application.
+resulting improvement in execution time, both depend on the particular
+application and the hardware environment. You should experiment to find
+the best level for your application.
Since the precise set of optimizations done at each level will vary from
release to release (and sometime from target to target), it is best to think
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 0a3cdb50223..9d541db6e27 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -10076,7 +10076,7 @@ Library (RTL) ALI files.
@code{n} controls the optimization level:
-@multitable {xxxxxxxxx}
{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxxxx}
{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
`n'
@@ -10091,7 +10091,7 @@ Effect
@tab
-No optimization, the default setting if no @code{-O} appears
+No optimization, the default setting if no @code{-O} appears.
@item
@@ -10099,8 +10099,8 @@ No optimization, the default setting if no @code{-O}
appears
@tab
-Normal optimization, the default if you specify @code{-O} without an
-operand. A good compromise between code quality and compilation
+Moderate optimization, same as @code{-O} without an operand.
+A good compromise between quality of generated code and compilation
time.
@item
@@ -10109,7 +10109,7 @@ time.
@tab
-Extensive optimization, may improve execution time, possibly at
+Extensive optimization, should improve execution time, possibly at
the cost of substantially increased compilation time.
@item
@@ -10118,8 +10118,8 @@ the cost of substantially increased compilation time.
@tab
-Same as @code{-O2}, and also includes inline expansion for small
-subprograms in the same unit.
+Full optimization, may further improve execution time, possibly at
+the cost of substantially larger generated code.
@item
@@ -10127,7 +10127,23 @@ subprograms in the same unit.
@tab
-Optimize space usage
+Optimize for size (code and data) rather than speed.
+
+@item
+
+`z'
+
+@tab
+
+Optimize aggressively for size (code and data) rather than speed.
+
+@item
+
+`g'
+
+@tab
+
+Optimize for debugging experience rather than speed.
@end multitable
@@ -20281,13 +20297,12 @@ Turning on optimization makes the compiler attempt to
improve the
performance and/or code size at the expense of compilation time and
possibly the ability to debug the program.
-If you use multiple @code{-O} switches, with or without level
-numbers, the last such switch is the one that’s used.
-
-You can use the
-@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1}
-@code{-O2}, @code{-O3}, and @code{-Os})
-to @code{gcc} to control the optimization level:
+You can pass the @code{-O} switch, with or without an operand
+(the permitted forms with an operand are @code{-O0}, @code{-O1},
+@code{-O2}, @code{-O3}, @code{-Os}, @code{-Oz}, and
+@code{-Og}) to @code{gcc} to control the optimization level. If you
+pass multiple @code{-O} switches, with or without an operand,
+the last such switch is the one that’s used:
@itemize *
@@ -20298,8 +20313,7 @@ to @code{gcc} to control the optimization level:
@item @code{-O0}
-No optimization (the default);
-generates unoptimized code but has
+No optimization (the default); generates unoptimized code but has
the fastest compilation time. Debugging is easiest with this switch.
Note that many other compilers do substantial optimization even if
@@ -20316,10 +20330,11 @@ mind when doing performance comparisons.
@item @code{-O1}
-Moderate optimization; optimizes reasonably well but does not
-degrade compilation time significantly. You may not be able to see
-some variables in the debugger and changing the value of some
-variables in the debugger may not have the effect you desire.
+Moderate optimization (same as @code{-O} without an operand);
+optimizes reasonably well but does not degrade compilation time
+significantly. You may not be able to see some variables in the
+debugger, and changing the value of some variables in the debugger
+may not have the effect you desire.
@end table
@item
@@ -20328,9 +20343,8 @@ variables in the debugger may not have the effect you
desire.
@item @code{-O2}
-Full optimization;
-generates highly optimized code and has
-the slowest compilation time. You may see significant impacts on
+Extensive optimization; generates highly optimized code but has
+an increased compilation time. You may see significant impacts on
your ability to display and modify variables in the debugger.
@end table
@@ -20340,9 +20354,9 @@ your ability to display and modify variables in the
debugger.
@item @code{-O3}
-Full optimization as in @code{-O2};
-also uses more aggressive automatic inlining of subprograms within a unit
-(@ref{104,,Inlining of Subprograms}) and attempts to vectorize loops.
+Full optimization; attempts more sophisticated transformations, in
+particular on loops, possibly at the cost of larger generated code.
+You may be hardly able to use the debugger at this optimization level.
@end table
@item
@@ -20351,16 +20365,41 @@ also uses more aggressive automatic inlining of
subprograms within a unit
@item @code{-Os}
-Optimize space usage (code and data) of resulting program.
+Optimize for size (code and data) of resulting binary rather than
+speed; based on the @code{-O2} optimization level, but disables
+some of its transformations that often increase code size, as well
+as performs further optimizations designed to reduce code size.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-Oz}
+
+Optimize aggressively for size (code and data) of resulting binary
+rather than speed; may increase the number of instructions executed
+if these instructions require fewer bytes to be encoded.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-Og}
+
+Optimize for debugging experience rather than speed; based on the
+@code{-O1} optimization level, but attempts to eliminate all the
+negative effects of optimization on debugging.
@end table
@end itemize
Higher optimization levels perform more global transformations on the
program and apply more expensive analysis algorithms in order to generate
faster and more compact code. The price in compilation time, and the
-resulting improvement in execution time,
-both depend on the particular application and the hardware environment.
-You should experiment to find the best level for your application.
+resulting improvement in execution time, both depend on the particular
+application and the hardware environment. You should experiment to find
+the best level for your application.
Since the precise set of optimizations done at each level will vary from
release to release (and sometime from target to target), it is best to think
diff --git a/gcc/ada/usage.adb b/gcc/ada/usage.adb
index efa38b540dd..3f6cd69b639 100644
--- a/gcc/ada/usage.adb
+++ b/gcc/ada/usage.adb
@@ -92,17 +92,17 @@ begin
-- Common switches available everywhere
- Write_Switch_Char ("g ", "");
+ Write_Switch_Char ("g ", "");
Write_Line ("Generate debugging information");
- Write_Switch_Char ("Idir ", "");
+ Write_Switch_Char ("Idir ", "");
Write_Line ("Specify source files search path");
- Write_Switch_Char ("I- ", "");
+ Write_Switch_Char ("I- ", "");
Write_Line ("Do not look for sources in current directory");
- Write_Switch_Char ("O[0123] ", "");
- Write_Line ("Control the optimization level");
+ Write_Switch_Char ("O[?] ", "");
+ Write_Line ("Control the optimization level (?=0/1/2/3/s/z/g)");
Write_Eol;
--
2.43.0
