| @c Copyright (C) 1996-2021 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-2021 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 |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``GNU General Public License'' and ``Funding |
| Free Software'', the Front-Cover texts being (a) (see below), and with |
| the Back-Cover Texts being (b) (see below). A copy of the license is |
| included in the gfdl(7) man page. |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. |
| @c man end |
| @c Set file name and title for the man page. |
| @setfilename gcov |
| @settitle coverage testing tool |
| @end ignore |
| |
| @node Gcov |
| @chapter @command{gcov}---a Test Coverage Program |
| |
| @command{gcov} is a tool you can use in conjunction with GCC to |
| test code coverage in your programs. |
| |
| @menu |
| * Gcov Intro:: Introduction to gcov. |
| * Invoking Gcov:: How to use gcov. |
| * Gcov and Optimization:: Using gcov with GCC optimization. |
| * Gcov Data Files:: The files used by gcov. |
| * Cross-profiling:: Data file relocation. |
| @end menu |
| |
| @node Gcov Intro |
| @section Introduction to @command{gcov} |
| @c man begin DESCRIPTION |
| |
| @command{gcov} is a test coverage program. Use it in concert with GCC |
| to analyze your programs to help create more efficient, faster running |
| code and to discover untested parts of your program. You can use |
| @command{gcov} as a profiling tool to help discover where your |
| optimization efforts will best affect your code. You can also use |
| @command{gcov} along with the other profiling tool, @command{gprof}, to |
| assess which parts of your code use the greatest amount of computing |
| time. |
| |
| Profiling tools help you analyze your code's performance. Using a |
| profiler such as @command{gcov} or @command{gprof}, you can find out some |
| basic performance statistics, such as: |
| |
| @itemize @bullet |
| @item |
| how often each line of code executes |
| |
| @item |
| what lines of code are actually executed |
| |
| @item |
| how much computing time each section of code uses |
| @end itemize |
| |
| Once you know these things about how your code works when compiled, you |
| can look at each module to see which modules should be optimized. |
| @command{gcov} helps you determine where to work on optimization. |
| |
| Software developers also use coverage testing in concert with |
| testsuites, to make sure software is actually good enough for a release. |
| Testsuites can verify that a program works as expected; a coverage |
| program tests to see how much of the program is exercised by the |
| testsuite. Developers can then determine what kinds of test cases need |
| to be added to the testsuites to create both better testing and a better |
| final product. |
| |
| You should compile your code without optimization if you plan to use |
| @command{gcov} because the optimization, by combining some lines of code |
| into one function, may not give you as much information as you need to |
| look for `hot spots' where the code is using a great deal of computer |
| time. Likewise, because @command{gcov} accumulates statistics by line (at |
| the lowest resolution), it works best with a programming style that |
| places only one statement on each line. If you use complicated macros |
| that expand to loops or to other control structures, the statistics are |
| less helpful---they only report on the line where the macro call |
| appears. If your complex macros behave like functions, you can replace |
| them with inline functions to solve this problem. |
| |
| @command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which |
| indicates how many times each line of a source file @file{@var{sourcefile}.c} |
| has executed. You can use these logfiles along with @command{gprof} to aid |
| in fine-tuning the performance of your programs. @command{gprof} gives |
| timing information you can use along with the information you get from |
| @command{gcov}. |
| |
| @command{gcov} works only on code compiled with GCC@. It is not |
| compatible with any other profiling or test coverage mechanism. |
| |
| @c man end |
| |
| @node Invoking Gcov |
| @section Invoking @command{gcov} |
| |
| @smallexample |
| gcov @r{[}@var{options}@r{]} @var{files} |
| @end smallexample |
| |
| @command{gcov} accepts the following options: |
| |
| @ignore |
| @c man begin SYNOPSIS |
| gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] |
| [@option{-a}|@option{--all-blocks}] |
| [@option{-b}|@option{--branch-probabilities}] |
| [@option{-c}|@option{--branch-counts}] |
| [@option{-d}|@option{--display-progress}] |
| [@option{-f}|@option{--function-summaries}] |
| [@option{-j}|@option{--json-format}] |
| [@option{-H}|@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} |
| @c man end |
| @c man begin SEEALSO |
| gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. |
| @c man end |
| @end ignore |
| |
| @c man begin OPTIONS |
| @table @gcctabopt |
| |
| @item -a |
| @itemx --all-blocks |
| Write individual execution counts for every basic block. Normally gcov |
| outputs execution counts only for the main blocks of a line. With this |
| option you can determine if blocks within a single line are not being |
| executed. |
| |
| @item -b |
| @itemx --branch-probabilities |
| Write branch frequencies to the output file, and write branch summary |
| info to the standard output. This option allows you to see how often |
| each branch in your program was taken. Unconditional branches will not |
| be shown, unless the @option{-u} option is given. |
| |
| @item -c |
| @itemx --branch-counts |
| Write branch frequencies as the number of branches taken, rather than |
| the percentage of branches taken. |
| |
| @item -d |
| @itemx --display-progress |
| Display the progress on the standard output. |
| |
| @item -f |
| @itemx --function-summaries |
| Output summaries for each function in addition to the file level summary. |
| |
| @item -h |
| @itemx --help |
| Display help about using @command{gcov} (on the standard output), and |
| exit without doing any further processing. |
| |
| @item -j |
| @itemx --json-format |
| Output gcov file in an easy-to-parse JSON intermediate format |
| which does not require source code for generation. The JSON |
| file is compressed with gzip compression algorithm |
| and the files have @file{.gcov.json.gz} extension. |
| |
| Structure of the JSON is following: |
| |
| @smallexample |
| @{ |
| "current_working_directory": "foo/bar", |
| "data_file": "a.out", |
| "format_version": "1", |
| "gcc_version": "11.1.1 20210510" |
| "files": ["$file"] |
| @} |
| @end smallexample |
| |
| Fields of the root element have following semantics: |
| |
| @itemize @bullet |
| @item |
| @var{current_working_directory}: working directory where |
| a compilation unit was compiled |
| |
| @item |
| @var{data_file}: name of the data file (GCDA) |
| |
| @item |
| @var{format_version}: semantic version of the format |
| |
| @item |
| @var{gcc_version}: version of the GCC compiler |
| @end itemize |
| |
| Each @var{file} has the following form: |
| |
| @smallexample |
| @{ |
| "file": "a.c", |
| "functions": ["$function"], |
| "lines": ["$line"] |
| @} |
| @end smallexample |
| |
| Fields of the @var{file} element have following semantics: |
| |
| @itemize @bullet |
| @item |
| @var{file_name}: name of the source file |
| @end itemize |
| |
| Each @var{function} has the following form: |
| |
| @smallexample |
| @{ |
| "blocks": 2, |
| "blocks_executed": 2, |
| "demangled_name": "foo", |
| "end_column": 1, |
| "end_line": 4, |
| "execution_count": 1, |
| "name": "foo", |
| "start_column": 5, |
| "start_line": 1 |
| @} |
| @end smallexample |
| |
| Fields of the @var{function} element have following semantics: |
| |
| @itemize @bullet |
| @item |
| @var{blocks}: number of blocks that are in the function |
| |
| @item |
| @var{blocks_executed}: number of executed blocks of the function |
| |
| @item |
| @var{demangled_name}: demangled name of the function |
| |
| @item |
| @var{end_column}: column in the source file where the function ends |
| |
| @item |
| @var{end_line}: line in the source file where the function ends |
| |
| @item |
| @var{execution_count}: number of executions of the function |
| |
| @item |
| @var{name}: name of the function |
| |
| @item |
| @var{start_column}: column in the source file where the function begins |
| |
| @item |
| @var{start_line}: line in the source file where the function begins |
| @end itemize |
| |
| Note that line numbers and column numbers number from 1. In the current |
| implementation, @var{start_line} and @var{start_column} do not include |
| any template parameters and the leading return type but that |
| this is likely to be fixed in the future. |
| |
| Each @var{line} has the following form: |
| |
| @smallexample |
| @{ |
| "branches": ["$branch"], |
| "count": 2, |
| "line_number": 15, |
| "unexecuted_block": false, |
| "function_name": "foo", |
| @} |
| @end smallexample |
| |
| Branches are present only with @var{-b} option. |
| Fields of the @var{line} element have following semantics: |
| |
| @itemize @bullet |
| @item |
| @var{count}: number of executions of the line |
| |
| @item |
| @var{line_number}: line number |
| |
| @item |
| @var{unexecuted_block}: flag whether the line contains an unexecuted block |
| (not all statements on the line are executed) |
| |
| @item |
| @var{function_name}: a name of a function this @var{line} belongs to |
| (for a line with an inlined statements can be not set) |
| @end itemize |
| |
| Each @var{branch} has the following form: |
| |
| @smallexample |
| @{ |
| "count": 11, |
| "fallthrough": true, |
| "throw": false |
| @} |
| @end smallexample |
| |
| Fields of the @var{branch} element have following semantics: |
| |
| @itemize @bullet |
| @item |
| @var{count}: number of executions of the branch |
| |
| @item |
| @var{fallthrough}: true when the branch is a fall through branch |
| |
| @item |
| @var{throw}: true when the branch is an exceptional branch |
| @end itemize |
| |
| @item -H |
| @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 |
| header file @file{x.h} contains code, and was included in the file |
| @file{a.c}, then running @command{gcov} on the file @file{a.c} will |
| produce an output file called @file{a.c##x.h.gcov} instead of |
| @file{x.h.gcov}. This can be useful if @file{x.h} is included in |
| multiple source files and you want to see the individual |
| contributions. If you use the @samp{-p} option, both the including |
| and included file names will be complete path names. |
| |
| @item -m |
| @itemx --demangled-names |
| Display demangled function names in output. The default is to show |
| mangled function names. |
| |
| @item -n |
| @itemx --no-output |
| Do not create the @command{gcov} output file. |
| |
| @item -o @var{directory|file} |
| @itemx --object-directory @var{directory} |
| @itemx --object-file @var{file} |
| Specify either the directory containing the gcov data files, or the |
| object path name. The @file{.gcno}, and |
| @file{.gcda} data files are searched for using this option. If a directory |
| is specified, the data files are in that directory and named after the |
| input file name, without its extension. If a file is specified here, |
| the data files are named after that file, without its extension. |
| |
| @item -p |
| @itemx --preserve-paths |
| Preserve complete path information in the names of generated |
| @file{.gcov} files. Without this option, just the filename component is |
| used. With this option, all directories are used, with @samp{/} characters |
| translated to @samp{#} characters, @file{.} directory components |
| removed and unremoveable @file{..} |
| 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 |
| (after source prefix elision). Absolute paths are usually system |
| header files and coverage of any inline functions therein is normally |
| uninteresting. |
| |
| @item -s @var{directory} |
| @itemx --source-prefix @var{directory} |
| A prefix for source file names to remove when generating the output |
| coverage files. This option is useful when building in a separate |
| directory, and the pathname to the source directory is not wanted when |
| 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. |
| Unconditional branches are normally not interesting. |
| |
| @item -v |
| @itemx --version |
| Display the @command{gcov} version number (on the standard output), |
| and exit without doing any further processing. |
| |
| @item -w |
| @itemx --verbose |
| Print verbose informations related to basic blocks and arcs. |
| |
| @item -x |
| @itemx --hash-filenames |
| When using @var{--preserve-paths}, |
| 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}, |
| where the @var{source-file} component is the final filename part and |
| the @var{md5} component is calculated from the full mangled name that |
| would have been used otherwise. The option is an alternative |
| to the @var{--preserve-paths} on systems which have a filesystem limit. |
| |
| @end table |
| |
| @command{gcov} should be run with the current directory the same as that |
| when you invoked the compiler. Otherwise it will not be able to locate |
| the source files. @command{gcov} produces files called |
| @file{@var{mangledname}.gcov} in the current directory. These contain |
| the coverage information of the source file they correspond to. |
| One @file{.gcov} file is produced for each source (or header) file |
| containing code, |
| which was compiled to produce the data files. The @var{mangledname} part |
| of the output file name is usually simply the source file name, but can |
| be something more complicated if the @samp{-l} or @samp{-p} options are |
| given. Refer to those options for details. |
| |
| If you invoke @command{gcov} with multiple input files, the |
| contributions from each input file are summed. Typically you would |
| invoke it with the same list of files as the final link of your executable. |
| |
| The @file{.gcov} files contain the @samp{:} separated fields along with |
| program source code. The format is |
| |
| @smallexample |
| @var{execution_count}:@var{line_number}:@var{source line text} |
| @end smallexample |
| |
| 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 |
| non-exceptional paths or only exceptional paths such as C++ exception |
| 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 |
| |
| @smallexample |
| -:0:@var{tag}:@var{value} |
| @end smallexample |
| |
| The ordering and number of these preamble lines will be augmented as |
| @command{gcov} development progresses --- do not rely on them remaining |
| unchanged. Use @var{tag} to locate a particular preamble line. |
| |
| The additional block information is of the form |
| |
| @smallexample |
| @var{tag} @var{information} |
| @end smallexample |
| |
| The @var{information} is human readable, but designed to be simple |
| enough for machine parsing too. |
| |
| When printing percentages, 0% and 100% are only printed when the values |
| are @emph{exactly} 0% and 100% respectively. Other values which would |
| conventionally be rounded to 0% or 100% are instead printed as the |
| nearest non-boundary value. |
| |
| When using @command{gcov}, you must first compile your program |
| with a special GCC option @samp{--coverage}. |
| This tells the compiler to generate additional information needed by |
| gcov (basically a flow graph of the program) and also includes |
| additional code in the object files for generating the extra profiling |
| information needed by gcov. These additional files are placed in the |
| directory where the object file is located. |
| |
| Running the program will cause profile output to be generated. For each |
| source file compiled with @option{-fprofile-arcs}, an accompanying |
| @file{.gcda} file will be placed in the object file directory. |
| |
| 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.cpp}, this |
| is what you see when you use the basic @command{gcov} facility: |
| |
| @smallexample |
| $ g++ --coverage tmp.cpp -c |
| $ g++ --coverage tmp.o |
| $ a.out |
| $ gcov tmp.cpp -m |
| File 'tmp.cpp' |
| Lines executed:92.86% of 14 |
| Creating 'tmp.cpp.gcov' |
| @end smallexample |
| |
| The file @file{tmp.cpp.gcov} contains output from @command{gcov}. |
| Here is a sample: |
| |
| @smallexample |
| -: 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: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.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: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 |
| line of the block. A multi-line block will only contribute to the |
| execution count of that last line, and other lines will not be shown |
| to contain code, unless previous blocks end on those lines. |
| The total execution count of a line is shown and subsequent lines show |
| the execution counts for individual blocks that end on that line. After each |
| block, the branch and call counts of the block will be shown, if the |
| @option{-b} option is given. |
| |
| 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 33 contains a basic block that was not executed. |
| |
| @need 450 |
| When you use the @option{-b} option, your output looks like this: |
| |
| @smallexample |
| -: 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: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: 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% |
| #####: 33: printf ("Failure\n"); |
| call 0 never executed |
| 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 |
| is called, how many times it returns and what percentage of the |
| function's blocks were executed. |
| |
| For each basic block, a line is printed after the last line of the basic |
| block describing the branch or call that ends the basic block. There can |
| be multiple branches and calls listed for a single source line if there |
| are multiple basic blocks that end on that line. In this case, the |
| branches and calls are each given a number. There is no simple way to map |
| these branches and calls back to source constructs. In general, though, |
| the lowest numbered branch or call will correspond to the leftmost construct |
| on the source line. |
| |
| For a branch, if it was executed at least once, then a percentage |
| indicating the number of times the branch was taken divided by the |
| number of times the branch was executed will be printed. Otherwise, the |
| message ``never executed'' is printed. |
| |
| For a call, if it was executed at least once, then a percentage |
| indicating the number of times the call returned divided by the number |
| of times the call was executed will be printed. This will usually be |
| 100%, but may be less for functions that call @code{exit} or @code{longjmp}, |
| and thus may not return every time they are called. |
| |
| The execution counts are cumulative. If the example program were |
| executed again without removing the @file{.gcda} file, the count for the |
| number of times each line in the source was executed would be added to |
| the results of the previous run(s). This is potentially useful in |
| several ways. For example, it could be used to accumulate data over a |
| number of program runs as part of a test verification suite, or to |
| provide more accurate long-term information over a large number of |
| program runs. |
| |
| The data in the @file{.gcda} files is saved immediately before the program |
| exits. For each source file compiled with @option{-fprofile-arcs}, the |
| profiling code first attempts to read in an existing @file{.gcda} file; if |
| the file doesn't match the executable (differing number of basic block |
| counts) it will ignore the contents of the file. It then adds in the |
| new execution counts and finally writes the data to the file. |
| |
| @node Gcov and Optimization |
| @section Using @command{gcov} with GCC Optimization |
| |
| If you plan to use @command{gcov} to help optimize your code, you must |
| first compile your program with a special GCC option |
| @samp{--coverage}. Aside from that, you can use any |
| other GCC options; but if you want to prove that every single line |
| in your program was executed, you should not compile with optimization |
| at the same time. On some machines the optimizer can eliminate some |
| simple code lines by combining them with other lines. For example, code |
| like this: |
| |
| @smallexample |
| if (a != b) |
| c = 1; |
| else |
| c = 0; |
| @end smallexample |
| |
| @noindent |
| can be compiled into one instruction on some machines. In this case, |
| there is no way for @command{gcov} to calculate separate execution counts |
| for each line because there isn't separate code for each line. Hence |
| the @command{gcov} output looks like this if you compiled the program with |
| optimization: |
| |
| @smallexample |
| 100: 12:if (a != b) |
| 100: 13: c = 1; |
| 100: 14:else |
| 100: 15: c = 0; |
| @end smallexample |
| |
| The output shows that this block of code, combined by optimization, |
| executed 100 times. In one sense this result is correct, because there |
| was only one instruction representing all four of these lines. However, |
| the output does not indicate how many times the result was 0 and how |
| many times the result was 1. |
| |
| Inlineable functions can create unexpected line counts. Line counts are |
| shown for the source code of the inlineable function, but what is shown |
| depends on where the function is inlined, or if it is not inlined at all. |
| |
| If the function is not inlined, the compiler must emit an out of line |
| copy of the function, in any object file that needs it. If |
| @file{fileA.o} and @file{fileB.o} both contain out of line bodies of a |
| particular inlineable function, they will also both contain coverage |
| counts for that function. When @file{fileA.o} and @file{fileB.o} are |
| linked together, the linker will, on many systems, select one of those |
| out of line bodies for all calls to that function, and remove or ignore |
| the other. Unfortunately, it will not remove the coverage counters for |
| the unused function body. Hence when instrumented, all but one use of |
| that function will show zero counts. |
| |
| If the function is inlined in several places, the block structure in |
| each location might not be the same. For instance, a condition might |
| now be calculable at compile time in some instances. Because the |
| coverage of all the uses of the inline function will be shown for the |
| same source lines, the line counts themselves might seem inconsistent. |
| |
| Long-running applications can use the @code{__gcov_reset} and @code{__gcov_dump} |
| facilities to restrict profile collection to the program region of |
| interest. Calling @code{__gcov_reset(void)} will clear all run-time profile |
| counters to zero, and calling @code{__gcov_dump(void)} will cause the profile |
| information collected at that point to be dumped to @file{.gcda} output files. |
| Instrumented applications use a static destructor with priority 99 |
| 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 |
| |
| @node Gcov Data Files |
| @section Brief Description of @command{gcov} Data Files |
| |
| @command{gcov} uses two files for profiling. The names of these files |
| are derived from the original @emph{object} file by substituting the |
| file suffix with either @file{.gcno}, or @file{.gcda}. The files |
| contain coverage and profile data stored in a platform-independent format. |
| The @file{.gcno} files are placed in the same directory as the object |
| file. By default, the @file{.gcda} files are also stored in the same |
| directory as the object file, but the GCC @option{-fprofile-dir} option |
| may be used to store the @file{.gcda} files in a separate directory. |
| |
| The @file{.gcno} notes file is generated when the source file is compiled |
| with the GCC @option{-ftest-coverage} option. It contains information to |
| reconstruct the basic block graphs and assign source line numbers to |
| blocks. |
| |
| The @file{.gcda} count data file is generated when a program containing |
| object files built with the GCC @option{-fprofile-arcs} option is executed. |
| A separate @file{.gcda} file is created for each object file compiled with |
| this option. It contains arc transition counts, value profile counts, and |
| some summary information. |
| |
| 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{--json-format} option. |
| |
| @node Cross-profiling |
| @section Data File Relocation to Support Cross-Profiling |
| |
| Running the program will cause profile output to be generated. For each |
| source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} |
| file will be placed in the object file directory. That implicitly requires |
| running the program on the same system as it was built or having the same |
| absolute directory structure on the target system. The program will try |
| to create the needed directory structure, if it is not already present. |
| |
| To support cross-profiling, a program compiled with @option{-fprofile-arcs} |
| can relocate the data files based on two environment variables: |
| |
| @itemize @bullet |
| @item |
| GCOV_PREFIX contains the prefix to add to the absolute paths |
| in the object file. Prefix can be absolute, or relative. The |
| default is no prefix. |
| |
| @item |
| GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off |
| the hardwired absolute paths. Default value is 0. |
| |
| @emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined, |
| then a relative path is made out of the hardwired absolute paths. |
| @end itemize |
| |
| For example, if the object file @file{/user/build/foo.o} was built with |
| @option{-fprofile-arcs}, the final executable will try to create the data file |
| @file{/user/build/foo.gcda} when running on the target system. This will |
| fail if the corresponding directory does not exist and it is unable to create |
| it. This can be overcome by, for example, setting the environment as |
| @samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a |
| setting will name the data file @file{/target/run/build/foo.gcda}. |
| |
| You must move the data files to the expected directory tree in order to |
| use them for profile directed optimizations (@option{-fprofile-use}), or to |
| use the @command{gcov} tool. |