Mercurial > hg > CbC > CbC_gcc
annotate gcc/doc/gcov.texi @ 158:494b0b89df80 default tip
...
| author | Shinji KONO <kono@ie.u-ryukyu.ac.jp> |
|---|---|
| date | Mon, 25 May 2020 18:13:55 +0900 |
| parents | 1830386684a0 |
| children |
| rev | line source |
|---|---|
| 145 | 1 @c Copyright (C) 1996-2020 Free Software Foundation, Inc. |
| 0 | 2 @c This is part of the GCC manual. |
| 3 @c For copying conditions, see the file gcc.texi. | |
| 4 | |
| 5 @ignore | |
| 6 @c man begin COPYRIGHT | |
| 145 | 7 Copyright @copyright{} 1996-2020 Free Software Foundation, Inc. |
| 0 | 8 |
| 9 Permission is granted to copy, distribute and/or modify this document | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
10 under the terms of the GNU Free Documentation License, Version 1.3 or |
| 0 | 11 any later version published by the Free Software Foundation; with the |
| 12 Invariant Sections being ``GNU General Public License'' and ``Funding | |
| 13 Free Software'', the Front-Cover texts being (a) (see below), and with | |
| 14 the Back-Cover Texts being (b) (see below). A copy of the license is | |
| 15 included in the gfdl(7) man page. | |
| 16 | |
| 17 (a) The FSF's Front-Cover Text is: | |
| 18 | |
| 19 A GNU Manual | |
| 20 | |
| 21 (b) The FSF's Back-Cover Text is: | |
| 22 | |
| 23 You have freedom to copy and modify this GNU Manual, like GNU | |
| 24 software. Copies published by the Free Software Foundation raise | |
| 25 funds for GNU development. | |
| 26 @c man end | |
| 27 @c Set file name and title for the man page. | |
| 28 @setfilename gcov | |
| 29 @settitle coverage testing tool | |
| 30 @end ignore | |
| 31 | |
| 32 @node Gcov | |
| 33 @chapter @command{gcov}---a Test Coverage Program | |
| 34 | |
| 35 @command{gcov} is a tool you can use in conjunction with GCC to | |
| 36 test code coverage in your programs. | |
| 37 | |
| 38 @menu | |
| 39 * Gcov Intro:: Introduction to gcov. | |
| 40 * Invoking Gcov:: How to use gcov. | |
| 41 * Gcov and Optimization:: Using gcov with GCC optimization. | |
| 42 * Gcov Data Files:: The files used by gcov. | |
| 43 * Cross-profiling:: Data file relocation. | |
| 44 @end menu | |
| 45 | |
| 46 @node Gcov Intro | |
| 47 @section Introduction to @command{gcov} | |
| 48 @c man begin DESCRIPTION | |
| 49 | |
| 50 @command{gcov} is a test coverage program. Use it in concert with GCC | |
| 51 to analyze your programs to help create more efficient, faster running | |
| 52 code and to discover untested parts of your program. You can use | |
| 53 @command{gcov} as a profiling tool to help discover where your | |
| 54 optimization efforts will best affect your code. You can also use | |
| 55 @command{gcov} along with the other profiling tool, @command{gprof}, to | |
| 56 assess which parts of your code use the greatest amount of computing | |
| 57 time. | |
| 58 | |
| 59 Profiling tools help you analyze your code's performance. Using a | |
| 60 profiler such as @command{gcov} or @command{gprof}, you can find out some | |
| 61 basic performance statistics, such as: | |
| 62 | |
| 63 @itemize @bullet | |
| 64 @item | |
| 65 how often each line of code executes | |
| 66 | |
| 67 @item | |
| 68 what lines of code are actually executed | |
| 69 | |
| 70 @item | |
| 71 how much computing time each section of code uses | |
| 72 @end itemize | |
| 73 | |
| 74 Once you know these things about how your code works when compiled, you | |
| 75 can look at each module to see which modules should be optimized. | |
| 76 @command{gcov} helps you determine where to work on optimization. | |
| 77 | |
| 78 Software developers also use coverage testing in concert with | |
| 79 testsuites, to make sure software is actually good enough for a release. | |
| 80 Testsuites can verify that a program works as expected; a coverage | |
| 81 program tests to see how much of the program is exercised by the | |
| 82 testsuite. Developers can then determine what kinds of test cases need | |
| 83 to be added to the testsuites to create both better testing and a better | |
| 84 final product. | |
| 85 | |
| 86 You should compile your code without optimization if you plan to use | |
| 87 @command{gcov} because the optimization, by combining some lines of code | |
| 88 into one function, may not give you as much information as you need to | |
| 89 look for `hot spots' where the code is using a great deal of computer | |
| 90 time. Likewise, because @command{gcov} accumulates statistics by line (at | |
| 91 the lowest resolution), it works best with a programming style that | |
| 92 places only one statement on each line. If you use complicated macros | |
| 93 that expand to loops or to other control structures, the statistics are | |
| 94 less helpful---they only report on the line where the macro call | |
| 95 appears. If your complex macros behave like functions, you can replace | |
| 96 them with inline functions to solve this problem. | |
| 97 | |
| 98 @command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which | |
| 99 indicates how many times each line of a source file @file{@var{sourcefile}.c} | |
| 100 has executed. You can use these logfiles along with @command{gprof} to aid | |
| 101 in fine-tuning the performance of your programs. @command{gprof} gives | |
| 102 timing information you can use along with the information you get from | |
| 103 @command{gcov}. | |
| 104 | |
| 105 @command{gcov} works only on code compiled with GCC@. It is not | |
| 106 compatible with any other profiling or test coverage mechanism. | |
| 107 | |
| 108 @c man end | |
| 109 | |
| 110 @node Invoking Gcov | |
| 111 @section Invoking @command{gcov} | |
| 112 | |
| 113 @smallexample | |
| 111 | 114 gcov @r{[}@var{options}@r{]} @var{files} |
| 0 | 115 @end smallexample |
| 116 | |
| 117 @command{gcov} accepts the following options: | |
| 118 | |
| 119 @ignore | |
| 120 @c man begin SYNOPSIS | |
| 121 gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] | |
| 122 [@option{-a}|@option{--all-blocks}] | |
| 123 [@option{-b}|@option{--branch-probabilities}] | |
| 124 [@option{-c}|@option{--branch-counts}] | |
| 111 | 125 [@option{-d}|@option{--display-progress}] |
| 0 | 126 [@option{-f}|@option{--function-summaries}] |
| 145 | 127 [@option{-i}|@option{--json-format}] |
| 131 | 128 [@option{-j}|@option{--human-readable}] |
| 129 [@option{-k}|@option{--use-colors}] | |
| 111 | 130 [@option{-l}|@option{--long-file-names}] |
| 131 [@option{-m}|@option{--demangled-names}] | |
| 132 [@option{-n}|@option{--no-output}] | |
| 133 [@option{-o}|@option{--object-directory} @var{directory|file}] | |
| 134 [@option{-p}|@option{--preserve-paths}] | |
| 131 | 135 [@option{-q}|@option{--use-hotness-colors}] |
| 111 | 136 [@option{-r}|@option{--relative-only}] |
| 137 [@option{-s}|@option{--source-prefix} @var{directory}] | |
| 131 | 138 [@option{-t}|@option{--stdout}] |
| 0 | 139 [@option{-u}|@option{--unconditional-branches}] |
| 111 | 140 [@option{-x}|@option{--hash-filenames}] |
| 141 @var{files} | |
| 0 | 142 @c man end |
| 143 @c man begin SEEALSO | |
| 144 gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. | |
| 145 @c man end | |
| 146 @end ignore | |
| 147 | |
| 148 @c man begin OPTIONS | |
| 149 @table @gcctabopt | |
| 150 | |
| 151 @item -a | |
| 152 @itemx --all-blocks | |
| 153 Write individual execution counts for every basic block. Normally gcov | |
| 154 outputs execution counts only for the main blocks of a line. With this | |
| 155 option you can determine if blocks within a single line are not being | |
| 156 executed. | |
| 157 | |
| 158 @item -b | |
| 159 @itemx --branch-probabilities | |
| 160 Write branch frequencies to the output file, and write branch summary | |
| 161 info to the standard output. This option allows you to see how often | |
| 162 each branch in your program was taken. Unconditional branches will not | |
| 163 be shown, unless the @option{-u} option is given. | |
| 164 | |
| 165 @item -c | |
| 166 @itemx --branch-counts | |
| 167 Write branch frequencies as the number of branches taken, rather than | |
| 168 the percentage of branches taken. | |
| 169 | |
| 111 | 170 @item -d |
| 171 @itemx --display-progress | |
| 172 Display the progress on the standard output. | |
| 173 | |
| 174 @item -f | |
| 175 @itemx --function-summaries | |
| 176 Output summaries for each function in addition to the file level summary. | |
| 177 | |
| 178 @item -h | |
| 179 @itemx --help | |
| 180 Display help about using @command{gcov} (on the standard output), and | |
| 181 exit without doing any further processing. | |
| 182 | |
| 183 @item -i | |
| 145 | 184 @itemx --json-format |
| 185 Output gcov file in an easy-to-parse JSON intermediate format | |
| 186 which does not require source code for generation. The JSON | |
| 187 file is compressed with gzip compression algorithm | |
| 188 and the files have @file{.gcov.json.gz} extension. | |
| 111 | 189 |
| 145 | 190 Structure of the JSON is following: |
| 111 | 191 |
| 192 @smallexample | |
| 145 | 193 @{ |
| 194 "current_working_directory": @var{current_working_directory}, | |
| 195 "data_file": @var{data_file}, | |
| 196 "format_version": @var{format_version}, | |
| 197 "gcc_version": @var{gcc_version} | |
| 198 "files": [@var{file}] | |
| 199 @} | |
| 131 | 200 @end smallexample |
| 111 | 201 |
| 145 | 202 Fields of the root element have following semantics: |
| 203 | |
| 204 @itemize @bullet | |
| 205 @item | |
| 206 @var{current_working_directory}: working directory where | |
| 207 a compilation unit was compiled | |
| 208 | |
| 209 @item | |
| 210 @var{data_file}: name of the data file (GCDA) | |
| 211 | |
| 212 @item | |
| 213 @var{format_version}: semantic version of the format | |
| 214 | |
| 215 @item | |
| 216 @var{gcc_version}: version of the GCC compiler | |
| 217 @end itemize | |
| 111 | 218 |
| 145 | 219 Each @var{file} has the following form: |
| 220 | |
| 221 @smallexample | |
| 222 @{ | |
| 223 "file": @var{file_name}, | |
| 224 "functions": [@var{function}], | |
| 225 "lines": [@var{line}] | |
| 226 @} | |
| 227 @end smallexample | |
| 228 | |
| 229 Fields of the @var{file} element have following semantics: | |
| 230 | |
| 231 @itemize @bullet | |
| 232 @item | |
| 233 @var{file_name}: name of the source file | |
| 234 @end itemize | |
| 235 | |
| 236 Each @var{function} has the following form: | |
| 111 | 237 |
| 238 @smallexample | |
| 145 | 239 @{ |
| 240 "blocks": @var{blocks}, | |
| 241 "blocks_executed": @var{blocks_executed}, | |
| 242 "demangled_name": "@var{demangled_name}, | |
| 243 "end_column": @var{end_column}, | |
| 244 "end_line": @var{end_line}, | |
| 245 "execution_count": @var{execution_count}, | |
| 246 "name": @var{name}, | |
| 247 "start_column": @var{start_column} | |
| 248 "start_line": @var{start_line} | |
| 249 @} | |
| 111 | 250 @end smallexample |
| 0 | 251 |
| 145 | 252 Fields of the @var{function} element have following semantics: |
| 253 | |
| 254 @itemize @bullet | |
| 255 @item | |
| 256 @var{blocks}: number of blocks that are in the function | |
| 257 | |
| 258 @item | |
| 259 @var{blocks_executed}: number of executed blocks of the function | |
| 260 | |
| 261 @item | |
| 262 @var{demangled_name}: demangled name of the function | |
| 263 | |
| 264 @item | |
| 265 @var{end_column}: column in the source file where the function ends | |
| 266 | |
| 267 @item | |
| 268 @var{end_line}: line in the source file where the function ends | |
| 269 | |
| 270 @item | |
| 271 @var{execution_count}: number of executions of the function | |
| 272 | |
| 273 @item | |
| 274 @var{name}: name of the function | |
| 275 | |
| 276 @item | |
| 277 @var{start_column}: column in the source file where the function begins | |
| 278 | |
| 279 @item | |
| 280 @var{start_line}: line in the source file where the function begins | |
| 281 @end itemize | |
| 282 | |
| 283 Note that line numbers and column numbers number from 1. In the current | |
| 284 implementation, @var{start_line} and @var{start_column} do not include | |
| 285 any template parameters and the leading return type but that | |
| 286 this is likely to be fixed in the future. | |
| 287 | |
| 288 Each @var{line} has the following form: | |
| 289 | |
| 290 @smallexample | |
| 291 @{ | |
| 292 "branches": [@var{branch}], | |
| 293 "count": @var{count}, | |
| 294 "line_number": @var{line_number}, | |
| 295 "unexecuted_block": @var{unexecuted_block} | |
| 296 "function_name": @var{function_name}, | |
| 297 @} | |
| 298 @end smallexample | |
| 299 | |
| 300 Branches are present only with @var{-b} option. | |
| 301 Fields of the @var{line} element have following semantics: | |
| 302 | |
| 303 @itemize @bullet | |
| 304 @item | |
| 305 @var{count}: number of executions of the line | |
| 306 | |
| 307 @item | |
| 308 @var{line_number}: line number | |
| 309 | |
| 310 @item | |
| 311 @var{unexecuted_block}: flag whether the line contains an unexecuted block | |
| 312 (not all statements on the line are executed) | |
| 313 | |
| 314 @item | |
| 315 @var{function_name}: a name of a function this @var{line} belongs to | |
| 316 (for a line with an inlined statements can be not set) | |
| 317 @end itemize | |
| 318 | |
| 319 Each @var{branch} has the following form: | |
| 320 | |
| 321 @smallexample | |
| 322 @{ | |
| 323 "count": @var{count}, | |
| 324 "fallthrough": @var{fallthrough}, | |
| 325 "throw": @var{throw} | |
| 326 @} | |
| 327 @end smallexample | |
| 328 | |
| 329 Fields of the @var{branch} element have following semantics: | |
| 330 | |
| 331 @itemize @bullet | |
| 332 @item | |
| 333 @var{count}: number of executions of the branch | |
| 334 | |
| 335 @item | |
| 336 @var{fallthrough}: true when the branch is a fall through branch | |
| 337 | |
| 338 @item | |
| 339 @var{throw}: true when the branch is an exceptional branch | |
| 340 @end itemize | |
| 341 | |
| 131 | 342 @item -j |
| 343 @itemx --human-readable | |
| 344 Write counts in human readable format (like 24.6k). | |
| 345 | |
| 346 @item -k | |
| 347 @itemx --use-colors | |
| 348 | |
| 349 Use colors for lines of code that have zero coverage. We use red color for | |
| 350 non-exceptional lines and cyan for exceptional. Same colors are used for | |
| 351 basic blocks with @option{-a} option. | |
| 352 | |
| 0 | 353 @item -l |
| 354 @itemx --long-file-names | |
| 355 Create long file names for included source files. For example, if the | |
| 356 header file @file{x.h} contains code, and was included in the file | |
| 111 | 357 @file{a.c}, then running @command{gcov} on the file @file{a.c} will |
| 358 produce an output file called @file{a.c##x.h.gcov} instead of | |
| 359 @file{x.h.gcov}. This can be useful if @file{x.h} is included in | |
| 360 multiple source files and you want to see the individual | |
| 361 contributions. If you use the @samp{-p} option, both the including | |
| 362 and included file names will be complete path names. | |
| 0 | 363 |
| 111 | 364 @item -m |
| 365 @itemx --demangled-names | |
| 366 Display demangled function names in output. The default is to show | |
| 367 mangled function names. | |
| 0 | 368 |
| 111 | 369 @item -n |
| 370 @itemx --no-output | |
| 371 Do not create the @command{gcov} output file. | |
| 0 | 372 |
| 373 @item -o @var{directory|file} | |
| 374 @itemx --object-directory @var{directory} | |
| 375 @itemx --object-file @var{file} | |
| 376 Specify either the directory containing the gcov data files, or the | |
| 377 object path name. The @file{.gcno}, and | |
| 378 @file{.gcda} data files are searched for using this option. If a directory | |
| 379 is specified, the data files are in that directory and named after the | |
| 111 | 380 input file name, without its extension. If a file is specified here, |
| 381 the data files are named after that file, without its extension. | |
| 382 | |
| 383 @item -p | |
| 384 @itemx --preserve-paths | |
| 385 Preserve complete path information in the names of generated | |
| 386 @file{.gcov} files. Without this option, just the filename component is | |
| 387 used. With this option, all directories are used, with @samp{/} characters | |
| 388 translated to @samp{#} characters, @file{.} directory components | |
| 389 removed and unremoveable @file{..} | |
| 390 components renamed to @samp{^}. This is useful if sourcefiles are in several | |
| 391 different directories. | |
| 392 | |
| 131 | 393 @item -q |
| 394 @itemx --use-hotness-colors | |
| 395 | |
| 396 Emit perf-like colored output for hot lines. Legend of the color scale | |
| 397 is printed at the very beginning of the output file. | |
| 398 | |
| 111 | 399 @item -r |
| 400 @itemx --relative-only | |
| 401 Only output information about source files with a relative pathname | |
| 402 (after source prefix elision). Absolute paths are usually system | |
| 403 header files and coverage of any inline functions therein is normally | |
| 404 uninteresting. | |
| 405 | |
| 406 @item -s @var{directory} | |
| 407 @itemx --source-prefix @var{directory} | |
| 408 A prefix for source file names to remove when generating the output | |
| 409 coverage files. This option is useful when building in a separate | |
| 410 directory, and the pathname to the source directory is not wanted when | |
| 411 determining the output file names. Note that this prefix detection is | |
| 412 applied before determining whether the source file is absolute. | |
| 0 | 413 |
| 131 | 414 @item -t |
| 415 @itemx --stdout | |
| 416 Output to standard output instead of output files. | |
| 417 | |
| 0 | 418 @item -u |
| 419 @itemx --unconditional-branches | |
| 420 When branch probabilities are given, include those of unconditional branches. | |
| 421 Unconditional branches are normally not interesting. | |
| 422 | |
| 111 | 423 @item -v |
| 424 @itemx --version | |
| 425 Display the @command{gcov} version number (on the standard output), | |
| 426 and exit without doing any further processing. | |
| 427 | |
| 428 @item -w | |
| 429 @itemx --verbose | |
| 430 Print verbose informations related to basic blocks and arcs. | |
| 431 | |
| 432 @item -x | |
| 433 @itemx --hash-filenames | |
| 145 | 434 When using @var{--preserve-paths}, |
| 435 gcov uses the full pathname of the source files to create | |
| 111 | 436 an output filename. This can lead to long filenames that can overflow |
| 437 filesystem limits. This option creates names of the form | |
| 438 @file{@var{source-file}##@var{md5}.gcov}, | |
| 439 where the @var{source-file} component is the final filename part and | |
| 440 the @var{md5} component is calculated from the full mangled name that | |
| 145 | 441 would have been used otherwise. The option is an alternative |
| 442 to the @var{--preserve-paths} on systems which have a filesystem limit. | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
443 |
| 0 | 444 @end table |
| 445 | |
| 446 @command{gcov} should be run with the current directory the same as that | |
| 447 when you invoked the compiler. Otherwise it will not be able to locate | |
| 448 the source files. @command{gcov} produces files called | |
| 449 @file{@var{mangledname}.gcov} in the current directory. These contain | |
| 450 the coverage information of the source file they correspond to. | |
| 111 | 451 One @file{.gcov} file is produced for each source (or header) file |
| 452 containing code, | |
| 0 | 453 which was compiled to produce the data files. The @var{mangledname} part |
| 454 of the output file name is usually simply the source file name, but can | |
| 455 be something more complicated if the @samp{-l} or @samp{-p} options are | |
| 456 given. Refer to those options for details. | |
| 457 | |
| 111 | 458 If you invoke @command{gcov} with multiple input files, the |
| 459 contributions from each input file are summed. Typically you would | |
| 460 invoke it with the same list of files as the final link of your executable. | |
| 461 | |
| 0 | 462 The @file{.gcov} files contain the @samp{:} separated fields along with |
| 463 program source code. The format is | |
| 464 | |
| 465 @smallexample | |
| 466 @var{execution_count}:@var{line_number}:@var{source line text} | |
| 467 @end smallexample | |
| 468 | |
| 469 Additional block information may succeed each line, when requested by | |
| 470 command line option. The @var{execution_count} is @samp{-} for lines | |
| 111 | 471 containing no code. Unexecuted lines are marked @samp{#####} or |
| 131 | 472 @samp{=====}, depending on whether they are reachable by |
| 111 | 473 non-exceptional paths or only exceptional paths such as C++ exception |
| 131 | 474 handlers, respectively. Given the @samp{-a} option, unexecuted blocks are |
| 111 | 475 marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block |
| 476 is reachable via non-exceptional or exceptional paths. | |
| 131 | 477 Executed basic blocks having a statement with zero @var{execution_count} |
| 478 end with @samp{*} character and are colored with magenta color with | |
| 479 the @option{-k} option. This functionality is not supported in Ada. | |
| 480 | |
| 481 Note that GCC can completely remove the bodies of functions that are | |
| 482 not needed -- for instance if they are inlined everywhere. Such functions | |
| 483 are marked with @samp{-}, which can be confusing. | |
| 484 Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions} | |
| 485 options to retain these functions and | |
| 486 allow gcov to properly show their @var{execution_count}. | |
| 111 | 487 |
| 0 | 488 Some lines of information at the start have @var{line_number} of zero. |
| 111 | 489 These preamble lines are of the form |
| 0 | 490 |
| 491 @smallexample | |
| 492 -:0:@var{tag}:@var{value} | |
| 493 @end smallexample | |
| 494 | |
| 495 The ordering and number of these preamble lines will be augmented as | |
| 496 @command{gcov} development progresses --- do not rely on them remaining | |
| 497 unchanged. Use @var{tag} to locate a particular preamble line. | |
| 498 | |
| 499 The additional block information is of the form | |
| 500 | |
| 501 @smallexample | |
| 502 @var{tag} @var{information} | |
| 503 @end smallexample | |
| 504 | |
| 505 The @var{information} is human readable, but designed to be simple | |
| 506 enough for machine parsing too. | |
| 507 | |
| 508 When printing percentages, 0% and 100% are only printed when the values | |
| 509 are @emph{exactly} 0% and 100% respectively. Other values which would | |
| 510 conventionally be rounded to 0% or 100% are instead printed as the | |
| 511 nearest non-boundary value. | |
| 512 | |
| 145 | 513 When using @command{gcov}, you must first compile your program |
| 514 with a special GCC option @samp{--coverage}. | |
| 0 | 515 This tells the compiler to generate additional information needed by |
| 516 gcov (basically a flow graph of the program) and also includes | |
| 517 additional code in the object files for generating the extra profiling | |
| 518 information needed by gcov. These additional files are placed in the | |
| 519 directory where the object file is located. | |
| 520 | |
| 521 Running the program will cause profile output to be generated. For each | |
| 522 source file compiled with @option{-fprofile-arcs}, an accompanying | |
| 523 @file{.gcda} file will be placed in the object file directory. | |
| 524 | |
| 525 Running @command{gcov} with your program's source file names as arguments | |
| 526 will now produce a listing of the code along with frequency of execution | |
| 131 | 527 for each line. For example, if your program is called @file{tmp.cpp}, this |
| 0 | 528 is what you see when you use the basic @command{gcov} facility: |
| 529 | |
| 530 @smallexample | |
| 145 | 531 $ g++ --coverage tmp.cpp |
| 0 | 532 $ a.out |
| 131 | 533 $ gcov tmp.cpp -m |
| 534 File 'tmp.cpp' | |
| 535 Lines executed:92.86% of 14 | |
| 536 Creating 'tmp.cpp.gcov' | |
| 0 | 537 @end smallexample |
| 538 | |
| 131 | 539 The file @file{tmp.cpp.gcov} contains output from @command{gcov}. |
| 0 | 540 Here is a sample: |
| 541 | |
| 542 @smallexample | |
| 131 | 543 -: 0:Source:tmp.cpp |
| 544 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 545 -: 0:Graph:tmp.gcno |
| 546 -: 0:Data:tmp.gcda | |
| 547 -: 0:Runs:1 | |
| 548 -: 0:Programs:1 | |
| 549 -: 1:#include <stdio.h> | |
| 550 -: 2: | |
| 131 | 551 -: 3:template<class T> |
| 552 -: 4:class Foo | |
| 553 -: 5:@{ | |
| 554 -: 6: public: | |
| 555 1*: 7: Foo(): b (1000) @{@} | |
| 556 ------------------ | |
| 557 Foo<char>::Foo(): | |
| 558 #####: 7: Foo(): b (1000) @{@} | |
| 559 ------------------ | |
| 560 Foo<int>::Foo(): | |
| 561 1: 7: Foo(): b (1000) @{@} | |
| 562 ------------------ | |
| 563 2*: 8: void inc () @{ b++; @} | |
| 564 ------------------ | |
| 565 Foo<char>::inc(): | |
| 566 #####: 8: void inc () @{ b++; @} | |
| 567 ------------------ | |
| 568 Foo<int>::inc(): | |
| 569 2: 8: void inc () @{ b++; @} | |
| 570 ------------------ | |
| 571 -: 9: | |
| 572 -: 10: private: | |
| 573 -: 11: int b; | |
| 574 -: 12:@}; | |
| 575 -: 13: | |
| 576 -: 14:template class Foo<int>; | |
| 577 -: 15:template class Foo<char>; | |
| 578 -: 16: | |
| 579 -: 17:int | |
| 580 1: 18:main (void) | |
| 581 -: 19:@{ | |
| 582 -: 20: int i, total; | |
| 583 1: 21: Foo<int> counter; | |
| 584 -: 22: | |
| 585 1: 23: counter.inc(); | |
| 586 1: 24: counter.inc(); | |
| 587 1: 25: total = 0; | |
| 588 -: 26: | |
| 589 11: 27: for (i = 0; i < 10; i++) | |
| 590 10: 28: total += i; | |
| 591 -: 29: | |
| 592 1*: 30: int v = total > 100 ? 1 : 2; | |
| 593 -: 31: | |
| 594 1: 32: if (total != 45) | |
| 595 #####: 33: printf ("Failure\n"); | |
| 596 -: 34: else | |
| 597 1: 35: printf ("Success\n"); | |
| 598 1: 36: return 0; | |
| 599 -: 37:@} | |
| 0 | 600 @end smallexample |
| 601 | |
| 131 | 602 Note that line 7 is shown in the report multiple times. First occurrence |
| 603 presents total number of execution of the line and the next two belong | |
| 604 to instances of class Foo constructors. As you can also see, line 30 contains | |
| 605 some unexecuted basic blocks and thus execution count has asterisk symbol. | |
| 606 | |
| 0 | 607 When you use the @option{-a} option, you will get individual block |
| 608 counts, and the output looks like this: | |
| 609 | |
| 610 @smallexample | |
| 131 | 611 -: 0:Source:tmp.cpp |
| 612 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 613 -: 0:Graph:tmp.gcno |
| 614 -: 0:Data:tmp.gcda | |
| 615 -: 0:Runs:1 | |
| 616 -: 0:Programs:1 | |
| 617 -: 1:#include <stdio.h> | |
| 618 -: 2: | |
| 131 | 619 -: 3:template<class T> |
| 620 -: 4:class Foo | |
| 621 -: 5:@{ | |
| 622 -: 6: public: | |
| 623 1*: 7: Foo(): b (1000) @{@} | |
| 624 ------------------ | |
| 625 Foo<char>::Foo(): | |
| 626 #####: 7: Foo(): b (1000) @{@} | |
| 627 ------------------ | |
| 628 Foo<int>::Foo(): | |
| 629 1: 7: Foo(): b (1000) @{@} | |
| 630 ------------------ | |
| 631 2*: 8: void inc () @{ b++; @} | |
| 632 ------------------ | |
| 633 Foo<char>::inc(): | |
| 634 #####: 8: void inc () @{ b++; @} | |
| 635 ------------------ | |
| 636 Foo<int>::inc(): | |
| 637 2: 8: void inc () @{ b++; @} | |
| 638 ------------------ | |
| 639 -: 9: | |
| 640 -: 10: private: | |
| 641 -: 11: int b; | |
| 642 -: 12:@}; | |
| 643 -: 13: | |
| 644 -: 14:template class Foo<int>; | |
| 645 -: 15:template class Foo<char>; | |
| 646 -: 16: | |
| 647 -: 17:int | |
| 648 1: 18:main (void) | |
| 649 -: 19:@{ | |
| 650 -: 20: int i, total; | |
| 651 1: 21: Foo<int> counter; | |
| 652 1: 21-block 0 | |
| 653 -: 22: | |
| 654 1: 23: counter.inc(); | |
| 655 1: 23-block 0 | |
| 656 1: 24: counter.inc(); | |
| 657 1: 24-block 0 | |
| 658 1: 25: total = 0; | |
| 659 -: 26: | |
| 660 11: 27: for (i = 0; i < 10; i++) | |
| 661 1: 27-block 0 | |
| 662 11: 27-block 1 | |
| 663 10: 28: total += i; | |
| 664 10: 28-block 0 | |
| 665 -: 29: | |
| 666 1*: 30: int v = total > 100 ? 1 : 2; | |
| 667 1: 30-block 0 | |
| 668 %%%%%: 30-block 1 | |
| 669 1: 30-block 2 | |
| 670 -: 31: | |
| 671 1: 32: if (total != 45) | |
| 672 1: 32-block 0 | |
| 673 #####: 33: printf ("Failure\n"); | |
| 674 %%%%%: 33-block 0 | |
| 675 -: 34: else | |
| 676 1: 35: printf ("Success\n"); | |
| 677 1: 35-block 0 | |
| 678 1: 36: return 0; | |
| 679 1: 36-block 0 | |
| 680 -: 37:@} | |
| 0 | 681 @end smallexample |
| 682 | |
| 683 In this mode, each basic block is only shown on one line -- the last | |
| 684 line of the block. A multi-line block will only contribute to the | |
| 685 execution count of that last line, and other lines will not be shown | |
| 686 to contain code, unless previous blocks end on those lines. | |
| 687 The total execution count of a line is shown and subsequent lines show | |
| 688 the execution counts for individual blocks that end on that line. After each | |
| 689 block, the branch and call counts of the block will be shown, if the | |
| 690 @option{-b} option is given. | |
| 691 | |
| 692 Because of the way GCC instruments calls, a call count can be shown | |
| 693 after a line with no individual blocks. | |
| 131 | 694 As you can see, line 33 contains a basic block that was not executed. |
| 0 | 695 |
| 696 @need 450 | |
| 697 When you use the @option{-b} option, your output looks like this: | |
| 698 | |
| 699 @smallexample | |
| 131 | 700 -: 0:Source:tmp.cpp |
| 701 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 702 -: 0:Graph:tmp.gcno |
| 703 -: 0:Data:tmp.gcda | |
| 704 -: 0:Runs:1 | |
| 705 -: 0:Programs:1 | |
| 706 -: 1:#include <stdio.h> | |
| 707 -: 2: | |
| 131 | 708 -: 3:template<class T> |
| 709 -: 4:class Foo | |
| 710 -: 5:@{ | |
| 711 -: 6: public: | |
| 712 1*: 7: Foo(): b (1000) @{@} | |
| 713 ------------------ | |
| 714 Foo<char>::Foo(): | |
| 715 function Foo<char>::Foo() called 0 returned 0% blocks executed 0% | |
| 716 #####: 7: Foo(): b (1000) @{@} | |
| 717 ------------------ | |
| 718 Foo<int>::Foo(): | |
| 719 function Foo<int>::Foo() called 1 returned 100% blocks executed 100% | |
| 720 1: 7: Foo(): b (1000) @{@} | |
| 721 ------------------ | |
| 722 2*: 8: void inc () @{ b++; @} | |
| 723 ------------------ | |
| 724 Foo<char>::inc(): | |
| 725 function Foo<char>::inc() called 0 returned 0% blocks executed 0% | |
| 726 #####: 8: void inc () @{ b++; @} | |
| 727 ------------------ | |
| 728 Foo<int>::inc(): | |
| 729 function Foo<int>::inc() called 2 returned 100% blocks executed 100% | |
| 730 2: 8: void inc () @{ b++; @} | |
| 731 ------------------ | |
| 732 -: 9: | |
| 733 -: 10: private: | |
| 734 -: 11: int b; | |
| 735 -: 12:@}; | |
| 736 -: 13: | |
| 737 -: 14:template class Foo<int>; | |
| 738 -: 15:template class Foo<char>; | |
| 739 -: 16: | |
| 740 -: 17:int | |
| 741 function main called 1 returned 100% blocks executed 81% | |
| 742 1: 18:main (void) | |
| 743 -: 19:@{ | |
| 744 -: 20: int i, total; | |
| 745 1: 21: Foo<int> counter; | |
| 746 call 0 returned 100% | |
| 747 branch 1 taken 100% (fallthrough) | |
| 748 branch 2 taken 0% (throw) | |
| 749 -: 22: | |
| 750 1: 23: counter.inc(); | |
| 751 call 0 returned 100% | |
| 752 branch 1 taken 100% (fallthrough) | |
| 753 branch 2 taken 0% (throw) | |
| 754 1: 24: counter.inc(); | |
| 755 call 0 returned 100% | |
| 756 branch 1 taken 100% (fallthrough) | |
| 757 branch 2 taken 0% (throw) | |
| 758 1: 25: total = 0; | |
| 759 -: 26: | |
| 760 11: 27: for (i = 0; i < 10; i++) | |
| 0 | 761 branch 0 taken 91% (fallthrough) |
| 762 branch 1 taken 9% | |
| 131 | 763 10: 28: total += i; |
| 764 -: 29: | |
| 765 1*: 30: int v = total > 100 ? 1 : 2; | |
| 766 branch 0 taken 0% (fallthrough) | |
| 767 branch 1 taken 100% | |
| 768 -: 31: | |
| 769 1: 32: if (total != 45) | |
| 0 | 770 branch 0 taken 0% (fallthrough) |
| 771 branch 1 taken 100% | |
| 131 | 772 #####: 33: printf ("Failure\n"); |
| 0 | 773 call 0 never executed |
| 131 | 774 branch 1 never executed |
| 775 branch 2 never executed | |
| 776 -: 34: else | |
| 777 1: 35: printf ("Success\n"); | |
| 778 call 0 returned 100% | |
| 779 branch 1 taken 100% (fallthrough) | |
| 780 branch 2 taken 0% (throw) | |
| 781 1: 36: return 0; | |
| 782 -: 37:@} | |
| 0 | 783 @end smallexample |
| 784 | |
| 785 For each function, a line is printed showing how many times the function | |
| 786 is called, how many times it returns and what percentage of the | |
| 787 function's blocks were executed. | |
| 788 | |
| 789 For each basic block, a line is printed after the last line of the basic | |
| 790 block describing the branch or call that ends the basic block. There can | |
| 791 be multiple branches and calls listed for a single source line if there | |
| 792 are multiple basic blocks that end on that line. In this case, the | |
| 793 branches and calls are each given a number. There is no simple way to map | |
| 794 these branches and calls back to source constructs. In general, though, | |
| 795 the lowest numbered branch or call will correspond to the leftmost construct | |
| 796 on the source line. | |
| 797 | |
| 798 For a branch, if it was executed at least once, then a percentage | |
| 799 indicating the number of times the branch was taken divided by the | |
| 800 number of times the branch was executed will be printed. Otherwise, the | |
| 801 message ``never executed'' is printed. | |
| 802 | |
| 803 For a call, if it was executed at least once, then a percentage | |
| 804 indicating the number of times the call returned divided by the number | |
| 805 of times the call was executed will be printed. This will usually be | |
| 806 100%, but may be less for functions that call @code{exit} or @code{longjmp}, | |
| 807 and thus may not return every time they are called. | |
| 808 | |
| 809 The execution counts are cumulative. If the example program were | |
| 810 executed again without removing the @file{.gcda} file, the count for the | |
| 811 number of times each line in the source was executed would be added to | |
| 812 the results of the previous run(s). This is potentially useful in | |
| 813 several ways. For example, it could be used to accumulate data over a | |
| 814 number of program runs as part of a test verification suite, or to | |
| 815 provide more accurate long-term information over a large number of | |
| 816 program runs. | |
| 817 | |
| 818 The data in the @file{.gcda} files is saved immediately before the program | |
| 819 exits. For each source file compiled with @option{-fprofile-arcs}, the | |
| 820 profiling code first attempts to read in an existing @file{.gcda} file; if | |
| 821 the file doesn't match the executable (differing number of basic block | |
| 822 counts) it will ignore the contents of the file. It then adds in the | |
| 823 new execution counts and finally writes the data to the file. | |
| 824 | |
| 825 @node Gcov and Optimization | |
| 826 @section Using @command{gcov} with GCC Optimization | |
| 827 | |
| 828 If you plan to use @command{gcov} to help optimize your code, you must | |
| 145 | 829 first compile your program with a special GCC option |
| 830 @samp{--coverage}. Aside from that, you can use any | |
| 0 | 831 other GCC options; but if you want to prove that every single line |
| 832 in your program was executed, you should not compile with optimization | |
| 833 at the same time. On some machines the optimizer can eliminate some | |
| 834 simple code lines by combining them with other lines. For example, code | |
| 835 like this: | |
| 836 | |
| 837 @smallexample | |
| 838 if (a != b) | |
| 839 c = 1; | |
| 840 else | |
| 841 c = 0; | |
| 842 @end smallexample | |
| 843 | |
| 844 @noindent | |
| 845 can be compiled into one instruction on some machines. In this case, | |
| 846 there is no way for @command{gcov} to calculate separate execution counts | |
| 847 for each line because there isn't separate code for each line. Hence | |
| 848 the @command{gcov} output looks like this if you compiled the program with | |
| 849 optimization: | |
| 850 | |
| 851 @smallexample | |
| 852 100: 12:if (a != b) | |
| 853 100: 13: c = 1; | |
| 854 100: 14:else | |
| 855 100: 15: c = 0; | |
| 856 @end smallexample | |
| 857 | |
| 858 The output shows that this block of code, combined by optimization, | |
| 859 executed 100 times. In one sense this result is correct, because there | |
| 860 was only one instruction representing all four of these lines. However, | |
| 861 the output does not indicate how many times the result was 0 and how | |
| 862 many times the result was 1. | |
| 863 | |
| 864 Inlineable functions can create unexpected line counts. Line counts are | |
| 865 shown for the source code of the inlineable function, but what is shown | |
| 866 depends on where the function is inlined, or if it is not inlined at all. | |
| 867 | |
| 868 If the function is not inlined, the compiler must emit an out of line | |
| 869 copy of the function, in any object file that needs it. If | |
| 870 @file{fileA.o} and @file{fileB.o} both contain out of line bodies of a | |
| 871 particular inlineable function, they will also both contain coverage | |
| 872 counts for that function. When @file{fileA.o} and @file{fileB.o} are | |
| 873 linked together, the linker will, on many systems, select one of those | |
| 874 out of line bodies for all calls to that function, and remove or ignore | |
| 875 the other. Unfortunately, it will not remove the coverage counters for | |
| 876 the unused function body. Hence when instrumented, all but one use of | |
| 877 that function will show zero counts. | |
| 878 | |
| 879 If the function is inlined in several places, the block structure in | |
| 880 each location might not be the same. For instance, a condition might | |
| 881 now be calculable at compile time in some instances. Because the | |
| 882 coverage of all the uses of the inline function will be shown for the | |
| 883 same source lines, the line counts themselves might seem inconsistent. | |
| 884 | |
| 111 | 885 Long-running applications can use the @code{__gcov_reset} and @code{__gcov_dump} |
| 886 facilities to restrict profile collection to the program region of | |
| 887 interest. Calling @code{__gcov_reset(void)} will clear all profile counters | |
| 888 to zero, and calling @code{__gcov_dump(void)} will cause the profile information | |
| 889 collected at that point to be dumped to @file{.gcda} output files. | |
| 890 Instrumented applications use a static destructor with priority 99 | |
| 891 to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump} | |
| 892 is executed after all user defined static destructors, | |
| 893 as well as handlers registered with @code{atexit}. | |
| 131 | 894 If an executable loads a dynamic shared object via dlopen functionality, |
| 895 @option{-Wl,--dynamic-list-data} is needed to dump all profile data. | |
| 896 | |
| 897 Profiling run-time library reports various errors related to profile | |
| 898 manipulation and profile saving. Errors are printed into standard error output | |
| 899 or @samp{GCOV_ERROR_FILE} file, if environment variable is used. | |
| 900 In order to terminate immediately after an errors occurs | |
| 901 set @samp{GCOV_EXIT_AT_ERROR} environment variable. | |
| 902 That can help users to find profile clashing which leads | |
| 903 to a misleading profile. | |
| 111 | 904 |
| 0 | 905 @c man end |
| 906 | |
| 907 @node Gcov Data Files | |
| 111 | 908 @section Brief Description of @command{gcov} Data Files |
| 0 | 909 |
| 910 @command{gcov} uses two files for profiling. The names of these files | |
| 911 are derived from the original @emph{object} file by substituting the | |
| 111 | 912 file suffix with either @file{.gcno}, or @file{.gcda}. The files |
| 913 contain coverage and profile data stored in a platform-independent format. | |
| 914 The @file{.gcno} files are placed in the same directory as the object | |
| 915 file. By default, the @file{.gcda} files are also stored in the same | |
| 916 directory as the object file, but the GCC @option{-fprofile-dir} option | |
| 917 may be used to store the @file{.gcda} files in a separate directory. | |
| 0 | 918 |
| 111 | 919 The @file{.gcno} notes file is generated when the source file is compiled |
| 920 with the GCC @option{-ftest-coverage} option. It contains information to | |
| 0 | 921 reconstruct the basic block graphs and assign source line numbers to |
| 922 blocks. | |
| 923 | |
| 111 | 924 The @file{.gcda} count data file is generated when a program containing |
| 925 object files built with the GCC @option{-fprofile-arcs} option is executed. | |
| 926 A separate @file{.gcda} file is created for each object file compiled with | |
| 927 this option. It contains arc transition counts, value profile counts, and | |
| 928 some summary information. | |
| 0 | 929 |
| 131 | 930 It is not recommended to access the coverage files directly. |
| 931 Consumers should use the intermediate format that is provided | |
| 145 | 932 by @command{gcov} tool via @option{--json-format} option. |
| 0 | 933 |
| 934 @node Cross-profiling | |
| 111 | 935 @section Data File Relocation to Support Cross-Profiling |
| 0 | 936 |
| 111 | 937 Running the program will cause profile output to be generated. For each |
| 938 source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} | |
| 939 file will be placed in the object file directory. That implicitly requires | |
| 940 running the program on the same system as it was built or having the same | |
| 0 | 941 absolute directory structure on the target system. The program will try |
| 942 to create the needed directory structure, if it is not already present. | |
| 943 | |
| 944 To support cross-profiling, a program compiled with @option{-fprofile-arcs} | |
| 111 | 945 can relocate the data files based on two environment variables: |
| 0 | 946 |
| 947 @itemize @bullet | |
| 948 @item | |
| 111 | 949 GCOV_PREFIX contains the prefix to add to the absolute paths |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
950 in the object file. Prefix can be absolute, or relative. The |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
951 default is no prefix. |
| 0 | 952 |
| 953 @item | |
| 954 GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off | |
| 955 the hardwired absolute paths. Default value is 0. | |
| 956 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
957 @emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined, |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
958 then a relative path is made out of the hardwired absolute paths. |
| 0 | 959 @end itemize |
| 960 | |
| 961 For example, if the object file @file{/user/build/foo.o} was built with | |
| 962 @option{-fprofile-arcs}, the final executable will try to create the data file | |
| 963 @file{/user/build/foo.gcda} when running on the target system. This will | |
| 964 fail if the corresponding directory does not exist and it is unable to create | |
| 965 it. This can be overcome by, for example, setting the environment as | |
| 966 @samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a | |
| 967 setting will name the data file @file{/target/run/build/foo.gcda}. | |
| 968 | |
| 969 You must move the data files to the expected directory tree in order to | |
| 111 | 970 use them for profile directed optimizations (@option{-fprofile-use}), or to |
| 0 | 971 use the @command{gcov} tool. |