path: root/gcc/doc/gcov-tool.1

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GCOV-TOOL 1"
.TH GCOV-TOOL 1 "2016-08-22" "gcc-6.2.0" "GNU"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gcov\-tool \- offline gcda profile processing tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gcov-tool [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR]
.PP
gcov-tool merge [merge\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-o\fR| \fB\-\-output\fR \fIdirectory\fR]
     [\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov-tool rewrite [rewrite\-options] \fIdirectory\fR
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
     [\fB\-s\fR|\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR]
     [\fB\-n\fR|\fB\-\-normalize\fR \fIlong_long_value\fR]
.PP
gcov-tool overlap [overlap\-options] \fIdirectory1\fR \fIdirectory2\fR
     [\fB\-v\fR|\fB\-\-verbose\fR]
     [\fB\-h\fR|\fB\-\-hotonly\fR]
     [\fB\-f\fR|\fB\-\-function\fR]
     [\fB\-F\fR|\fB\-\-fullname\fR]
     [\fB\-o\fR|\fB\-\-object\fR]
     [\fB\-t\fR|\fB\-\-hot_threshold\fR] \fIfloat\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBgcov-tool\fR is an offline tool to process gcc's gcda profile files.
.PP
Current gcov-tool supports the following functionalities:
.IP "*" 4
merge two sets of profiles with weights.
.IP "*" 4
read one set of profile and rewrite profile contents. One can scale or
normalize the count values.
.PP
Examples of the use cases for this tool are:
.IP "*" 4
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.
.IP "*" 4
Rewrite the profile after removing a subset of the gcda files, while maintaining
the consistency of the summary and the histogram.
.IP "*" 4
It can also be used to debug or libgcov code as the tools shares the majority
code as the runtime library.
.PP
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:
.IP "*" 4
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.
.IP "*" 4
summary checksum difference: Summary checksum uses a \s-1CRC32\s0 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.
.IP "*" 4
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.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display help about using \fBgcov-tool\fR (on the standard output), and
exit without doing any further processing.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the \fBgcov-tool\fR version number (on the standard output),
and exit without doing any further processing.
.IP "\fBmerge\fR" 4
.IX Item "merge"
Merge two profile directories.
.RS 4
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output directory name is
\&\fImerged_profile\fR.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
Set the merge weights of the \fIdirectory1\fR and \fIdirectory2\fR,
respectively. The default weights are 1 for both.
.RE
.RS 4
.RE
.IP "\fBrewrite\fR" 4
.IX Item "rewrite"
Read the specified profile directory and rewrite to a new directory.
.RS 4
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output name is \fIrewrite_profile\fR.
.IP "\fB\-s\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "-s float_or_simple-frac_value"
.PD 0
.IP "\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "--scale float_or_simple-frac_value"
.PD
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.
.IP "\fB\-n\fR \fIlong_long_value\fR" 4
.IX Item "-n long_long_value"
.PD 0
.IP "\fB\-\-normalize <long_long_value>\fR" 4
.IX Item "--normalize <long_long_value>"
.PD
Normalize the profile. The specified value is the max counter value
in the new profile.
.RE
.RS 4
.RE
.IP "\fBoverlap\fR" 4
.IX Item "overlap"
Computer 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.
.RS 4
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-hotonly\fR" 4
.IX Item "--hotonly"
.PD
Only print info for hot objects/functions.
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-function\fR" 4
.IX Item "--function"
.PD
Print function level overlap score.
.IP "\fB\-F\fR" 4
.IX Item "-F"
.PD 0
.IP "\fB\-\-fullname\fR" 4
.IX Item "--fullname"
.PD
Print full gcda filename.
.IP "\fB\-o\fR" 4
.IX Item "-o"
.PD 0
.IP "\fB\-\-object\fR" 4
.IX Item "--object"
.PD
Print object level overlap score.
.IP "\fB\-t\fR \fIfloat\fR" 4
.IX Item "-t float"
.PD 0
.IP "\fB\-\-hot_threshold <float>\fR" 4
.IX Item "--hot_threshold <float>"
.PD
Set the threshold for hot counter value.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), \fIgcc\fR\|(1), \fIgcov\fR\|(1) and the Info entry for
\&\fIgcc\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2014\-2016 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding
Free Software\*(R", 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 \fIgfdl\fR\|(7) man page.
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\&     A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\&     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.
.Ve