Mercurial > hg > CbC > CbC_gcc
diff gcc/doc/gcov.texi @ 131:84e7813d76e9
gcc-8.2
author | mir3636 |
---|---|
date | Thu, 25 Oct 2018 07:37:49 +0900 |
parents | 04ced10e8804 |
children | 1830386684a0 |
line wrap: on
line diff
--- a/gcc/doc/gcov.texi Fri Oct 27 22:46:09 2017 +0900 +++ b/gcc/doc/gcov.texi Thu Oct 25 07:37:49 2018 +0900 @@ -1,10 +1,10 @@ -@c Copyright (C) 1996-2017 Free Software Foundation, Inc. +@c Copyright (C) 1996-2018 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @ignore @c man begin COPYRIGHT -Copyright @copyright{} 1996-2017 Free Software Foundation, Inc. +Copyright @copyright{} 1996-2018 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -125,13 +125,17 @@ [@option{-d}|@option{--display-progress}] [@option{-f}|@option{--function-summaries}] [@option{-i}|@option{--intermediate-format}] + [@option{-j}|@option{--human-readable}] + [@option{-k}|@option{--use-colors}] [@option{-l}|@option{--long-file-names}] [@option{-m}|@option{--demangled-names}] [@option{-n}|@option{--no-output}] [@option{-o}|@option{--object-directory} @var{directory|file}] [@option{-p}|@option{--preserve-paths}] + [@option{-q}|@option{--use-hotness-colors}] [@option{-r}|@option{--relative-only}] [@option{-s}|@option{--source-prefix} @var{directory}] + [@option{-t}|@option{--stdout}] [@option{-u}|@option{--unconditional-branches}] [@option{-x}|@option{--hash-filenames}] @var{files} @@ -186,35 +190,81 @@ one entry per line @smallexample +version:@var{gcc_version} +cwd:@var{working_directory} file:@var{source_file_name} -function:@var{line_number},@var{execution_count},@var{function_name} -lcount:@var{line number},@var{execution_count} +function:@var{start_line_number},@var{end_line_number},@var{execution_count},@var{function_name} +lcount:@var{line number},@var{execution_count},@var{has_unexecuted_block} branch:@var{line_number},@var{branch_coverage_type} Where the @var{branch_coverage_type} is notexec (Branch not executed) taken (Branch executed and taken) nottaken (Branch executed, but not taken) +@end smallexample There can be multiple @var{file} entries in an intermediate gcov file. All entries following a @var{file} pertain to that source file -until the next @var{file} entry. -@end smallexample +until the next @var{file} entry. If there are multiple functions that +start on a single line, then corresponding lcount is repeated multiple +times. Here is a sample when @option{-i} is used in conjunction with @option{-b} option: @smallexample -file:array.cc -function:11,1,_Z3sumRKSt6vectorIPiSaIS0_EE -function:22,1,main -lcount:11,1 -lcount:12,1 -lcount:14,1 -branch:14,taken -lcount:26,1 -branch:28,nottaken +version: 8.1.0 20180103 +cwd:/home/gcc/testcase +file:tmp.cpp +function:7,7,0,_ZN3FooIcEC2Ev +function:7,7,1,_ZN3FooIiEC2Ev +function:8,8,0,_ZN3FooIcE3incEv +function:8,8,2,_ZN3FooIiE3incEv +function:18,37,1,main +lcount:7,0,1 +lcount:7,1,0 +lcount:8,0,1 +lcount:8,2,0 +lcount:18,1,0 +lcount:21,1,0 +branch:21,taken +branch:21,nottaken +lcount:23,1,0 +branch:23,taken +branch:23,nottaken +lcount:24,1,0 +branch:24,taken +branch:24,nottaken +lcount:25,1,0 +lcount:27,11,0 +branch:27,taken +branch:27,taken +lcount:28,10,0 +lcount:30,1,1 +branch:30,nottaken +branch:30,taken +lcount:32,1,0 +branch:32,nottaken +branch:32,taken +lcount:33,0,1 +branch:33,notexec +branch:33,notexec +lcount:35,1,0 +branch:35,taken +branch:35,nottaken +lcount:36,1,0 @end smallexample +@item -j +@itemx --human-readable +Write counts in human readable format (like 24.6k). + +@item -k +@itemx --use-colors + +Use colors for lines of code that have zero coverage. We use red color for +non-exceptional lines and cyan for exceptional. Same colors are used for +basic blocks with @option{-a} option. + @item -l @itemx --long-file-names Create long file names for included source files. For example, if the @@ -255,6 +305,12 @@ components renamed to @samp{^}. This is useful if sourcefiles are in several different directories. +@item -q +@itemx --use-hotness-colors + +Emit perf-like colored output for hot lines. Legend of the color scale +is printed at the very beginning of the output file. + @item -r @itemx --relative-only Only output information about source files with a relative pathname @@ -270,6 +326,10 @@ determining the output file names. Note that this prefix detection is applied before determining whether the source file is absolute. +@item -t +@itemx --stdout +Output to standard output instead of output files. + @item -u @itemx --unconditional-branches When branch probabilities are given, include those of unconditional branches. @@ -286,7 +346,7 @@ @item -x @itemx --hash-filenames -By default, gcov uses the full pathname of the source files to to create +By default, gcov uses the full pathname of the source files to create an output filename. This can lead to long filenames that can overflow filesystem limits. This option creates names of the form @file{@var{source-file}##@var{md5}.gcov}, @@ -322,11 +382,21 @@ Additional block information may succeed each line, when requested by command line option. The @var{execution_count} is @samp{-} for lines containing no code. Unexecuted lines are marked @samp{#####} or -@samp{====}, depending on whether they are reachable by +@samp{=====}, depending on whether they are reachable by non-exceptional paths or only exceptional paths such as C++ exception -handlers, respectively. Given @samp{-a} option, unexecuted blocks are +handlers, respectively. Given the @samp{-a} option, unexecuted blocks are marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block is reachable via non-exceptional or exceptional paths. +Executed basic blocks having a statement with zero @var{execution_count} +end with @samp{*} character and are colored with magenta color with +the @option{-k} option. This functionality is not supported in Ada. + +Note that GCC can completely remove the bodies of functions that are +not needed -- for instance if they are inlined everywhere. Such functions +are marked with @samp{-}, which can be confusing. +Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions} +options to retain these functions and +allow gcov to properly show their @var{execution_count}. Some lines of information at the start have @var{line_number} of zero. These preamble lines are of the form @@ -367,79 +437,160 @@ Running @command{gcov} with your program's source file names as arguments will now produce a listing of the code along with frequency of execution -for each line. For example, if your program is called @file{tmp.c}, this +for each line. For example, if your program is called @file{tmp.cpp}, this is what you see when you use the basic @command{gcov} facility: @smallexample -$ gcc -fprofile-arcs -ftest-coverage tmp.c +$ g++ -fprofile-arcs -ftest-coverage tmp.cpp $ a.out -$ gcov tmp.c -File 'tmp.c' -Lines executed:90.00% of 10 -Creating 'tmp.c.gcov' +$ gcov tmp.cpp -m +File 'tmp.cpp' +Lines executed:92.86% of 14 +Creating 'tmp.cpp.gcov' @end smallexample -The file @file{tmp.c.gcov} contains output from @command{gcov}. +The file @file{tmp.cpp.gcov} contains output from @command{gcov}. Here is a sample: @smallexample - -: 0:Source:tmp.c + -: 0:Source:tmp.cpp + -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include <stdio.h> -: 2: - -: 3:int main (void) - 1: 4:@{ - 1: 5: int i, total; - -: 6: - 1: 7: total = 0; - -: 8: - 11: 9: for (i = 0; i < 10; i++) - 10: 10: total += i; - -: 11: - 1: 12: if (total != 45) - #####: 13: printf ("Failure\n"); - -: 14: else - 1: 15: printf ("Success\n"); - 1: 16: return 0; - -: 17:@} + -: 3:template<class T> + -: 4:class Foo + -: 5:@{ + -: 6: public: + 1*: 7: Foo(): b (1000) @{@} +------------------ +Foo<char>::Foo(): + #####: 7: Foo(): b (1000) @{@} +------------------ +Foo<int>::Foo(): + 1: 7: Foo(): b (1000) @{@} +------------------ + 2*: 8: void inc () @{ b++; @} +------------------ +Foo<char>::inc(): + #####: 8: void inc () @{ b++; @} +------------------ +Foo<int>::inc(): + 2: 8: void inc () @{ b++; @} +------------------ + -: 9: + -: 10: private: + -: 11: int b; + -: 12:@}; + -: 13: + -: 14:template class Foo<int>; + -: 15:template class Foo<char>; + -: 16: + -: 17:int + 1: 18:main (void) + -: 19:@{ + -: 20: int i, total; + 1: 21: Foo<int> counter; + -: 22: + 1: 23: counter.inc(); + 1: 24: counter.inc(); + 1: 25: total = 0; + -: 26: + 11: 27: for (i = 0; i < 10; i++) + 10: 28: total += i; + -: 29: + 1*: 30: int v = total > 100 ? 1 : 2; + -: 31: + 1: 32: if (total != 45) + #####: 33: printf ("Failure\n"); + -: 34: else + 1: 35: printf ("Success\n"); + 1: 36: return 0; + -: 37:@} @end smallexample +Note that line 7 is shown in the report multiple times. First occurrence +presents total number of execution of the line and the next two belong +to instances of class Foo constructors. As you can also see, line 30 contains +some unexecuted basic blocks and thus execution count has asterisk symbol. + When you use the @option{-a} option, you will get individual block counts, and the output looks like this: @smallexample - -: 0:Source:tmp.c + -: 0:Source:tmp.cpp + -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include <stdio.h> -: 2: - -: 3:int main (void) - 1: 4:@{ - 1: 4-block 0 - 1: 5: int i, total; - -: 6: - 1: 7: total = 0; - -: 8: - 11: 9: for (i = 0; i < 10; i++) - 11: 9-block 0 - 10: 10: total += i; - 10: 10-block 0 - -: 11: - 1: 12: if (total != 45) - 1: 12-block 0 - #####: 13: printf ("Failure\n"); - $$$$$: 13-block 0 - -: 14: else - 1: 15: printf ("Success\n"); - 1: 15-block 0 - 1: 16: return 0; - 1: 16-block 0 - -: 17:@} + -: 3:template<class T> + -: 4:class Foo + -: 5:@{ + -: 6: public: + 1*: 7: Foo(): b (1000) @{@} +------------------ +Foo<char>::Foo(): + #####: 7: Foo(): b (1000) @{@} +------------------ +Foo<int>::Foo(): + 1: 7: Foo(): b (1000) @{@} +------------------ + 2*: 8: void inc () @{ b++; @} +------------------ +Foo<char>::inc(): + #####: 8: void inc () @{ b++; @} +------------------ +Foo<int>::inc(): + 2: 8: void inc () @{ b++; @} +------------------ + -: 9: + -: 10: private: + -: 11: int b; + -: 12:@}; + -: 13: + -: 14:template class Foo<int>; + -: 15:template class Foo<char>; + -: 16: + -: 17:int + 1: 18:main (void) + -: 19:@{ + -: 20: int i, total; + 1: 21: Foo<int> counter; + 1: 21-block 0 + -: 22: + 1: 23: counter.inc(); + 1: 23-block 0 + 1: 24: counter.inc(); + 1: 24-block 0 + 1: 25: total = 0; + -: 26: + 11: 27: for (i = 0; i < 10; i++) + 1: 27-block 0 + 11: 27-block 1 + 10: 28: total += i; + 10: 28-block 0 + -: 29: + 1*: 30: int v = total > 100 ? 1 : 2; + 1: 30-block 0 + %%%%%: 30-block 1 + 1: 30-block 2 + -: 31: + 1: 32: if (total != 45) + 1: 32-block 0 + #####: 33: printf ("Failure\n"); + %%%%%: 33-block 0 + -: 34: else + 1: 35: printf ("Success\n"); + 1: 35-block 0 + 1: 36: return 0; + 1: 36-block 0 + -: 37:@} @end smallexample In this mode, each basic block is only shown on one line -- the last @@ -453,53 +604,95 @@ Because of the way GCC instruments calls, a call count can be shown after a line with no individual blocks. -As you can see, line 13 contains a basic block that was not executed. +As you can see, line 33 contains a basic block that was not executed. @need 450 When you use the @option{-b} option, your output looks like this: @smallexample -$ gcov -b tmp.c -File 'tmp.c' -Lines executed:90.00% of 10 -Branches executed:80.00% of 5 -Taken at least once:80.00% of 5 -Calls executed:50.00% of 2 -Creating 'tmp.c.gcov' -@end smallexample - -Here is a sample of a resulting @file{tmp.c.gcov} file: - -@smallexample - -: 0:Source:tmp.c + -: 0:Source:tmp.cpp + -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include <stdio.h> -: 2: - -: 3:int main (void) -function main called 1 returned 1 blocks executed 75% - 1: 4:@{ - 1: 5: int i, total; - -: 6: - 1: 7: total = 0; - -: 8: - 11: 9: for (i = 0; i < 10; i++) + -: 3:template<class T> + -: 4:class Foo + -: 5:@{ + -: 6: public: + 1*: 7: Foo(): b (1000) @{@} +------------------ +Foo<char>::Foo(): +function Foo<char>::Foo() called 0 returned 0% blocks executed 0% + #####: 7: Foo(): b (1000) @{@} +------------------ +Foo<int>::Foo(): +function Foo<int>::Foo() called 1 returned 100% blocks executed 100% + 1: 7: Foo(): b (1000) @{@} +------------------ + 2*: 8: void inc () @{ b++; @} +------------------ +Foo<char>::inc(): +function Foo<char>::inc() called 0 returned 0% blocks executed 0% + #####: 8: void inc () @{ b++; @} +------------------ +Foo<int>::inc(): +function Foo<int>::inc() called 2 returned 100% blocks executed 100% + 2: 8: void inc () @{ b++; @} +------------------ + -: 9: + -: 10: private: + -: 11: int b; + -: 12:@}; + -: 13: + -: 14:template class Foo<int>; + -: 15:template class Foo<char>; + -: 16: + -: 17:int +function main called 1 returned 100% blocks executed 81% + 1: 18:main (void) + -: 19:@{ + -: 20: int i, total; + 1: 21: Foo<int> counter; +call 0 returned 100% +branch 1 taken 100% (fallthrough) +branch 2 taken 0% (throw) + -: 22: + 1: 23: counter.inc(); +call 0 returned 100% +branch 1 taken 100% (fallthrough) +branch 2 taken 0% (throw) + 1: 24: counter.inc(); +call 0 returned 100% +branch 1 taken 100% (fallthrough) +branch 2 taken 0% (throw) + 1: 25: total = 0; + -: 26: + 11: 27: for (i = 0; i < 10; i++) branch 0 taken 91% (fallthrough) branch 1 taken 9% - 10: 10: total += i; - -: 11: - 1: 12: if (total != 45) + 10: 28: total += i; + -: 29: + 1*: 30: int v = total > 100 ? 1 : 2; +branch 0 taken 0% (fallthrough) +branch 1 taken 100% + -: 31: + 1: 32: if (total != 45) branch 0 taken 0% (fallthrough) branch 1 taken 100% - #####: 13: printf ("Failure\n"); + #####: 33: printf ("Failure\n"); call 0 never executed - -: 14: else - 1: 15: printf ("Success\n"); -call 0 called 1 returned 100% - 1: 16: return 0; - -: 17:@} +branch 1 never executed +branch 2 never executed + -: 34: else + 1: 35: printf ("Success\n"); +call 0 returned 100% +branch 1 taken 100% (fallthrough) +branch 2 taken 0% (throw) + 1: 36: return 0; + -: 37:@} @end smallexample For each function, a line is printed showing how many times the function @@ -611,6 +804,16 @@ to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump} is executed after all user defined static destructors, as well as handlers registered with @code{atexit}. +If an executable loads a dynamic shared object via dlopen functionality, +@option{-Wl,--dynamic-list-data} is needed to dump all profile data. + +Profiling run-time library reports various errors related to profile +manipulation and profile saving. Errors are printed into standard error output +or @samp{GCOV_ERROR_FILE} file, if environment variable is used. +In order to terminate immediately after an errors occurs +set @samp{GCOV_EXIT_AT_ERROR} environment variable. +That can help users to find profile clashing which leads +to a misleading profile. @c man end @@ -637,9 +840,9 @@ this option. It contains arc transition counts, value profile counts, and some summary information. -The full details of the file format is specified in @file{gcov-io.h}, -and functions provided in that header file should be used to access the -coverage files. +It is not recommended to access the coverage files directly. +Consumers should use the intermediate format that is provided +by @command{gcov} tool via @option{--intermediate-format} option. @node Cross-profiling @section Data File Relocation to Support Cross-Profiling