@c Copyright (C) 2014 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{} 2014 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.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below).  A copy of the license is
included in the gfdl(7) man page.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@c man end
@c Set file name and title for the man page.
@setfilename gcov-tool
@settitle offline gcda profile processing tool
@end ignore

@node Gcov-tool
@chapter @command{gcov-tool}---an Offline Gcda Profile Processing Tool

@command{gcov-tool} is a tool you can use in conjunction with GCC to
manipulate or process gcda profile files offline.

@menu
* Gcov-tool Intro::             Introduction to gcov-tool.
* Invoking Gcov-tool::          How to use gcov-tool.
@end menu

@node Gcov-tool Intro
@section Introduction to @command{gcov-tool}
@c man begin DESCRIPTION

@command{gcov-tool} is an offline tool to process gcc's gcda profile files.

Current gcov-tool supports the following functionalities:

@itemize @bullet
@item
merge two sets of profiles with weights.

@item
read one set of profile and rewrite profile contents. One can scale or
normalize the count values.
@end itemize

Examples of the use cases for this tool are:
@itemize @bullet
@item
Collect the profiles for different set of inputs, and use this tool to merge
them. One can specify the weight to factor in the relative importance of
each input.

@item
Rewrite the profile after removing a subset of the gcda files, while maintaining
the consistency of the summary and the histogram.

@item
It can also be used to debug or libgcov code as the tools shares the majority
code as the runtime library.
@end itemize

Note that for the merging operation, this profile generated offline may
contain slight different values from the online merged profile. Here are
a list of typical differences:

@itemize @bullet
@item
histogram difference: This offline tool recomputes the histogram after merging
the counters. The resulting histogram, therefore, is precise. The online
merging does not have this capability -- the histogram is merged from two
histograms and the result is an approximation.

@item
summary checksum difference: Summary checksum uses a CRC32 operation. The value
depends on the link list order of gcov-info objects. This order is different in
gcov-tool from that in the online merge. It's expected to have different
summary checksums. It does not really matter as the compiler does not use this
checksum anywhere.

@item
value profile counter values difference: Some counter values for value profile
are runtime dependent, like heap addresses. It's normal to see some difference
in these kind of counters.
@end itemize

@c man end

@node Invoking Gcov-tool
@section Invoking @command{gcov-tool}

@smallexample
gcov-tool @r{[}@var{global-options}@r{]} SUB_COMMAND
@r{[}@var{sub_command-options}@r{]} @var{profile_dir}
@end smallexample

@command{gcov-tool} accepts the following options:

@ignore
@c man begin SYNOPSIS
gcov-tool [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]

gcov-tool merge [merge-options] @var{directory1} @var{directory2}
     [@option{-v}|@option{--verbose}]
     [@option{-o}|@option{ --output} @var{directory}]
     [@option{-w}|@option{--weight} @var{w1,w2}]

gcov-tool rewrite [rewrite-options] @var{directory}
     [@option{-v}|@option{--verbose}]
     [@option{-o}|@option{--output} @var{directory}]
     [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
     [@option{-n}|@option{--normalize} @var{long_long_value}]
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
@file{gcc}.
@c man end
@end ignore

@c man begin OPTIONS
@table @gcctabopt
@item -h
@itemx --help
Display help about using @command{gcov-tool} (on the standard output), and
exit without doing any further processing.

@item -v
@itemx --version
Display the @command{gcov-tool} version number (on the standard output),
and exit without doing any further processing.

@item merge
Merge two profile directories.

@table @gcctabopt
@item -v
@itemx --verbose
Set the verbose mode.

@item -o @var{directory}
@itemx --output @var{directory}
Set the output profile directory. Default output directory name is
@var{merged_profile}.

@item -w @var{w1},@var{w2}
@itemx --weight @var{w1},@var{w2}
Set the merge weights of the @var{directory1} and @var{directory2},
respectively. The default weights are 1 for both.
@end table

@item rewrite
Read the specified profile directory and rewrite to a new directory.

@table @gcctabopt
@item -v
@itemx --verbose
Set the verbose mode.

@item -o @var{directory}
@itemx --output @var{directory}
Set the output profile directory. Default output name is @var{rewrite_profile}.

@item -s @var{float_or_simple-frac_value}
@itemx --scale @var{float_or_simple-frac_value}
Scale the profile counters. The specified value can be in floating point value,
or simple fraction value form, such 1, 2, 2/3, and 5/3.

@item -n @var{long_long_value}
@itemx --normalize <long_long_value>
Normalize the profile. The specified value is the max counter value
in the new profile.

@end table
@end table

@c man end