Mercurial > hg > CbC > CbC_gcc
annotate gcc/doc/gcov.texi @ 131:84e7813d76e9
gcc-8.2
| author | mir3636 |
|---|---|
| date | Thu, 25 Oct 2018 07:37:49 +0900 |
| parents | 04ced10e8804 |
| children | 1830386684a0 |
| rev | line source |
|---|---|
| 131 | 1 @c Copyright (C) 1996-2018 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 | |
| 131 | 7 Copyright @copyright{} 1996-2018 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}] |
| 111 | 127 [@option{-i}|@option{--intermediate-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 | |
| 184 @itemx --intermediate-format | |
| 185 Output gcov file in an easy-to-parse intermediate text format that can | |
| 186 be used by @command{lcov} or other tools. The output is a single | |
| 187 @file{.gcov} file per @file{.gcda} file. No source code is required. | |
| 188 | |
| 189 The format of the intermediate @file{.gcov} file is plain text with | |
| 190 one entry per line | |
| 191 | |
| 192 @smallexample | |
| 131 | 193 version:@var{gcc_version} |
| 194 cwd:@var{working_directory} | |
| 111 | 195 file:@var{source_file_name} |
| 131 | 196 function:@var{start_line_number},@var{end_line_number},@var{execution_count},@var{function_name} |
| 197 lcount:@var{line number},@var{execution_count},@var{has_unexecuted_block} | |
| 111 | 198 branch:@var{line_number},@var{branch_coverage_type} |
| 199 | |
| 200 Where the @var{branch_coverage_type} is | |
| 201 notexec (Branch not executed) | |
| 202 taken (Branch executed and taken) | |
| 203 nottaken (Branch executed, but not taken) | |
| 131 | 204 @end smallexample |
| 111 | 205 |
| 206 There can be multiple @var{file} entries in an intermediate gcov | |
| 207 file. All entries following a @var{file} pertain to that source file | |
| 131 | 208 until the next @var{file} entry. If there are multiple functions that |
| 209 start on a single line, then corresponding lcount is repeated multiple | |
| 210 times. | |
| 111 | 211 |
| 212 Here is a sample when @option{-i} is used in conjunction with @option{-b} option: | |
| 213 | |
| 214 @smallexample | |
| 131 | 215 version: 8.1.0 20180103 |
| 216 cwd:/home/gcc/testcase | |
| 217 file:tmp.cpp | |
| 218 function:7,7,0,_ZN3FooIcEC2Ev | |
| 219 function:7,7,1,_ZN3FooIiEC2Ev | |
| 220 function:8,8,0,_ZN3FooIcE3incEv | |
| 221 function:8,8,2,_ZN3FooIiE3incEv | |
| 222 function:18,37,1,main | |
| 223 lcount:7,0,1 | |
| 224 lcount:7,1,0 | |
| 225 lcount:8,0,1 | |
| 226 lcount:8,2,0 | |
| 227 lcount:18,1,0 | |
| 228 lcount:21,1,0 | |
| 229 branch:21,taken | |
| 230 branch:21,nottaken | |
| 231 lcount:23,1,0 | |
| 232 branch:23,taken | |
| 233 branch:23,nottaken | |
| 234 lcount:24,1,0 | |
| 235 branch:24,taken | |
| 236 branch:24,nottaken | |
| 237 lcount:25,1,0 | |
| 238 lcount:27,11,0 | |
| 239 branch:27,taken | |
| 240 branch:27,taken | |
| 241 lcount:28,10,0 | |
| 242 lcount:30,1,1 | |
| 243 branch:30,nottaken | |
| 244 branch:30,taken | |
| 245 lcount:32,1,0 | |
| 246 branch:32,nottaken | |
| 247 branch:32,taken | |
| 248 lcount:33,0,1 | |
| 249 branch:33,notexec | |
| 250 branch:33,notexec | |
| 251 lcount:35,1,0 | |
| 252 branch:35,taken | |
| 253 branch:35,nottaken | |
| 254 lcount:36,1,0 | |
| 111 | 255 @end smallexample |
| 0 | 256 |
| 131 | 257 @item -j |
| 258 @itemx --human-readable | |
| 259 Write counts in human readable format (like 24.6k). | |
| 260 | |
| 261 @item -k | |
| 262 @itemx --use-colors | |
| 263 | |
| 264 Use colors for lines of code that have zero coverage. We use red color for | |
| 265 non-exceptional lines and cyan for exceptional. Same colors are used for | |
| 266 basic blocks with @option{-a} option. | |
| 267 | |
| 0 | 268 @item -l |
| 269 @itemx --long-file-names | |
| 270 Create long file names for included source files. For example, if the | |
| 271 header file @file{x.h} contains code, and was included in the file | |
| 111 | 272 @file{a.c}, then running @command{gcov} on the file @file{a.c} will |
| 273 produce an output file called @file{a.c##x.h.gcov} instead of | |
| 274 @file{x.h.gcov}. This can be useful if @file{x.h} is included in | |
| 275 multiple source files and you want to see the individual | |
| 276 contributions. If you use the @samp{-p} option, both the including | |
| 277 and included file names will be complete path names. | |
| 0 | 278 |
| 111 | 279 @item -m |
| 280 @itemx --demangled-names | |
| 281 Display demangled function names in output. The default is to show | |
| 282 mangled function names. | |
| 0 | 283 |
| 111 | 284 @item -n |
| 285 @itemx --no-output | |
| 286 Do not create the @command{gcov} output file. | |
| 0 | 287 |
| 288 @item -o @var{directory|file} | |
| 289 @itemx --object-directory @var{directory} | |
| 290 @itemx --object-file @var{file} | |
| 291 Specify either the directory containing the gcov data files, or the | |
| 292 object path name. The @file{.gcno}, and | |
| 293 @file{.gcda} data files are searched for using this option. If a directory | |
| 294 is specified, the data files are in that directory and named after the | |
| 111 | 295 input file name, without its extension. If a file is specified here, |
| 296 the data files are named after that file, without its extension. | |
| 297 | |
| 298 @item -p | |
| 299 @itemx --preserve-paths | |
| 300 Preserve complete path information in the names of generated | |
| 301 @file{.gcov} files. Without this option, just the filename component is | |
| 302 used. With this option, all directories are used, with @samp{/} characters | |
| 303 translated to @samp{#} characters, @file{.} directory components | |
| 304 removed and unremoveable @file{..} | |
| 305 components renamed to @samp{^}. This is useful if sourcefiles are in several | |
| 306 different directories. | |
| 307 | |
| 131 | 308 @item -q |
| 309 @itemx --use-hotness-colors | |
| 310 | |
| 311 Emit perf-like colored output for hot lines. Legend of the color scale | |
| 312 is printed at the very beginning of the output file. | |
| 313 | |
| 111 | 314 @item -r |
| 315 @itemx --relative-only | |
| 316 Only output information about source files with a relative pathname | |
| 317 (after source prefix elision). Absolute paths are usually system | |
| 318 header files and coverage of any inline functions therein is normally | |
| 319 uninteresting. | |
| 320 | |
| 321 @item -s @var{directory} | |
| 322 @itemx --source-prefix @var{directory} | |
| 323 A prefix for source file names to remove when generating the output | |
| 324 coverage files. This option is useful when building in a separate | |
| 325 directory, and the pathname to the source directory is not wanted when | |
| 326 determining the output file names. Note that this prefix detection is | |
| 327 applied before determining whether the source file is absolute. | |
| 0 | 328 |
| 131 | 329 @item -t |
| 330 @itemx --stdout | |
| 331 Output to standard output instead of output files. | |
| 332 | |
| 0 | 333 @item -u |
| 334 @itemx --unconditional-branches | |
| 335 When branch probabilities are given, include those of unconditional branches. | |
| 336 Unconditional branches are normally not interesting. | |
| 337 | |
| 111 | 338 @item -v |
| 339 @itemx --version | |
| 340 Display the @command{gcov} version number (on the standard output), | |
| 341 and exit without doing any further processing. | |
| 342 | |
| 343 @item -w | |
| 344 @itemx --verbose | |
| 345 Print verbose informations related to basic blocks and arcs. | |
| 346 | |
| 347 @item -x | |
| 348 @itemx --hash-filenames | |
| 131 | 349 By default, gcov uses the full pathname of the source files to create |
| 111 | 350 an output filename. This can lead to long filenames that can overflow |
| 351 filesystem limits. This option creates names of the form | |
| 352 @file{@var{source-file}##@var{md5}.gcov}, | |
| 353 where the @var{source-file} component is the final filename part and | |
| 354 the @var{md5} component is calculated from the full mangled name that | |
| 355 would have been used otherwise. | |
|
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
|
356 |
| 0 | 357 @end table |
| 358 | |
| 359 @command{gcov} should be run with the current directory the same as that | |
| 360 when you invoked the compiler. Otherwise it will not be able to locate | |
| 361 the source files. @command{gcov} produces files called | |
| 362 @file{@var{mangledname}.gcov} in the current directory. These contain | |
| 363 the coverage information of the source file they correspond to. | |
| 111 | 364 One @file{.gcov} file is produced for each source (or header) file |
| 365 containing code, | |
| 0 | 366 which was compiled to produce the data files. The @var{mangledname} part |
| 367 of the output file name is usually simply the source file name, but can | |
| 368 be something more complicated if the @samp{-l} or @samp{-p} options are | |
| 369 given. Refer to those options for details. | |
| 370 | |
| 111 | 371 If you invoke @command{gcov} with multiple input files, the |
| 372 contributions from each input file are summed. Typically you would | |
| 373 invoke it with the same list of files as the final link of your executable. | |
| 374 | |
| 0 | 375 The @file{.gcov} files contain the @samp{:} separated fields along with |
| 376 program source code. The format is | |
| 377 | |
| 378 @smallexample | |
| 379 @var{execution_count}:@var{line_number}:@var{source line text} | |
| 380 @end smallexample | |
| 381 | |
| 382 Additional block information may succeed each line, when requested by | |
| 383 command line option. The @var{execution_count} is @samp{-} for lines | |
| 111 | 384 containing no code. Unexecuted lines are marked @samp{#####} or |
| 131 | 385 @samp{=====}, depending on whether they are reachable by |
| 111 | 386 non-exceptional paths or only exceptional paths such as C++ exception |
| 131 | 387 handlers, respectively. Given the @samp{-a} option, unexecuted blocks are |
| 111 | 388 marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block |
| 389 is reachable via non-exceptional or exceptional paths. | |
| 131 | 390 Executed basic blocks having a statement with zero @var{execution_count} |
| 391 end with @samp{*} character and are colored with magenta color with | |
| 392 the @option{-k} option. This functionality is not supported in Ada. | |
| 393 | |
| 394 Note that GCC can completely remove the bodies of functions that are | |
| 395 not needed -- for instance if they are inlined everywhere. Such functions | |
| 396 are marked with @samp{-}, which can be confusing. | |
| 397 Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions} | |
| 398 options to retain these functions and | |
| 399 allow gcov to properly show their @var{execution_count}. | |
| 111 | 400 |
| 0 | 401 Some lines of information at the start have @var{line_number} of zero. |
| 111 | 402 These preamble lines are of the form |
| 0 | 403 |
| 404 @smallexample | |
| 405 -:0:@var{tag}:@var{value} | |
| 406 @end smallexample | |
| 407 | |
| 408 The ordering and number of these preamble lines will be augmented as | |
| 409 @command{gcov} development progresses --- do not rely on them remaining | |
| 410 unchanged. Use @var{tag} to locate a particular preamble line. | |
| 411 | |
| 412 The additional block information is of the form | |
| 413 | |
| 414 @smallexample | |
| 415 @var{tag} @var{information} | |
| 416 @end smallexample | |
| 417 | |
| 418 The @var{information} is human readable, but designed to be simple | |
| 419 enough for machine parsing too. | |
| 420 | |
| 421 When printing percentages, 0% and 100% are only printed when the values | |
| 422 are @emph{exactly} 0% and 100% respectively. Other values which would | |
| 423 conventionally be rounded to 0% or 100% are instead printed as the | |
| 424 nearest non-boundary value. | |
| 425 | |
| 426 When using @command{gcov}, you must first compile your program with two | |
| 427 special GCC options: @samp{-fprofile-arcs -ftest-coverage}. | |
| 428 This tells the compiler to generate additional information needed by | |
| 429 gcov (basically a flow graph of the program) and also includes | |
| 430 additional code in the object files for generating the extra profiling | |
| 431 information needed by gcov. These additional files are placed in the | |
| 432 directory where the object file is located. | |
| 433 | |
| 434 Running the program will cause profile output to be generated. For each | |
| 435 source file compiled with @option{-fprofile-arcs}, an accompanying | |
| 436 @file{.gcda} file will be placed in the object file directory. | |
| 437 | |
| 438 Running @command{gcov} with your program's source file names as arguments | |
| 439 will now produce a listing of the code along with frequency of execution | |
| 131 | 440 for each line. For example, if your program is called @file{tmp.cpp}, this |
| 0 | 441 is what you see when you use the basic @command{gcov} facility: |
| 442 | |
| 443 @smallexample | |
| 131 | 444 $ g++ -fprofile-arcs -ftest-coverage tmp.cpp |
| 0 | 445 $ a.out |
| 131 | 446 $ gcov tmp.cpp -m |
| 447 File 'tmp.cpp' | |
| 448 Lines executed:92.86% of 14 | |
| 449 Creating 'tmp.cpp.gcov' | |
| 0 | 450 @end smallexample |
| 451 | |
| 131 | 452 The file @file{tmp.cpp.gcov} contains output from @command{gcov}. |
| 0 | 453 Here is a sample: |
| 454 | |
| 455 @smallexample | |
| 131 | 456 -: 0:Source:tmp.cpp |
| 457 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 458 -: 0:Graph:tmp.gcno |
| 459 -: 0:Data:tmp.gcda | |
| 460 -: 0:Runs:1 | |
| 461 -: 0:Programs:1 | |
| 462 -: 1:#include <stdio.h> | |
| 463 -: 2: | |
| 131 | 464 -: 3:template<class T> |
| 465 -: 4:class Foo | |
| 466 -: 5:@{ | |
| 467 -: 6: public: | |
| 468 1*: 7: Foo(): b (1000) @{@} | |
| 469 ------------------ | |
| 470 Foo<char>::Foo(): | |
| 471 #####: 7: Foo(): b (1000) @{@} | |
| 472 ------------------ | |
| 473 Foo<int>::Foo(): | |
| 474 1: 7: Foo(): b (1000) @{@} | |
| 475 ------------------ | |
| 476 2*: 8: void inc () @{ b++; @} | |
| 477 ------------------ | |
| 478 Foo<char>::inc(): | |
| 479 #####: 8: void inc () @{ b++; @} | |
| 480 ------------------ | |
| 481 Foo<int>::inc(): | |
| 482 2: 8: void inc () @{ b++; @} | |
| 483 ------------------ | |
| 484 -: 9: | |
| 485 -: 10: private: | |
| 486 -: 11: int b; | |
| 487 -: 12:@}; | |
| 488 -: 13: | |
| 489 -: 14:template class Foo<int>; | |
| 490 -: 15:template class Foo<char>; | |
| 491 -: 16: | |
| 492 -: 17:int | |
| 493 1: 18:main (void) | |
| 494 -: 19:@{ | |
| 495 -: 20: int i, total; | |
| 496 1: 21: Foo<int> counter; | |
| 497 -: 22: | |
| 498 1: 23: counter.inc(); | |
| 499 1: 24: counter.inc(); | |
| 500 1: 25: total = 0; | |
| 501 -: 26: | |
| 502 11: 27: for (i = 0; i < 10; i++) | |
| 503 10: 28: total += i; | |
| 504 -: 29: | |
| 505 1*: 30: int v = total > 100 ? 1 : 2; | |
| 506 -: 31: | |
| 507 1: 32: if (total != 45) | |
| 508 #####: 33: printf ("Failure\n"); | |
| 509 -: 34: else | |
| 510 1: 35: printf ("Success\n"); | |
| 511 1: 36: return 0; | |
| 512 -: 37:@} | |
| 0 | 513 @end smallexample |
| 514 | |
| 131 | 515 Note that line 7 is shown in the report multiple times. First occurrence |
| 516 presents total number of execution of the line and the next two belong | |
| 517 to instances of class Foo constructors. As you can also see, line 30 contains | |
| 518 some unexecuted basic blocks and thus execution count has asterisk symbol. | |
| 519 | |
| 0 | 520 When you use the @option{-a} option, you will get individual block |
| 521 counts, and the output looks like this: | |
| 522 | |
| 523 @smallexample | |
| 131 | 524 -: 0:Source:tmp.cpp |
| 525 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 526 -: 0:Graph:tmp.gcno |
| 527 -: 0:Data:tmp.gcda | |
| 528 -: 0:Runs:1 | |
| 529 -: 0:Programs:1 | |
| 530 -: 1:#include <stdio.h> | |
| 531 -: 2: | |
| 131 | 532 -: 3:template<class T> |
| 533 -: 4:class Foo | |
| 534 -: 5:@{ | |
| 535 -: 6: public: | |
| 536 1*: 7: Foo(): b (1000) @{@} | |
| 537 ------------------ | |
| 538 Foo<char>::Foo(): | |
| 539 #####: 7: Foo(): b (1000) @{@} | |
| 540 ------------------ | |
| 541 Foo<int>::Foo(): | |
| 542 1: 7: Foo(): b (1000) @{@} | |
| 543 ------------------ | |
| 544 2*: 8: void inc () @{ b++; @} | |
| 545 ------------------ | |
| 546 Foo<char>::inc(): | |
| 547 #####: 8: void inc () @{ b++; @} | |
| 548 ------------------ | |
| 549 Foo<int>::inc(): | |
| 550 2: 8: void inc () @{ b++; @} | |
| 551 ------------------ | |
| 552 -: 9: | |
| 553 -: 10: private: | |
| 554 -: 11: int b; | |
| 555 -: 12:@}; | |
| 556 -: 13: | |
| 557 -: 14:template class Foo<int>; | |
| 558 -: 15:template class Foo<char>; | |
| 559 -: 16: | |
| 560 -: 17:int | |
| 561 1: 18:main (void) | |
| 562 -: 19:@{ | |
| 563 -: 20: int i, total; | |
| 564 1: 21: Foo<int> counter; | |
| 565 1: 21-block 0 | |
| 566 -: 22: | |
| 567 1: 23: counter.inc(); | |
| 568 1: 23-block 0 | |
| 569 1: 24: counter.inc(); | |
| 570 1: 24-block 0 | |
| 571 1: 25: total = 0; | |
| 572 -: 26: | |
| 573 11: 27: for (i = 0; i < 10; i++) | |
| 574 1: 27-block 0 | |
| 575 11: 27-block 1 | |
| 576 10: 28: total += i; | |
| 577 10: 28-block 0 | |
| 578 -: 29: | |
| 579 1*: 30: int v = total > 100 ? 1 : 2; | |
| 580 1: 30-block 0 | |
| 581 %%%%%: 30-block 1 | |
| 582 1: 30-block 2 | |
| 583 -: 31: | |
| 584 1: 32: if (total != 45) | |
| 585 1: 32-block 0 | |
| 586 #####: 33: printf ("Failure\n"); | |
| 587 %%%%%: 33-block 0 | |
| 588 -: 34: else | |
| 589 1: 35: printf ("Success\n"); | |
| 590 1: 35-block 0 | |
| 591 1: 36: return 0; | |
| 592 1: 36-block 0 | |
| 593 -: 37:@} | |
| 0 | 594 @end smallexample |
| 595 | |
| 596 In this mode, each basic block is only shown on one line -- the last | |
| 597 line of the block. A multi-line block will only contribute to the | |
| 598 execution count of that last line, and other lines will not be shown | |
| 599 to contain code, unless previous blocks end on those lines. | |
| 600 The total execution count of a line is shown and subsequent lines show | |
| 601 the execution counts for individual blocks that end on that line. After each | |
| 602 block, the branch and call counts of the block will be shown, if the | |
| 603 @option{-b} option is given. | |
| 604 | |
| 605 Because of the way GCC instruments calls, a call count can be shown | |
| 606 after a line with no individual blocks. | |
| 131 | 607 As you can see, line 33 contains a basic block that was not executed. |
| 0 | 608 |
| 609 @need 450 | |
| 610 When you use the @option{-b} option, your output looks like this: | |
| 611 | |
| 612 @smallexample | |
| 131 | 613 -: 0:Source:tmp.cpp |
| 614 -: 0:Working directory:/home/gcc/testcase | |
| 0 | 615 -: 0:Graph:tmp.gcno |
| 616 -: 0:Data:tmp.gcda | |
| 617 -: 0:Runs:1 | |
| 618 -: 0:Programs:1 | |
| 619 -: 1:#include <stdio.h> | |
| 620 -: 2: | |
| 131 | 621 -: 3:template<class T> |
| 622 -: 4:class Foo | |
| 623 -: 5:@{ | |
| 624 -: 6: public: | |
| 625 1*: 7: Foo(): b (1000) @{@} | |
| 626 ------------------ | |
| 627 Foo<char>::Foo(): | |
| 628 function Foo<char>::Foo() called 0 returned 0% blocks executed 0% | |
| 629 #####: 7: Foo(): b (1000) @{@} | |
| 630 ------------------ | |
| 631 Foo<int>::Foo(): | |
| 632 function Foo<int>::Foo() called 1 returned 100% blocks executed 100% | |
| 633 1: 7: Foo(): b (1000) @{@} | |
| 634 ------------------ | |
| 635 2*: 8: void inc () @{ b++; @} | |
| 636 ------------------ | |
| 637 Foo<char>::inc(): | |
| 638 function Foo<char>::inc() called 0 returned 0% blocks executed 0% | |
| 639 #####: 8: void inc () @{ b++; @} | |
| 640 ------------------ | |
| 641 Foo<int>::inc(): | |
| 642 function Foo<int>::inc() called 2 returned 100% blocks executed 100% | |
| 643 2: 8: void inc () @{ b++; @} | |
| 644 ------------------ | |
| 645 -: 9: | |
| 646 -: 10: private: | |
| 647 -: 11: int b; | |
| 648 -: 12:@}; | |
| 649 -: 13: | |
| 650 -: 14:template class Foo<int>; | |
| 651 -: 15:template class Foo<char>; | |
| 652 -: 16: | |
| 653 -: 17:int | |
| 654 function main called 1 returned 100% blocks executed 81% | |
| 655 1: 18:main (void) | |
| 656 -: 19:@{ | |
| 657 -: 20: int i, total; | |
| 658 1: 21: Foo<int> counter; | |
| 659 call 0 returned 100% | |
| 660 branch 1 taken 100% (fallthrough) | |
| 661 branch 2 taken 0% (throw) | |
| 662 -: 22: | |
| 663 1: 23: counter.inc(); | |
| 664 call 0 returned 100% | |
| 665 branch 1 taken 100% (fallthrough) | |
| 666 branch 2 taken 0% (throw) | |
| 667 1: 24: counter.inc(); | |
| 668 call 0 returned 100% | |
| 669 branch 1 taken 100% (fallthrough) | |
| 670 branch 2 taken 0% (throw) | |
| 671 1: 25: total = 0; | |
| 672 -: 26: | |
| 673 11: 27: for (i = 0; i < 10; i++) | |
| 0 | 674 branch 0 taken 91% (fallthrough) |
| 675 branch 1 taken 9% | |
| 131 | 676 10: 28: total += i; |
| 677 -: 29: | |
| 678 1*: 30: int v = total > 100 ? 1 : 2; | |
| 679 branch 0 taken 0% (fallthrough) | |
| 680 branch 1 taken 100% | |
| 681 -: 31: | |
| 682 1: 32: if (total != 45) | |
| 0 | 683 branch 0 taken 0% (fallthrough) |
| 684 branch 1 taken 100% | |
| 131 | 685 #####: 33: printf ("Failure\n"); |
| 0 | 686 call 0 never executed |
| 131 | 687 branch 1 never executed |
| 688 branch 2 never executed | |
| 689 -: 34: else | |
| 690 1: 35: printf ("Success\n"); | |
| 691 call 0 returned 100% | |
| 692 branch 1 taken 100% (fallthrough) | |
| 693 branch 2 taken 0% (throw) | |
| 694 1: 36: return 0; | |
| 695 -: 37:@} | |
| 0 | 696 @end smallexample |
| 697 | |
| 698 For each function, a line is printed showing how many times the function | |
| 699 is called, how many times it returns and what percentage of the | |
| 700 function's blocks were executed. | |
| 701 | |
| 702 For each basic block, a line is printed after the last line of the basic | |
| 703 block describing the branch or call that ends the basic block. There can | |
| 704 be multiple branches and calls listed for a single source line if there | |
| 705 are multiple basic blocks that end on that line. In this case, the | |
| 706 branches and calls are each given a number. There is no simple way to map | |
| 707 these branches and calls back to source constructs. In general, though, | |
| 708 the lowest numbered branch or call will correspond to the leftmost construct | |
| 709 on the source line. | |
| 710 | |
| 711 For a branch, if it was executed at least once, then a percentage | |
| 712 indicating the number of times the branch was taken divided by the | |
| 713 number of times the branch was executed will be printed. Otherwise, the | |
| 714 message ``never executed'' is printed. | |
| 715 | |
| 716 For a call, if it was executed at least once, then a percentage | |
| 717 indicating the number of times the call returned divided by the number | |
| 718 of times the call was executed will be printed. This will usually be | |
| 719 100%, but may be less for functions that call @code{exit} or @code{longjmp}, | |
| 720 and thus may not return every time they are called. | |
| 721 | |
| 722 The execution counts are cumulative. If the example program were | |
| 723 executed again without removing the @file{.gcda} file, the count for the | |
| 724 number of times each line in the source was executed would be added to | |
| 725 the results of the previous run(s). This is potentially useful in | |
| 726 several ways. For example, it could be used to accumulate data over a | |
| 727 number of program runs as part of a test verification suite, or to | |
| 728 provide more accurate long-term information over a large number of | |
| 729 program runs. | |
| 730 | |
| 731 The data in the @file{.gcda} files is saved immediately before the program | |
| 732 exits. For each source file compiled with @option{-fprofile-arcs}, the | |
| 733 profiling code first attempts to read in an existing @file{.gcda} file; if | |
| 734 the file doesn't match the executable (differing number of basic block | |
| 735 counts) it will ignore the contents of the file. It then adds in the | |
| 736 new execution counts and finally writes the data to the file. | |
| 737 | |
| 738 @node Gcov and Optimization | |
| 739 @section Using @command{gcov} with GCC Optimization | |
| 740 | |
| 741 If you plan to use @command{gcov} to help optimize your code, you must | |
| 742 first compile your program with two special GCC options: | |
| 743 @samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any | |
| 744 other GCC options; but if you want to prove that every single line | |
| 745 in your program was executed, you should not compile with optimization | |
| 746 at the same time. On some machines the optimizer can eliminate some | |
| 747 simple code lines by combining them with other lines. For example, code | |
| 748 like this: | |
| 749 | |
| 750 @smallexample | |
| 751 if (a != b) | |
| 752 c = 1; | |
| 753 else | |
| 754 c = 0; | |
| 755 @end smallexample | |
| 756 | |
| 757 @noindent | |
| 758 can be compiled into one instruction on some machines. In this case, | |
| 759 there is no way for @command{gcov} to calculate separate execution counts | |
| 760 for each line because there isn't separate code for each line. Hence | |
| 761 the @command{gcov} output looks like this if you compiled the program with | |
| 762 optimization: | |
| 763 | |
| 764 @smallexample | |
| 765 100: 12:if (a != b) | |
| 766 100: 13: c = 1; | |
| 767 100: 14:else | |
| 768 100: 15: c = 0; | |
| 769 @end smallexample | |
| 770 | |
| 771 The output shows that this block of code, combined by optimization, | |
| 772 executed 100 times. In one sense this result is correct, because there | |
| 773 was only one instruction representing all four of these lines. However, | |
| 774 the output does not indicate how many times the result was 0 and how | |
| 775 many times the result was 1. | |
| 776 | |
| 777 Inlineable functions can create unexpected line counts. Line counts are | |
| 778 shown for the source code of the inlineable function, but what is shown | |
| 779 depends on where the function is inlined, or if it is not inlined at all. | |
| 780 | |
| 781 If the function is not inlined, the compiler must emit an out of line | |
| 782 copy of the function, in any object file that needs it. If | |
| 783 @file{fileA.o} and @file{fileB.o} both contain out of line bodies of a | |
| 784 particular inlineable function, they will also both contain coverage | |
| 785 counts for that function. When @file{fileA.o} and @file{fileB.o} are | |
| 786 linked together, the linker will, on many systems, select one of those | |
| 787 out of line bodies for all calls to that function, and remove or ignore | |
| 788 the other. Unfortunately, it will not remove the coverage counters for | |
| 789 the unused function body. Hence when instrumented, all but one use of | |
| 790 that function will show zero counts. | |
| 791 | |
| 792 If the function is inlined in several places, the block structure in | |
| 793 each location might not be the same. For instance, a condition might | |
| 794 now be calculable at compile time in some instances. Because the | |
| 795 coverage of all the uses of the inline function will be shown for the | |
| 796 same source lines, the line counts themselves might seem inconsistent. | |
| 797 | |
| 111 | 798 Long-running applications can use the @code{__gcov_reset} and @code{__gcov_dump} |
| 799 facilities to restrict profile collection to the program region of | |
| 800 interest. Calling @code{__gcov_reset(void)} will clear all profile counters | |
| 801 to zero, and calling @code{__gcov_dump(void)} will cause the profile information | |
| 802 collected at that point to be dumped to @file{.gcda} output files. | |
| 803 Instrumented applications use a static destructor with priority 99 | |
| 804 to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump} | |
| 805 is executed after all user defined static destructors, | |
| 806 as well as handlers registered with @code{atexit}. | |
| 131 | 807 If an executable loads a dynamic shared object via dlopen functionality, |
| 808 @option{-Wl,--dynamic-list-data} is needed to dump all profile data. | |
| 809 | |
| 810 Profiling run-time library reports various errors related to profile | |
| 811 manipulation and profile saving. Errors are printed into standard error output | |
| 812 or @samp{GCOV_ERROR_FILE} file, if environment variable is used. | |
| 813 In order to terminate immediately after an errors occurs | |
| 814 set @samp{GCOV_EXIT_AT_ERROR} environment variable. | |
| 815 That can help users to find profile clashing which leads | |
| 816 to a misleading profile. | |
| 111 | 817 |
| 0 | 818 @c man end |
| 819 | |
| 820 @node Gcov Data Files | |
| 111 | 821 @section Brief Description of @command{gcov} Data Files |
| 0 | 822 |
| 823 @command{gcov} uses two files for profiling. The names of these files | |
| 824 are derived from the original @emph{object} file by substituting the | |
| 111 | 825 file suffix with either @file{.gcno}, or @file{.gcda}. The files |
| 826 contain coverage and profile data stored in a platform-independent format. | |
| 827 The @file{.gcno} files are placed in the same directory as the object | |
| 828 file. By default, the @file{.gcda} files are also stored in the same | |
| 829 directory as the object file, but the GCC @option{-fprofile-dir} option | |
| 830 may be used to store the @file{.gcda} files in a separate directory. | |
| 0 | 831 |
| 111 | 832 The @file{.gcno} notes file is generated when the source file is compiled |
| 833 with the GCC @option{-ftest-coverage} option. It contains information to | |
| 0 | 834 reconstruct the basic block graphs and assign source line numbers to |
| 835 blocks. | |
| 836 | |
| 111 | 837 The @file{.gcda} count data file is generated when a program containing |
| 838 object files built with the GCC @option{-fprofile-arcs} option is executed. | |
| 839 A separate @file{.gcda} file is created for each object file compiled with | |
| 840 this option. It contains arc transition counts, value profile counts, and | |
| 841 some summary information. | |
| 0 | 842 |
| 131 | 843 It is not recommended to access the coverage files directly. |
| 844 Consumers should use the intermediate format that is provided | |
| 845 by @command{gcov} tool via @option{--intermediate-format} option. | |
| 0 | 846 |
| 847 @node Cross-profiling | |
| 111 | 848 @section Data File Relocation to Support Cross-Profiling |
| 0 | 849 |
| 111 | 850 Running the program will cause profile output to be generated. For each |
| 851 source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} | |
| 852 file will be placed in the object file directory. That implicitly requires | |
| 853 running the program on the same system as it was built or having the same | |
| 0 | 854 absolute directory structure on the target system. The program will try |
| 855 to create the needed directory structure, if it is not already present. | |
| 856 | |
| 857 To support cross-profiling, a program compiled with @option{-fprofile-arcs} | |
| 111 | 858 can relocate the data files based on two environment variables: |
| 0 | 859 |
| 860 @itemize @bullet | |
| 861 @item | |
| 111 | 862 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
|
863 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
|
864 default is no prefix. |
| 0 | 865 |
| 866 @item | |
| 867 GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off | |
| 868 the hardwired absolute paths. Default value is 0. | |
| 869 | |
|
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
|
870 @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
|
871 then a relative path is made out of the hardwired absolute paths. |
| 0 | 872 @end itemize |
| 873 | |
| 874 For example, if the object file @file{/user/build/foo.o} was built with | |
| 875 @option{-fprofile-arcs}, the final executable will try to create the data file | |
| 876 @file{/user/build/foo.gcda} when running on the target system. This will | |
| 877 fail if the corresponding directory does not exist and it is unable to create | |
| 878 it. This can be overcome by, for example, setting the environment as | |
| 879 @samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a | |
| 880 setting will name the data file @file{/target/run/build/foo.gcda}. | |
| 881 | |
| 882 You must move the data files to the expected directory tree in order to | |
| 111 | 883 use them for profile directed optimizations (@option{-fprofile-use}), or to |
| 0 | 884 use the @command{gcov} tool. |