doc: mention STAGE1_CFLAGS

STAGE1_CFLAGS can be used to accelerate the just-built stage1 compiler
which especially improves its performance on some of the large generated
files during bootstrap. It defaults to nothing (i.e. -O0).

The downside is that if the native compiler is buggy, there's a greater
risk of a failed bootstrap. Those with a modern native compiler, ideally
a recent version of GCC, should be able to use -O1 or -O2 without issue
to get a faster build.

	PR rtl-optimization/111619
	* doc/install.texi (Building a native compiler): Discuss STAGE1_CFLAGS.
---
This came out of a discussion between mjw and I a little while ago when
working on the buildbots. OK?

 gcc/doc/install.texi | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)


base-commit: 00448f9b5a123b4b6b3e6f45d2fecf0a5dca66b3

Hi Sam,

On Mon, 2024-11-11 at 07:54 +0000, Sam James wrote:
> STAGE1_CFLAGS can be used to accelerate the just-built stage1 compiler
> which especially improves its performance on some of the large generated
> files during bootstrap. It defaults to nothing (i.e. -O0).
> 
> The downside is that if the native compiler is buggy, there's a greater
> risk of a failed bootstrap. Those with a modern native compiler, ideally
> a recent version of GCC, should be able to use -O1 or -O2 without issue
> to get a faster build.
> 
> 	PR rtl-optimization/111619
> 	* doc/install.texi (Building a native compiler): Discuss STAGE1_CFLAGS.
> ---
> This came out of a discussion between mjw and I a little while ago when
> working on the buildbots. OK?

I cannot approve, but the text does look OK to me.

builder.sourceware.org has been using STAGE1_CFLAGS="-O2" for all
bootstrap builds.
https://sourceware.org/cgit/builder/tree/builder/master.cfg#n4250

BTW. I think I would flip the default to that. It seems having a
bootstrap compiler which miscompiles at -O2 is very rare. Keep the env
var, but make people set it who don't trust their compiler to behave.

Cheers,

Mark

>  gcc/doc/install.texi | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
> index 705440ffd330..4bd60555af9b 100644
> --- a/gcc/doc/install.texi
> +++ b/gcc/doc/install.texi
> @@ -3017,7 +3017,11 @@ bootstrapped, you can use @code{CFLAGS_FOR_TARGET} to modify their
>  compilation flags, as for non-bootstrapped target libraries.
>  Again, if the native compiler miscompiles the stage1 compiler, you may
>  need to work around this by avoiding non-working parts of the stage1
> -compiler.  Use @code{STAGE1_TFLAGS} to this end.
> +compiler.  Use @code{STAGE1_CFLAGS} and @code{STAGE1_TFLAGS} (for target
> +libraries) to this end.  The default value for @code{STAGE1_CFLAGS} is
> +@samp{STAGE1_CFLAGS='-O0'} to increase the chances of a successful bootstrap
> +with a buggy native compiler.  Changing this to @code{-O1} or @code{-O2}
> +can improve bootstrap times, with some greater risk of a failed bootstrap.
>  
>  If you used the flag @option{--enable-languages=@dots{}} to restrict
>  the compilers to be built, only those you've actually enabled will be
> 
> base-commit: 00448f9b5a123b4b6b3e6f45d2fecf0a5dca66b3

Sam James <sam@gentoo.org> writes:

> STAGE1_CFLAGS can be used to accelerate the just-built stage1 compiler
> which especially improves its performance on some of the large generated
> files during bootstrap. It defaults to nothing (i.e. -O0).
>
> The downside is that if the native compiler is buggy, there's a greater
> risk of a failed bootstrap. Those with a modern native compiler, ideally
> a recent version of GCC, should be able to use -O1 or -O2 without issue
> to get a faster build.
>
> 	PR rtl-optimization/111619
> 	* doc/install.texi (Building a native compiler): Discuss STAGE1_CFLAGS.
> ---
> This came out of a discussion between mjw and I a little while ago when
> working on the buildbots. OK?

Ping.

>
>  gcc/doc/install.texi | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
> index 705440ffd330..4bd60555af9b 100644
> --- a/gcc/doc/install.texi
> +++ b/gcc/doc/install.texi
> @@ -3017,7 +3017,11 @@ bootstrapped, you can use @code{CFLAGS_FOR_TARGET} to modify their
>  compilation flags, as for non-bootstrapped target libraries.
>  Again, if the native compiler miscompiles the stage1 compiler, you may
>  need to work around this by avoiding non-working parts of the stage1
> -compiler.  Use @code{STAGE1_TFLAGS} to this end.
> +compiler.  Use @code{STAGE1_CFLAGS} and @code{STAGE1_TFLAGS} (for target
> +libraries) to this end.  The default value for @code{STAGE1_CFLAGS} is
> +@samp{STAGE1_CFLAGS='-O0'} to increase the chances of a successful bootstrap
> +with a buggy native compiler.  Changing this to @code{-O1} or @code{-O2}
> +can improve bootstrap times, with some greater risk of a failed bootstrap.
>  
>  If you used the flag @option{--enable-languages=@dots{}} to restrict
>  the compilers to be built, only those you've actually enabled will be
>
> base-commit: 00448f9b5a123b4b6b3e6f45d2fecf0a5dca66b3

On Wed, Nov 20, 2024 at 7:16 PM Sam James <sam@gentoo.org> wrote:
>
> Sam James <sam@gentoo.org> writes:
>
> > STAGE1_CFLAGS can be used to accelerate the just-built stage1 compiler
> > which especially improves its performance on some of the large generated
> > files during bootstrap. It defaults to nothing (i.e. -O0).
> >
> > The downside is that if the native compiler is buggy, there's a greater
> > risk of a failed bootstrap. Those with a modern native compiler, ideally
> > a recent version of GCC, should be able to use -O1 or -O2 without issue
> > to get a faster build.
> >
> >       PR rtl-optimization/111619
> >       * doc/install.texi (Building a native compiler): Discuss STAGE1_CFLAGS.
> > ---
> > This came out of a discussion between mjw and I a little while ago when
> > working on the buildbots. OK?
>
> Ping.
>
> >
> >  gcc/doc/install.texi | 6 +++++-
> >  1 file changed, 5 insertions(+), 1 deletion(-)
> >
> > diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
> > index 705440ffd330..4bd60555af9b 100644
> > --- a/gcc/doc/install.texi
> > +++ b/gcc/doc/install.texi
> > @@ -3017,7 +3017,11 @@ bootstrapped, you can use @code{CFLAGS_FOR_TARGET} to modify their
> >  compilation flags, as for non-bootstrapped target libraries.
> >  Again, if the native compiler miscompiles the stage1 compiler, you may
> >  need to work around this by avoiding non-working parts of the stage1
> > -compiler.  Use @code{STAGE1_TFLAGS} to this end.
> > +compiler.  Use @code{STAGE1_CFLAGS} and @code{STAGE1_TFLAGS} (for target
> > +libraries) to this end.  The default value for @code{STAGE1_CFLAGS} is
> > +@samp{STAGE1_CFLAGS='-O0'} to increase the chances of a successful bootstrap

The default for STAGE1_CFLAGS is '-g', not -O0 (this can make a
difference for non-GCC host
compilers).  The default for STAGE1_TFLAGS is '-O2 -g', note the
stage1 target libraries are
built by the stage1 compiler, not the host compiler.  I think the
sentence above for a reason
talks about STAGE1_TFLAGS and a better change would be to simply add

'You can use @code{STAGE1_CFLAGS} to set the flags passed to the host compiler
when building the stage1 compiler.  The default is to pass
@option{-g}, when the host
compiler is GCC this is results in a non-optimizing build of the
stage1 compiler.  You
can speed up the bootstrap by using @samp{STAGE1_CFLAGS='-O2'} at the increased
chance to miscompile the stage1 compiler when the host compiler is buggy.'

Richard.

> > +with a buggy native compiler.  Changing this to @code{-O1} or @code{-O2}
> > +can improve bootstrap times, with some greater risk of a failed bootstrap.
> >
> >  If you used the flag @option{--enable-languages=@dots{}} to restrict
> >  the compilers to be built, only those you've actually enabled will be
> >
> > base-commit: 00448f9b5a123b4b6b3e6f45d2fecf0a5dca66b3