Re: Incremental LTO linking part 7: documentation

[Jan Hubicka <hubicka at ucw dot cz>]

> Hi,
> 
> just small nits:
> 
> On Tue, May 08 2018, Jan Hubicka wrote:
> > Hi,
> > this patch adds documentation of -flinker-output.
> >
> > 	* doc/invoke.texi (-flinker-output): Document
> > Index: doc/invoke.texi
> > ===================================================================
> > --- doc/invoke.texi	(revision 260042)
> > +++ doc/invoke.texi	(working copy)
> > @@ -12208,6 +12208,50 @@
> >  object file names should not be used as arguments.  @xref{Overall
> >  Options}.
> >  
> > +@item -flinker-output=@var{type}
> > +@opindex -flinker-output
> > +This option controls the code generation of the link time optimizer.  By
> > +default the linker output is determined by the linker plugin automatically. For
> > +debugging the compiler and in the case of incremental linking to non-lto object
> > +file is desired, it may be useful to control the type manually.
> > +
> > +If @var{type} is @samp{exec} the code generation is configured to produce static
> > +binary. In this case @option{-fpic} and @option{-fpie} are both disabled.
> > +
> > +If @var{type} is @samp{dyn} the code generation is configured to produce shared
> > +library. In this case @option{-fpic} or @option{-fPIC} is preserved, but not
> > +enabled automatically.  This makes it possible to build shared libraries without
> > +position independent code on architectures this is possible, i.e. on x86.
> 
> on architectures *where* this is possible?
> 
> > +
> > +If @var{type} is @samp{pie} the code generation is configured to produce
> > +@option{-fpie} executable. This result in similar optimizations as @samp{exec}
> > +except that @option{-fpie} is not disabled if specified at compilation time.
> > +
> > +If @var{type} is @samp{rel} the compiler assumes that incremental linking is
> > +done.  The sections containing intermediate code for link-time optimization are
> > +merged, pre-optimized, and output to the resulting object file. In addition, if
> > +@option{-ffat-lto-objects} is specified the binary code is produced for future
> > +non-lto linking. The object file produced by incremental linking will be smaller
> > +than a static library produced from the same object files.  At link-time the
> > +result of incremental linking will also load faster to compiler than a static
> > +library assuming that majority of objects in the library are used.
> > +
> > +Finally @samp{nolto-rel} configure compiler to for incremental linking where
> > +code generation is forced, final binary is produced and the intermediate code
> > +for later link-time optimization is stripped. When multiple object files are
> > +linked together the resulting code will be optimized better than with link time
> > +optimizations disabled (for example, the cross-module inlining will happen),
> > +most of benefits of whole program optimizations are however lost. 
> > +
> > +During the incremental link (by @option{-r}) the linker plugin will default to
> > +@option{rel}. With current interfaces to GNU Binutils it is however not
> > +possible to link incrementally LTO objects and non-LTO objects into a single
> > +mixed object file.  In the case any of object files in incremental link can not
> > +be used for link-time optimization the linker plugin will output warning and
> > +use @samp{nolto-rel}. To maintain the whole program optimization it is
> > +recommended to link such objects into static library instead. Alternatively it
> > +is possible to use H.J. Lu's binutils with support for mixed objects.
> > +
> 
> I wonder whether this will be still true and what will people make of
> this two years from now.  Perhaps add a reference to the current
> binutils version?

Current GCC won't work better with newer binutils without changes at GCC side.
It does not seem that HJ's and GNU binutils will converge and if they do, we
will need to support it at lto-plugin time and while adding the support we will
also update the docs :)
> 
> Martin