1 files changed, 49 insertions, 7 deletions

diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index 22b27e76ec9..4cbc36f14a3 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -93,12 +93,16 @@ The Objective-C and Objective-C++ runtime library.
 @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 following subdirectories:
 @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 test failures.
 
 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}