Re: [LTO merge][5/15] Documentation

[Diego Novillo <dnovillo at google dot com>]

On Tue, Sep 29, 2009 at 17:02, Joseph S. Myers <joseph@codesourcery.com> wrote:

>> +Enable link-time optimization (LTO). ÂThis is enabled by default if a
>
> You mean, build that support into the compiler (not enable it by default
> once built in).

Fixed.

>> +working libelf implemetnation is found (see @option{--with-libelf}).
>
> "implementation"

Fixed.

> The options -flto -fwhopr -flto-compression-level need adding to the
> summary list of options.

Fixed.

> "LTRANS)@." for correct spacing.

Fixed.

>> +Disabled by default. ÂThis option is only supported by the LTO frontend.
>
> "front end"

Fixed.

>> +Disabled by default. ÂThis option is only supported by the LTO frontend.
>
> "front end"

Fixed.

>> +@item -flto-report
>> +This option is only useful when processing object files in LTO
>> +mode (via -fwhopr or -flto).
>
> @option{-fwhopr}, @option{-flto}.

Fixed.

> There are three new configure options, -with-libelf, --with-libelf-include
> and --with-libelf-lib, added by patch 2. ÂAll of these need documenting
> alongside the other configure options; a cross-reference to --with-libelf
> from the list of prerequisites is not sufficient, the option itself needs
> documenting.

Fixed.

>Â--enable-gold is effectively a new configure option to
> enable the plugin, and needs documenting as such. Â(My understanding is
> that the plugin might in principle be usable with other linkers rather
> than being strongly tied to gold only, so that isn't necessarily the best
> spelling of the configure option.)

Not really.  The plugin is tied to gold.  If other linkers
implement the exact same interface, then the plugin should work
with them, of course.

> I would expect the new directories to be documented in sourcebuild.texi.

Fixed.

> I would expect information about LTO contributors to be added to
> contrib.texi.

> I would think the LTO functionality needs one or more
> maintainers or reviewers appointed by the SC, if they haven't already been
> appointed, who should be added to MAINTAINERS.

I sent a request to the SC.


> There should be some explicit statement in install.texi that this
> functionality is only supported for ELF targets.

Done.


> The documentation of -flto-report in invoke.texi is clearly inadequate.
> Documentation should say what the option does; "only useful when"
> information may be appropriate as part of the documentation, but not the
> whole as it is at present.

Fixed.

>
> Comments (C):
>
> The user documentation fails to address LTO from a user's perspective. ÂIt
> describes implementation details, but does not explain how or when to use
> or not to use the functionality. ÂLet's consider the options documented:

I added a long description of how things work in the -flto flag.
Let's iterate over this during stage3.  The current content
should be enough to cover the main use scenarios.

> I would expect some changes to be needed to passes.texi as well to discuss
> LTO. ÂCertainly, it would be good to have some sort of overview of the
> workings of LTO and how data is arranged in object files that is checked
> into the GCC sources and branched along with GCC, whether in the internals
> manual or in comments in the sources (I haven't yet looked at the patches
> with the bulk of the LTO sources to see if there are suitable comments
> there); a wiki page that has moved on to describing new arrangements for
> 4.6 is of less use when fixing a bug on 4.5 branch. ÂBut this is secondary
> to getting a proper description for users of how to use LTO.

Will fix.


2009-09-28  Simon Baldwin  <simonb@google.com>
            Richard Guenther  <rguenther@suse.de>
            Janis Johnson  <janis187@us.ibm.com>
            Doug Kwan  <dougkwan@google.com>
            Diego Novillo  <dnovillo@google.com>
            Ramana Radhakrishnan  <ramana.r@gmail.com>
            Ollie Wild  <aaw@google.com>

        * doc/install.texi: Add documentation for libelf, --enable-lto
	--with-libelf, --with-libelf-include, --with-libelf-lib
	and --enable-gold.
        * doc/invoke.texi: Document -fwpa, -flto, -fwhopr,
        -fltrans, -flto-report, -flto-compression-level and
	-use-linker-plugin.
        * doc/sourcebuild.texi: Document use of zlib.
        Add section for LTO Testing.

Index: doc/sourcebuild.texi
===================================================================
--- doc/sourcebuild.texi	(revision 152279)
+++ doc/sourcebuild.texi	(working copy)
@@ -93,12 +93,16 @@ The Objective-C and Objective-C++ runtim
 @item libstdc++-v3
 The C++ runtime library.

+@item lto-plugin
+Plugin used by @command{gold} if link-time optimizations are enabled.
+
 @item maintainer-scripts
 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.

 @item zlib
-The @code{zlib} compression library, used by the Java front end and as
-part of the Java runtime library.
+The @code{zlib} compression library, used by the Java front end, as
+part of the Java runtime library, and for compressing and uncompressing
+GCC's intermediate language in LTO object files.
 @end table

 The build system in the top level directory, including how recursion
@@ -137,11 +141,12 @@ The @file{gcc} directory contains the fo
 @item @var{language}
 Subdirectories for various languages.  Directories containing a file
 @file{config-lang.in} are language subdirectories.  The contents of
-the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C)
-and @file{objcp} (for Objective-C++) are documented in this manual
-(@pxref{Passes, , Passes and Files of the Compiler}); those for other
-languages are not.  @xref{Front End, , Anatomy of a Language Front End},
-for details of the files in these directories.
+the subdirectories @file{cp} (for C++), @file{lto} (for LTO),
+@file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are
+documented in this manual (@pxref{Passes, , Passes and Files of the
+Compiler}); those for other languages are not.  @xref{Front End, ,
+Anatomy of a Language Front End}, for details of the files in these
+directories.

 @item config
 Configuration files for supported architectures and operating
@@ -821,6 +826,7 @@ here; FIXME: document the others.
 * Ada Tests::       The Ada language testsuites.
 * C Tests::         The C language testsuites.
 * libgcj Tests::    The Java library testsuites.
+* LTO Testing::     Support for testing link-time optimizations.
 * gcov Testing::    Support for testing gcov.
 * profopt Testing:: Support for testing profile-directed optimizations.
 * compat Testing::  Support for testing binary compatibility.
@@ -1347,6 +1353,42 @@ bugs in libgcj that had caused Mauve tes

 We encourage developers to contribute test cases to Mauve.

+@node LTO Testing
+@subsection Support for testing link-time optimizations
+
+Tests for link-time optimizations usually require multiple source files
+that are compiled separately, perhaps with different sets of options.
+There are several special-purpose test directives used for these tests.
+
+@table @code
+@item @{ dg-lto-do @var{do-what-keyword} @}
+@var{do-what-keyword} specifies how the test is compiled and whether
+it is executed.  It is one of:
+
+@table @code
+@item assemble
+Compile with @option{-c} to produce a relocatable object file.
+@item link
+Compile, assemble, and link to produce an executable file.
+@item run
+Produce and run an executable file, which is expected to return
+an exit code of 0.
+@end table
+
+The default is @code{assemble}.  That can be overridden for a set of
+tests by redefining @code{dg-do-what-default} within the @code{.exp}
+file for those tests.
+
+Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
+@samp{target} or @samp{xfail} list.  Use @code{dg-skip-if},
+@code{dg-xfail-if}, or @code{dg-xfail-run-if}.
+
+@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}]
@} [@{ target @var{selector} @}]@}
+This directive provides a list of one or more sets of compiler options
+to override @var{LTO_OPTIONS}.  Each test will be compiled and run with
+each of these sets of options.
+@end table
+
 @node gcov Testing
 @subsection Support for testing @command{gcov}

Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi	(revision 152279)
+++ doc/invoke.texi	(working copy)
@@ -349,8 +349,8 @@ Objective-C and Objective-C++ Dialects}.
 -fno-ira-share-spill-slots -fira-verbose=@var{n} @gol
 -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
 -floop-block -floop-interchange -floop-strip-mine -fgraphite-identity @gol
--floop-parallelize-all @gol
--fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
+-floop-parallelize-all -flto -flto-compression-level -flto-report -fltrans @gol
+-fltrans-output-list -fmerge-all-constants -fmerge-constants
-fmodulo-sched @gol
 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
 -fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
 -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
@@ -389,7 +389,7 @@ Objective-C and Objective-C++ Dialects}.
 -funit-at-a-time -funroll-all-loops -funroll-loops @gol
 -funsafe-loop-optimizations -funsafe-math-optimizations -funswitch-loops @gol
 -fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
--fwhole-program @gol
+-fwhole-program -fwhopr -fwpa -use-linker-plugin @gol
 --param @var{name}=@var{value}
 -O  -O0  -O1  -O2  -O3  -Os}

@@ -7111,6 +7111,224 @@ compilation unit, not for the single sou

 This option implies @option{-fwhole-file} for Fortran programs.

+@item -flto
+@opindex flto
+This option runs the standard link-time optimizer.  When invoked
+with source code, it generates GIMPLE and writes it to special
+ELF sections in the object file.  When the object files are
+linked together, all the function bodies are read from these ELF
+sections and instantiated as if they had been part of the same
+translation unit.
+
+To use the link-timer optimizer, @code{-flto} needs to be specified at
+compile time and during the final link.  For example,
+
+@smallexample
+gcc -c -O2 -flto foo.c
+gcc -c -O2 -flto bar.c
+gcc -o myprog -flto -O2 foo.o bar.o
+@end smallexample
+
+The first two invocations to GCC will save a bytecode representation
+of GIMPLE (one of GCC's internal representations) into special ELF
+sections inside @file{foo.o} and @file{bar.o}.  The final invocation
+will read the GIMPLE bytecode from @file{foo.o} and @file{bar.o},
+merge the two files into a single internal image, and compile the
+result as usual.  Since both @file{foo.o} and @file{bar.o} are merged
+into a single image, this causes all the inter-procedural analyses and
+optimizations in GCC to work across the two files as if they were a
+single one.  This means, for example, that the inliner will be able to
+inline functions in @file{bar.o} into functions in @file{foo.o} and
+vice-versa.
+
+Another (simpler) way to enable link-time optimization is,
+
+@smallexample
+gcc -o myprog -flto -O2 foo.c bar.c
+@end smallexample
+
+The above will generate bytecode for @file{foo.c} and @file{bar.c},
+merge them together into a single GIMPLE representation and optimize
+them as usual to produce @file{myprog}.
+
+The only important thing to keep in mind is that to enable link-time
+optimizations the @option{-flto} flag needs to be passed to both the
+compile and the link commands.
+
+Note that when a file is compiled with @option{-flto}, the generated
+object file will be larger than a regular object file because it will
+contain GIMPLE bytecodes and the usual final code.  This means that
+object files with LTO information can be linked as a normal object
+file.  So, in the previous example, if the final link is done with
+
+@smallexample
+gcc -o myprog foo.o bar.o
+@end smallexample
+
+The only difference will be that no inter-procedural optimizations
+will be applied to produce @file{myprog}.  The two object files
+@file{foo.o} and @file{bar.o} will be simply sent to the regular
+linker.
+
+Additionally, the optimization flags used to compile individual files
+are not necessarily related to those used at link-time.  For instance,
+
+@smallexample
+gcc -c -O0 -flto foo.c
+gcc -c -O0 -flto bar.c
+gcc -o myprog -flto -O3 foo.o bar.o
+@end smallexample
+
+This will produce individual object files with unoptimized assembler
+code, but the resulting binary @file{myprog} will be optimized at
+@option{-O3}.  Now, if the final binary is generated without
+@option{-flto}, then @file{myprog} will not be optimized.
+
+When producing the final binary with @option{-flto}, GCC will only
+apply link-time optimizations to those files that contain bytecode.
+Therefore, you can mix and match object files and libraries with
+GIMPLE bytecodes and final object code.  GCC will automatically select
+which files to optimize in LTO mode and which files to link without
+further processing.
+
+There are some code generation flags that GCC will preserve when
+generating bytecodes, as they need to be used during the final link
+stage.  Currently, the following options are saved into the GIMPLE
+bytecode files: @option{-fPIC}, @option{-fcommon} and all the
+@option{-m} target flags.
+
+At link time, these options are read-in and reapplied.  Note that the
+current implementation makes no attempt at recognizing conflicting
+values for these options.  If two or more files have a conflicting
+value (e.g., one file is compiled with @option{-fPIC} and another
+isn't), the compiler will simply use the last value read from the
+bytecode files.  It is recommended, then, that all the files
+participating in the same link be compiled with the same options.
+
+Another feature of LTO is that it is possible to apply interprocedural
+optimizations on files written in different languages.  This requires
+some support in the language front end.  Currently, the C, C++ and
+Fortran front ends are capable of emitting GIMPLE bytecodes, so
+something like this should work
+
+@smallexample
+gcc -c -flto foo.c
+g++ -c -flto bar.cc
+gfortran -c -flto baz.f90
+g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran
+@end smallexample
+
+Notice that the final link is done with @command{g++} to get the C++
+runtime libraries and @option{-lgfortran} is added to get the Fortran
+runtime libraries.  In general, when mixing languages in LTO mode, you
+should use the same link command used when mixing languages in a
+regular (non-LTO) compilation.  This means that if your build process
+was mixing languages before, all you need to add is @option{-flto} to
+all the compile and link commands.
+
+If object files containing GIMPLE bytecode are stored in a library
+archive, say @file{libfoo.a}, it is possible to extract and use them
+in an LTO link if you are using @command{gold} as the linker (which,
+in turn requires GCC to be configured with @option{--enable-gold}).
+To enable this feature, use the flag @option{-use-linker-plugin} at
+link-time:
+
+@smallexample
+gcc -o myprog -O2 -flto -use-linker-plugin a.o b.o -lfoo
+@end smallexample
+
+With the linker plugin enabled, @command{gold} will extract the needed
+GIMPLE files from @file{libfoo.a} and pass them on to the running GCC
+to make them part of the aggregated GIMPLE image to be optimized.
+
+If you are not using @command{gold} and/or do not specify
+@option{-use-linker-plugin} then the objects inside @file{libfoo.a}
+will be extracted and linked as usual, but they will not participate
+in the LTO optimization process.
+
+Regarding portability: the current implementation of LTO makes no
+attempt at generating bytecode that can be ported between different
+types of hosts.  The bytecode files are versioned and there is a
+strict version check, so bytecode files generated in one version of
+GCC will not work with an older/newer version of GCC.
+
+This option is disabled by default.
+
+@item -fwhopr
+@opindex fwhopr
+This option is identical in functionality to @option{-flto} but it
+differs in how the final link stage is executed.  Instead of loading
+all the function bodies in memory, the callgraph is analyzed and
+optimization decisions are made (whole program analysis or WPA). Once
+optimization decisions are made, the callgraph is partitioned and the
+different sections are compiled separately (local transformations or
+LTRANS)@.  This process allows optimizations on very large programs
+that otherwise would not fit in memory.  This option enables
+@option{-fwpa} and @option{-fltrans} automatically.
+
+Disabled by default.
+
+@item -fwpa
+@opindex fwpa
+This is an internal option used by GCC when compiling with
+@option{-fwhopr}.  You should never need to use it.
+
+This option runs the link-time optimizer in the whole-program-analysis
+(WPA) mode, which reads in summary information from all inputs and
+performs a whole-program analysis based on summary information only.
+It generates object files for subsequent runs of the link-time
+optimizer where individual object files are optimized using both
+summary information from the WPA mode and the actual function bodies.
+It then drives the LTRANS phase.
+
+Disabled by default.
+
+@item -fltrans
+@opindex fltrans
+This is an internal option used by GCC when compiling with
+@option{-fwhopr}.  You should never need to use it.
+
+This option runs the link-time optimizer in the local-transformation (LTRANS)
+mode, which reads in output from a previous run of the LTO in WPA mode.
+In the LTRANS mode, LTO optimizes an object and produces the final assembly.
+
+Disabled by default.
+
+@item -fltrans-output-list=@var{file}
+@opindex fltrans-output-list
+This is an internal option used by GCC when compiling with
+@option{-fwhopr}.  You should never need to use it.
+
+This option specifies a file to which the names of LTRANS output files are
+written.  This option is only meaningful in conjunction with @option{-fwpa}.
+
+Disabled by default.
+
+@item -flto-compression-level=@var{n}
+This option specifies the level of compression used for intermediate
+language written to LTO object files, and is only meaningful in
+conjunction with LTO mode (@option{-fwhopr}, @option{-flto}).  Valid
+values are 0 (no compression) to 9 (maximum compression).  Values
+outside this range are clamped to either 0 or 9.  If the option is not
+given, a default balanced compression setting is used.
+
+@item -flto-report
+Prints a report with internal details on the workings of the link-time
+optimizer.  The contents of this report vary from version to version,
+it is meant to be useful to GCC developers when processing object
+files in LTO mode (via @option{-fwhopr} or @option{-flto}).
+
+Disabled by default.
+
+@item -use-linker-plugin
+Enables the extraction of objects with GIMPLE bytecode information
+from library archives.  This option relies on features available only
+in @command{gold}, so to use this you must configure GCC with
+@option{--enable-gold}.  See @option{-flto} for a description on the
+effect of this flag and how to use it.
+
+Disabled by default.
+
 @item -fcprop-registers
 @opindex fcprop-registers
 After register allocation and post-register allocation instruction splitting,
Index: doc/install.texi
===================================================================
--- doc/install.texi	(revision 152279)
+++ doc/install.texi	(working copy)
@@ -356,6 +356,15 @@ Alternatively, if an MPC source distribu
 subdirectory of your GCC sources named @file{mpc}, it will be built
 together with GCC@.

+@item libelf version 0.8.12 (or later)
+
+Necessary to build link-time optimization (LTO) support.  It can be
+downloaded from @uref{http://www.mr511.de/software/libelf-0.8.12.tar.gz},
+though it is commonly available in several systems.
+
+The @option{--with-libelf} configure option should be used if libelf is
+not installed in your default library search patch.
+
 @end table

 @heading Tools/packages necessary for modifying GCC
@@ -1888,6 +1897,30 @@ Use the @code{WCHAR} and Win32 W functio
 add @code{-lunicows} to @file{libgcj.spec}.  The built executables will
 only run on Microsoft Windows NT and above.
 @end table
+
+@item --enable-lto
+Enable support for link-time optimization (LTO).  This is enabled by
+default if a working libelf implementation is found (see
+@option{--with-libelf}).
+
+@item --with-libelf=@var{pathname}
+@itemx --with-libelf-include=@var{pathname}
+@itemx --with-libelf-lib=@var{pathname}
+If you do not have libelf installed in a standard location and you
+want to enable support for link-time optimization (LTO), you can
+explicitly specify the directory where libelf is installed
+(@samp{--with-libelf=@var{libelfinstalldir}}).  The
+@option{--with-libelf=@var{libelfinstalldir}} option is shorthand for
+@option{--with-libelf-include=@var{libelfinstalldir}/include}
+@option{--with-libelf-lib=@var{libelfinstalldir}/lib}.
+
+@item --enable-gold
+Enable support for using @command{gold} as the linker.  If gold support is
+enabled together with @option{--enable-lto}, an additional directory
+@file{lto-plugin} will be built.  The code in this directory is a
+plugin for gold that allows the link-time optimizer to extract object
+files with LTO information out of library archives.  See
+@option{-flto} and @option{-fwhopr} for details.
 @end table

 @subsubheading AWT-Specific Options