[LTO merge][5/15] Documentation

[Diego Novillo <dnovillo at google dot com>]

This patch adds 

It has been tested on x86_64 together with the the other 14
patches in this merge.

See http://gcc.gnu.org/ml/gcc/2009-09/msg00578.html for a
description of the whole set.


Thanks.  Diego.


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 and --enable-lto.
	* doc/invoke.texi: Document -fwpa, -flto, -fwhopr,
	-fltrans, -flto-report and -flto-compression-level
	* doc/sourcebuild.texi: Document use of zlib.
	Add section for LTO Testing.

diff -rdupN --exclude=.svn --exclude=.git --exclude='*.diff*' --exclude='autom4te*' --exclude=tags --exclude=ChangeLog.lto --exclude=configure /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/install.texi /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/install.texi
--- /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/install.texi	2009-09-27 19:56:26.000000000 -0400
+++ /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/install.texi	2009-09-27 19:53:19.000000000 -0400
@@ -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,10 @@ 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 link-time optimization (LTO).  This is enabled by default if a
+working libelf implemetnation is found (see @option{--with-libelf}).
 @end table
 
 @subsubheading AWT-Specific Options
diff -rdupN --exclude=.svn --exclude=.git --exclude='*.diff*' --exclude='autom4te*' --exclude=tags --exclude=ChangeLog.lto --exclude=configure /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/invoke.texi /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/invoke.texi
--- /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/invoke.texi	2009-09-25 15:23:18.000000000 -0400
+++ /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/invoke.texi	2009-09-25 11:21:16.000000000 -0400
@@ -349,7 +349,7 @@ 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
+-floop-parallelize-all -fltrans -fltrans-output-list @gol
 -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
@@ -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 -fwpa @gol
 --param @var{name}=@var{value}
 -O  -O0  -O1  -O2  -O3  -Os}
 
@@ -7112,6 +7112,73 @@ 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.
+
+Disabled by default.
+
+@item -fwhopr
+@opindex fwhopr
+This option is similar 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 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.  This option is only supported by the LTO frontend.
+
+@item -fltrans
+@opindex fltrans
+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.  This option is only supported by the LTO frontend.
+
+@item -fltrans-output-list=@var{file}
+@opindex fltrans-output-list
+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 to 9,
+and correspond to levels of compression provided by Zlib.  Values
+outside this range are clamped to either 0 or 9.  If the option is not given,
+LTO uses Zlib's default compression setting.
+
+@item -flto-report
+This option is only useful when processing object files in LTO
+mode (via -fwhopr or -flto).
+
+Disabled by default.
+
 @item -fcprop-registers
 @opindex fcprop-registers
 After register allocation and post-register allocation instruction splitting,
diff -rdupN --exclude=.svn --exclude=.git --exclude='*.diff*' --exclude='autom4te*' --exclude=tags --exclude=ChangeLog.lto --exclude=configure /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/sourcebuild.texi /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/sourcebuild.texi
--- /usr/local/google/homedirs/dnovillo/gcc/trunk/gcc/doc/sourcebuild.texi	2009-09-23 12:43:00.000000000 -0400
+++ /usr/local/google/homedirs/dnovillo/gcc/trunk.lto/gcc/doc/sourcebuild.texi	2009-09-23 10:50:41.000000000 -0400
@@ -97,8 +97,9 @@ The C++ runtime library.
 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
@@ -821,6 +822,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 +1349,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}