Replace tabs with spaces in .texi files.

[pf3gnuchains/gcc-fork.git] / gcc / doc / gcov.texi

diff --git a/gcc/doc/gcov.texi b/gcc/doc/gcov.texi
index bfe4a3d..a81fbc2 100644 (file)
--- a/gcc/doc/gcov.texi
+++ b/gcc/doc/gcov.texi
@@ -1,12 +1,12 @@
 @c Copyright (C) 1996, 1997, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2008 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
 @ignore
 @c man begin COPYRIGHT
-Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005
-Free Software Foundation, Inc.
+Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+2008  Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -38,10 +38,11 @@ included in the gfdl(7) man page.
 test code coverage in your programs.
 
 @menu
-* Gcov Intro::                         Introduction to gcov.
-* Invoking Gcov::              How to use gcov.
+* Gcov Intro::                  Introduction to gcov.
+* Invoking Gcov::               How to use gcov.
 * Gcov and Optimization::       Using gcov with GCC optimization.
 * Gcov Data Files::             The files used by gcov.
+* Cross-profiling::             Data file relocation.
 @end menu
 
 @node Gcov Intro
@@ -109,10 +110,10 @@ compatible with any other profiling or test coverage mechanism.
 @c man end
 
 @node Invoking Gcov
-@section Invoking gcov
+@section Invoking @command{gcov}
 
 @smallexample
-gcov @r{[}@var{options}@r{]} @var{sourcefile}
+gcov @r{[}@var{options}@r{]} @var{sourcefiles}
 @end smallexample
 
 @command{gcov} accepts the following options:
@@ -127,7 +128,7 @@ gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
      [@option{-l}|@option{--long-file-names}]
      [@option{-p}|@option{--preserve-paths}]
      [@option{-f}|@option{--function-summaries}]
-     [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile}
+     [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefiles}
      [@option{-u}|@option{--unconditional-branches}]
 @c man end
 @c man begin SEEALSO
@@ -427,7 +428,7 @@ message ``never executed'' is printed.
 For a call, if it was executed at least once, then a percentage
 indicating the number of times the call returned divided by the number
 of times the call was executed will be printed.  This will usually be
-100%, but may be less for functions call @code{exit} or @code{longjmp},
+100%, but may be less for functions that call @code{exit} or @code{longjmp},
 and thus may not return every time they are called.
 
 The execution counts are cumulative.  If the example program were
@@ -531,3 +532,42 @@ information.
 The full details of the file format is specified in @file{gcov-io.h},
 and functions provided in that header file should be used to access the
 coverage files.
+
+@node Cross-profiling
+@section Data file relocation to support cross-profiling
+
+Running the program will cause profile output to be generated.  For each 
+source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} 
+file will be placed in the object file directory. That implicitly requires 
+running the program on the same system as it was built or having the same 
+absolute directory structure on the target system. The program will try
+to create the needed directory structure, if it is not already present.
+
+To support cross-profiling, a program compiled with @option{-fprofile-arcs}
+can relocate the data files based on two environment variables: 
+
+@itemize @bullet
+@item
+GCOV_PREFIX contains the prefix to add to the absolute paths 
+in the object file. Prefix must be absolute as well, otherwise its 
+value is ignored. The default is no prefix.
+
+@item
+GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off
+the hardwired absolute paths. Default value is 0.
+
+@emph{Note:} GCOV_PREFIX_STRIP has no effect if GCOV_PREFIX is undefined, empty
+or non-absolute.
+@end itemize
+
+For example, if the object file @file{/user/build/foo.o} was built with
+@option{-fprofile-arcs}, the final executable will try to create the data file
+@file{/user/build/foo.gcda} when running on the target system.  This will
+fail if the corresponding directory does not exist and it is unable to create
+it.  This can be overcome by, for example, setting the environment as
+@samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}.  Such a
+setting will name the data file @file{/target/run/build/foo.gcda}.
+
+You must move the data files to the expected directory tree in order to
+use them for profile directed optimizations (@option{--use-profile}), or to
+use the @command{gcov} tool.