diff options
Diffstat (limited to 'gcc/doc/gcov.texi')
| -rw-r--r-- | gcc/doc/gcov.texi | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/gcc/doc/gcov.texi b/gcc/doc/gcov.texi index dda279f..ecf147a 100644 --- a/gcc/doc/gcov.texi +++ b/gcc/doc/gcov.texi @@ -125,6 +125,9 @@ gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] [@option{-b}|@option{--branch-probabilities}] [@option{-c}|@option{--branch-counts}] [@option{-g}|@option{--conditions}] + [@option{-e}|@option{--prime-paths}] + [@option{--prime-paths-lines[=@var{type}]}] + [@option{--prime-paths-source[=@var{type}]}] [@option{-d}|@option{--display-progress}] [@option{-f}|@option{--function-summaries}] [@option{--include} @var{regex}] @@ -181,6 +184,91 @@ your program at least once had an independent effect on the outcome of the boolean expression (modified condition/decision coverage). This requires you to compile the source with @option{-fcondition-coverage}. +@item -e +@itemx --prime-paths +Write path coverage to the output file, and write path summary info to +the standard output. This option allows you to see how many prime paths +were taken at least once. A path is a sequence of basic blocks. A path +is simple if it has no repeated blocks (no loops) except maybe the first +and last block, and prime if it is a simple path of maximal length. For +the regular output this option only includes the number of paths +covered. For more fine grained information on paths you can use +@option{--prime-paths-lines} or @option{--prime-paths-source}. With +@option{--json-format} all path details are included in the output. +This requires you to compile the +source with @option{-fpath-coverage}. + +@item --prime-paths-lines [=@var{type}] +Write path coverage to the output file, and write path summary info to +the standard output. This option allows you to see how many prime paths +were taken at least once, and dense report on the covered or uncovered +paths and how to cover them. This mode is useful for automated +reporting and progress tracking. @var{type} may be omitted, or one of: +@itemize @bullet +@item +@var{uncovered} +- Include the uncovered (not taken) paths. This is the default. +@item +@var{covered} +- Include the covered (taken) paths. +@item +@var{both} +- Include all paths. This is equivalent to using both @var{covered} and +@var{uncovered}. +@end itemize + +This is an example of @option{--prime-paths-lines} output: + +@smallexample +paths covered 12 of 15 +path 2 not covered: lines 8 8(false) 11(true) 11 13(true) 13(true) 14 17 +path 3 not covered: lines 8 8(false) 11(true) 11 13(true) 13(false) 16 17 +path 4 not covered: lines 8 8(false) 11(true) 11 13(false) 16 17 +@end smallexample + +This means to cover path 2 you must run lines 8, 11, 13, 14, and 17, +evaluting the decision at 8 false and the decisions at 11 and 13 to +@code{false}. + +@item --prime-paths-source [=@var{type}] +Write path coverage to the output file, and write path summary info to +the standard output. This option allows you to see how many prime paths +were taken at least once, and detailed report on the uncovered paths an +how to cover them. This mode is useful for understanding paths and +interactions between sections of your program. @var{type} may be +omitted, or one of: +@itemize @bullet +@item +@var{uncovered} +- Include the uncovered (not taken) paths. This is the default. +@item +@var{covered} +- Include the covered (taken) paths. +@item +@var{both} +- Include all paths. This is equivalent to using both @var{covered} and +@var{uncovered}. +@end itemize + +This is an example of @option{--prime-paths-source} output: + +@smallexample +path 10 not covered: +BB 3: 8: for (i = 0; i < 10; i++) +BB 3: 9: total += i; +BB 4: (false) 8: for (i = 0; i < 10; i++) +BB 5: (true) 11: int v = total > 100 ? 1 : 2; +BB 6: 11: int v = total > 100 ? 1 : 2; +BB 8: (false) 13: if (total != 45 && v == 1) +BB 11: 16: printf ("Success\n"); +BB 12: 17: return 0; +@end smallexample + +The first (BB) column is the sequence of basic blocks (see @option{-w}). +The middle column (true/false) is the decision for that line. The third +column is the line number. The fourth column is the line itself. These +lines must be run in this order to cover path 10. + @item -d @itemx --display-progress Display the progress on the standard output. @@ -989,6 +1077,106 @@ condition 1 not covered (true) -: 12:@} @end smallexample +@anchor{gcov prime paths example} +When you compile with @option{--coverage -fpath-coverage} and use the +option @option{-e} your output looks like this: + +@smallexample +$ gcov -t -e tmp + -: 0:Source:tmp.cpp + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 1:#include <stdio.h> + -: 2: +paths covered 4 of 15 + 1: 3:int main () + -: 4:@{ + -: 5: int i, total; + 1: 6: total = 0; + -: 7: + 11: 8: for (i = 0; i < 10; i++) + 10: 9: total += i; + -: 10: + 1*: 11: int v = total > 100 ? 1 : 2; + -: 12: + 1*: 13: if (total != 45 && v == 1) + #####: 14: printf ("Failure\n"); + -: 15: else + 1: 16: printf ("Success\n"); + 1: 17: return 0; + -: 18:@} +@end smallexample + +This output is useful to figure out roughly where coverage is missing +and testing how different inputs change the coverage. The +@option{--prime-paths-source} is a useful tool for understanding paths. + +@smallexample +$ gcov -t --prime-paths-source tmp + -: 0:Source:tmp.cpp + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 1:#include <stdio.h> + -: 2: +paths covered 4 of 15 +path 1: +BB 2: 3:int main () +BB 2: 6: total = 0; +BB 2: 8: for (i = 0; i < 10; i++) +BB 4: (false) 8: for (i = 0; i < 10; i++) +BB 5: (true) 11: int v = total > 100 ? 1 : 2; +BB 6: 11: int v = total > 100 ? 1 : 2; +BB 8: (true) 13: if (total != 45 && v == 1) +BB 9: (true) 13: if (total != 45 && v == 1) +BB 10: 14: printf ("Failure\n"); +BB 12: 17: return 0; +@end smallexample + +In this mode, gcov will print details on the missing paths. The first +column lists the sequence of basic blocks (BB). The second column is +the decision to take at that line if there is one. The final columns +are the line number and the line itself. This is useful for +understanding the paths, in particular those that are hard to cover or +even unreachable. Lines may be repeated, for example the @code{for} +loop, if the same line is a part of multiple basic blocks. This mode is +intended for humans and good at understanding what code is exercised +under testing or for given inputs. This output is quite verbose, and +for focusing on specific functions it can be combined with the filters +@option{--include} and @option{--exclude}. + +A denser output is available with @option{--prime-paths-lines}, which +looks like this: + +@smallexample + -: 0:Source:tmp.cpp + -: 0:Graph:tmp.gcno + -: 0:Data:tmp.gcda + -: 0:Runs:1 + -: 1:#include <stdio.h> + -: 2: +paths covered 4 of 15 +path 1 not covered: lines 8 8(false) 11(true) 11 13(true) 13(true) 14 17 +path 2 not covered: lines 8 8(false) 11(true) 11 13(true) 13(false) 16 17 +path 3 not covered: lines 8 8(false) 11(true) 11 13(false) 16 17 +path 4 not covered: lines 8 8(false) 11(false) 11 13(true) 13(true) 14 17 +path 5 not covered: lines 8 8(false) 11(false) 11 13(true) 13(false) 16 17 +path 6 not covered: lines 8 8(false) 11(false) 11 13(false) 16 17 +path 8 not covered: lines 9 8(false) 11(true) 11 13(true) 13(true) 14 17 +path 9 not covered: lines 9 8(false) 11(true) 11 13(true) 13(false) 16 17 +path 10 not covered: lines 9 8(false) 11(true) 11 13(false) 16 17 +path 11 not covered: lines 9 8(false) 11(false) 11 13(true) 13(true) 14 17 +path 12 not covered: lines 9 8(false) 11(false) 11 13(true) 13(false) 16 17 + 1: 3:int main () + -: 4:@{ +@end smallexample + +In this mode, every missing path is expanded using the lines and +decisions like @option{--prime-paths-source} but printed on a single +line. This mode provides a good overview over the paths and for +tracking how different tests and inputs exercises the code. + 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 |