doc: Document -O1 as the preferred level for large machine-generated code

At -O1, the intention is that we compile things in a "reasonable" amount
of time (ditto memory use). In particular, we try to especially avoid
optimizations which scale poorly on pathological cases, as is the case
for large machine-generated code.

Recommend -O1 for large machine-generated code, as has been informally
done on bugs for a while now.

This applies (broadly speaking) for both large machine-generated functions
but also to a lesser extent repetitive small-but-still-not-tiny functions
from a generator program.

gcc/ChangeLog:
	PR middle-end/114855
	* doc/invoke.texi (Optimize options): Mention machine-generated
	code for -O1.

1 files changed, 5 insertions, 0 deletions

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index e0a6412..9fb0925 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -12560,6 +12560,11 @@ With @option{-O}, the compiler tries to reduce code size and execution
 time, without performing any optimizations that take a great deal of
 compilation time.
 
+@option{-O} is the recommended optimization level for large machine-generated
+code as a sensible balance between time taken to compile and memory use:
+higher optimization levels perform optimizations with greater algorithmic
+complexity than at @option{-O}.
+
 @c Note that in addition to the default_options_table list in opts.cc,
 @c several optimization flags default to true but control optimization
 @c passes that are explicitly disabled at -O0.