[PATCH] Update -flto docs wrt option handling

[Gerald Pfeifer]

Thanks for the time and diligence writing this up, Richi!

On Thu, 6 Mar 2014, Richard Biener wrote:
> -files; if @option{-flto} is not passed to the linker, no
> -interprocedural optimizations are applied.
> +files; if @option{-fno-lto} is not passed to the linker, no
> +interprocedural optimizations are applied.

That looks like one "no" too much?  

>  Note that when
> +@option{-fno-fat-lto-objects} is enabled the compile-stage is faster
> +but you cannot perform a regular, non-LTO link, on them.

The comma past "link" appears too much.

>  Additionally, the optimization flags used to compile individual files
>  are not necessarily related to those used at link time.  For instance,

That requires -ffat-lto-objects, though?  The text above talks more
about -fno-fat-lto-objects, not the positive form.

>  @smallexample
> -gcc -c -O0 -flto foo.c
> -gcc -c -O0 -flto bar.c
> -gcc -o myprog -flto -O3 foo.o bar.o
> +gcc -c -O0 -ffat-lto-objects -flto foo.c
> +gcc -c -O0 -ffat-lto-objects -flto bar.c
> +gcc -o myprog -O3 foo.o bar.o
>  @end smallexample
>  
>  This produces individual object files with unoptimized assembler
>  code, but the resulting binary @file{myprog} is optimized at
> -@option{-O3}.  If, instead, the final binary is generated without
> -@option{-flto}, then @file{myprog} is not optimized.
> +@option{-O3}.  If, instead, the final binary is generated with
> +@option{-fno-lto}, then @file{myprog} is not optimized.

Would it make sense to use -Os in the example?  I assume in the
last case myprog would then by optimized with -Os?  

I am suggesting this since I believe it's not optimization vs
no optimization but "optimization level provided during compilation"?

> +Currently, the following options and their setting are take from
> +the first object file that explicitely specified it: 
> +@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon},
> +@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm}
> +and all the @option{-m} target flags.

No -O options in case none are provided during link time?

> +Certain ABI changing flags are required to match in all compilation-units
> +and trying to override this at link-time with a conflicting value
> +is ignored.  This includes options such as @option{-freg-struct-return}
> +and @option{-fpcc-struct-return}. 

If they are required to match, shouldn't a conflicting value during
link time trigger a diagnoses -- error or at least warning?

> +Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow},
> +@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing}
> +are passed through to the link stage and merged conservatively for
> +conflicting translation units.  You can override them at linke-time.

What does conservative merging imply?  How does that work?

> +same link with the same options and also specify those options at
> +link-time.

"link time" (noun)

> -GCC will not work with an older/newer version of GCC@.
> +GCC will not work with an older/newer version of GCC.

What is a version here?  Release series?

Will GCC 4.9.0 and 4.9.1 work, or not?

Gerald