From: Sandra Loosemore <sloosemore@baylibre.com>
Date: Tue, 15 Apr 2025 18:37:37 +0000 (+0000)
Subject: Docs: Address -fivopts, -O0, and -Q confusion [PR71094]
X-Git-Tag: basepoints/gcc-16~51
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d91aab4dd6814ca54c211a93fec3f072745a52c4;p=thirdparty%2Fgcc.git

Docs: Address -fivopts, -O0, and -Q confusion [PR71094]

There's a blurb at the top of the "Optimize Options" node telling
people that most optimization options are completely disabled at -O0
and a similar blurb in the entry for -Og, but nothing at the entry for
-O0.  Since this is a continuing point of confusion it seems wise to
duplicate the information in all the places users are likely to look
for it.

gcc/ChangeLog
	PR tree-optimization/71094
	* doc/invoke.texi (Optimize Options): Document that -fivopts is
	enabled at -O1 and higher.  Add blurb about -O0 causing GCC to
	completely ignore most optimization options.
---

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index b99da94dca1..0b6644b0315 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -12746,6 +12746,7 @@ complexity than at @option{-O}.
 -fipa-pure-const
 -fipa-reference
 -fipa-reference-addressable
+-fivopts
 -fmerge-constants
 -fmove-loop-invariants
 -fmove-loop-stores
@@ -12854,6 +12855,13 @@ by @option{-O2} and also turns on the following optimization flags:
 Reduce compilation time and make debugging produce the expected
 results.  This is the default.
 
+At @option{-O0}, GCC completely disables most optimization passes;
+they are not run even if you explicitly enable them on the command
+line, or are listed by @option{-Q --help=optimizers} as being enabled by
+default.  Many optimizations performed by GCC depend on code analysis
+or canonicalization passes that are enabled by @option{-O}, and it would
+not be useful to run individual optimization passes in isolation.
+
 @opindex Os
 @item -Os
 Optimize for size.  @option{-Os} enables all @option{-O2} optimizations
@@ -14306,6 +14314,7 @@ Enabled by default at @option{-O1} and higher.
 @item -fivopts
 Perform induction variable optimizations (strength reduction, induction
 variable merging and induction variable elimination) on trees.
+Enabled by default at @option{-O1} and higher.
 
 @opindex ftree-parallelize-loops
 @item -ftree-parallelize-loops=n