1GCOV-TOOL(1)                          GNU                         GCOV-TOOL(1)
2
3
4

NAME

6       gcov-tool - offline gcda profile processing tool
7

SYNOPSIS

9       gcov-tool [-v|--version] [-h|--help]
10
11       gcov-tool merge [merge-options] directory1 directory2
12            [-o|--output directory]
13            [-v|--verbose]
14            [-w|--weight w1,w2]
15
16       gcov-tool rewrite [rewrite-options] directory
17            [-n|--normalize long_long_value]
18            [-o|--output directory]
19            [-s|--scale float_or_simple-frac_value]
20            [-v|--verbose]
21
22       gcov-tool overlap [overlap-options] directory1 directory2
23            [-f|--function]
24            [-F|--fullname]
25            [-h|--hotonly]
26            [-o|--object]
27            [-t|--hot_threshold] float
28            [-v|--verbose]
29

DESCRIPTION

31       gcov-tool is an offline tool to process gcc's gcda profile files.
32
33       Current gcov-tool supports the following functionalities:
34
35       *   merge two sets of profiles with weights.
36
37       *   read one set of profile and rewrite profile contents. One can scale
38           or normalize the count values.
39
40       Examples of the use cases for this tool are:
41
42       *   Collect the profiles for different set of inputs, and use this tool
43           to merge them. One can specify the weight to factor in the relative
44           importance of each input.
45
46       *   Rewrite the profile after removing a subset of the gcda files,
47           while maintaining the consistency of the summary and the histogram.
48
49       *   It can also be used to debug or libgcov code as the tools shares
50           the majority code as the runtime library.
51
52       Note that for the merging operation, this profile generated offline may
53       contain slight different values from the online merged profile. Here
54       are a list of typical differences:
55
56       *   histogram difference: This offline tool recomputes the histogram
57           after merging the counters. The resulting histogram, therefore, is
58           precise. The online merging does not have this capability -- the
59           histogram is merged from two histograms and the result is an
60           approximation.
61
62       *   summary checksum difference: Summary checksum uses a CRC32
63           operation. The value depends on the link list order of gcov-info
64           objects. This order is different in gcov-tool from that in the
65           online merge. It's expected to have different summary checksums. It
66           does not really matter as the compiler does not use this checksum
67           anywhere.
68
69       *   value profile counter values difference: Some counter values for
70           value profile are runtime dependent, like heap addresses. It's
71           normal to see some difference in these kind of counters.
72

OPTIONS

74       -h
75       --help
76           Display help about using gcov-tool (on the standard output), and
77           exit without doing any further processing.
78
79       -v
80       --version
81           Display the gcov-tool version number (on the standard output), and
82           exit without doing any further processing.
83
84       merge
85           Merge two profile directories.
86
87           -o directory
88           --output directory
89               Set the output profile directory. Default output directory name
90               is merged_profile.
91
92           -v
93           --verbose
94               Set the verbose mode.
95
96           -w w1,w2
97           --weight w1,w2
98               Set the merge weights of the directory1 and directory2,
99               respectively. The default weights are 1 for both.
100
101       rewrite
102           Read the specified profile directory and rewrite to a new
103           directory.
104
105           -n long_long_value
106           --normalize <long_long_value>
107               Normalize the profile. The specified value is the max counter
108               value in the new profile.
109
110           -o directory
111           --output directory
112               Set the output profile directory. Default output name is
113               rewrite_profile.
114
115           -s float_or_simple-frac_value
116           --scale float_or_simple-frac_value
117               Scale the profile counters. The specified value can be in
118               floating point value, or simple fraction value form, such 1, 2,
119               2/3, and 5/3.
120
121           -v
122           --verbose
123               Set the verbose mode.
124
125       overlap
126           Compute the overlap score between the two specified profile
127           directories.  The overlap score is computed based on the arc
128           profiles. It is defined as the sum of min (p1_counter[i] /
129           p1_sum_all, p2_counter[i] / p2_sum_all), for all arc counter i,
130           where p1_counter[i] and p2_counter[i] are two matched counters and
131           p1_sum_all and p2_sum_all are the sum of counter values in profile
132           1 and profile 2, respectively.
133
134           -f
135           --function
136               Print function level overlap score.
137
138           -F
139           --fullname
140               Print full gcda filename.
141
142           -h
143           --hotonly
144               Only print info for hot objects/functions.
145
146           -o
147           --object
148               Print object level overlap score.
149
150           -t float
151           --hot_threshold <float>
152               Set the threshold for hot counter value.
153
154           -v
155           --verbose
156               Set the verbose mode.
157

SEE ALSO

159       gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for
160       gcc.
161
163       Copyright (c) 2014-2020 Free Software Foundation, Inc.
164
165       Permission is granted to copy, distribute and/or modify this document
166       under the terms of the GNU Free Documentation License, Version 1.3 or
167       any later version published by the Free Software Foundation; with the
168       Invariant Sections being "GNU General Public License" and "Funding Free
169       Software", the Front-Cover texts being (a) (see below), and with the
170       Back-Cover Texts being (b) (see below).  A copy of the license is
171       included in the gfdl(7) man page.
172
173       (a) The FSF's Front-Cover Text is:
174
175            A GNU Manual
176
177       (b) The FSF's Back-Cover Text is:
178
179            You have freedom to copy and modify this GNU Manual, like GNU
180            software.  Copies published by the Free Software Foundation raise
181            funds for GNU development.
182
183
184
185gcc-10.3.1                        2021-04-22                      GCOV-TOOL(1)
Impressum