gcc/doc/gcov-tool.texi - gcc - Git at Google

 @c Copyright (C) 2014-2021 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-2021 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{-o}|@option{--output} @var{directory}]
      [@option{-v}|@option{--verbose}]
      [@option{-w}|@option{--weight} @var{w1,w2}]

 gcov-tool rewrite [rewrite-options] @var{directory}
      [@option{-n}|@option{--normalize} @var{long_long_value}]
      [@option{-o}|@option{--output} @var{directory}]
      [@option{-s}|@option{--scale} @var{float_or_simple-frac_value}]
      [@option{-v}|@option{--verbose}]

 gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
      [@option{-f}|@option{--function}]
      [@option{-F}|@option{--fullname}]
      [@option{-h}|@option{--hotonly}]
      [@option{-o}|@option{--object}]
      [@option{-t}|@option{--hot_threshold}] @var{float}
      [@option{-v}|@option{--verbose}]

 @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 -o @var{directory}
 @itemx --output @var{directory}
 Set the output profile directory. Default output directory name is
 @var{merged_profile}.

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

 @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 -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.

 @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 -v
 @itemx --verbose
 Set the verbose mode.
 @end table

 @item overlap
 Compute the overlap score between the two specified profile directories.
 The overlap score is computed based on the arc profiles. It is defined as
 the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
 for all arc counter i, where p1_counter[i] and p2_counter[i] are two
 matched counters and p1_sum_all and p2_sum_all are the sum of counter
 values in profile 1 and profile 2, respectively.

 @table @gcctabopt
 @item -f
 @itemx --function
 Print function level overlap score.

 @item -F
 @itemx --fullname
 Print full gcda filename.

 @item -h
 @itemx --hotonly
 Only print info for hot objects/functions.

 @item -o
 @itemx --object
 Print object level overlap score.

 @item -t @var{float}
 @itemx --hot_threshold <float>
 Set the threshold for hot counter value.

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

 @end table

 @c man end
	@c Copyright (C) 2014-2021 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-2021 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{-o}\|@option{--output} @var{directory}]
	[@option{-v}\|@option{--verbose}]
	[@option{-w}\|@option{--weight} @var{w1,w2}]

	gcov-tool rewrite [rewrite-options] @var{directory}
	[@option{-n}\|@option{--normalize} @var{long_long_value}]
	[@option{-o}\|@option{--output} @var{directory}]
	[@option{-s}\|@option{--scale} @var{float_or_simple-frac_value}]
	[@option{-v}\|@option{--verbose}]

	gcov-tool overlap [overlap-options] @var{directory1} @var{directory2}
	[@option{-f}\|@option{--function}]
	[@option{-F}\|@option{--fullname}]
	[@option{-h}\|@option{--hotonly}]
	[@option{-o}\|@option{--object}]
	[@option{-t}\|@option{--hot_threshold}] @var{float}
	[@option{-v}\|@option{--verbose}]

	@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 -o @var{directory}
	@itemx --output @var{directory}
	Set the output profile directory. Default output directory name is
	@var{merged_profile}.

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

	@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 -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.

	@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 -v
	@itemx --verbose
	Set the verbose mode.
	@end table

	@item overlap
	Compute the overlap score between the two specified profile directories.
	The overlap score is computed based on the arc profiles. It is defined as
	the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
	for all arc counter i, where p1_counter[i] and p2_counter[i] are two
	matched counters and p1_sum_all and p2_sum_all are the sum of counter
	values in profile 1 and profile 2, respectively.

	@table @gcctabopt
	@item -f
	@itemx --function
	Print function level overlap score.

	@item -F
	@itemx --fullname
	Print full gcda filename.

	@item -h
	@itemx --hotonly
	Only print info for hot objects/functions.

	@item -o
	@itemx --object
	Print object level overlap score.

	@item -t @var{float}
	@itemx --hot_threshold <float>
	Set the threshold for hot counter value.

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

	@end table

	@c man end