From: Jørgen Kvalsvik <j@lambda.is>
Date: Fri, 21 Jun 2024 18:28:01 +0000 (+0200)
Subject: Add section on MC/DC in gcov manual
X-Git-Tag: basepoints/gcc-16~7903
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=229bf66f8d5d6df2997cee37575241cae944e4a6;p=thirdparty%2Fgcc.git

Add section on MC/DC in gcov manual

gcc/ChangeLog:

	* doc/gcov.texi: Add MC/DC section.
---

diff --git a/gcc/doc/gcov.texi b/gcc/doc/gcov.texi
index c118061aed5..fa5bdd3d452 100644
--- a/gcc/doc/gcov.texi
+++ b/gcc/doc/gcov.texi
@@ -890,6 +890,78 @@ 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.
 
+When you use the @option{-g} option, your output looks like this:
+
+@smallexample
+$ gcov -t -m -g tmp
+        -:    0:Source:tmp.cpp
+        -:    0:Graph:tmp.gcno
+        -:    0:Data:tmp.gcda
+        -:    0:Runs:1
+        -:    1:#include <stdio.h>
+        -:    2:
+        -:    3:int
+        1:    4:main (void)
+        -:    5:@{
+        -:    6:  int i, total;
+        1:    7:  total = 0;
+        -:    8:
+       11:    9:  for (i = 0; i < 10; i++)
+condition outcomes covered 2/2
+       10:   10:    total += i;
+        -:   11:
+       1*:   12:  int v = total > 100 ? 1 : 2;
+condition outcomes covered 1/2
+condition  0 not covered (true)
+        -:   13:
+       1*:   14:  if (total != 45 && v == 1)
+condition outcomes covered 1/4
+condition  0 not covered (true)
+condition  1 not covered (true false)
+    #####:   15:    printf ("Failure\n");
+        -:   16:  else
+        1:   17:    printf ("Success\n");
+        1:   18:  return 0;
+        -:   19:@}
+@end smallexample
+
+For every condition the number of taken and total outcomes are
+printed, and if there are uncovered outcomes a line will be printed
+for each condition showing the uncovered outcome in parentheses.
+Conditions are identified by their index -- index 0 is the left-most
+condition.  In @code{a || (b && c)}, @var{a} is condition 0, @var{b}
+condition 1, and @var{c} condition 2.
+
+An outcome is considered covered if it has an independent effect on
+the decision, also known as masking MC/DC (Modified Condition/Decision
+Coverage).  In this example the decision evaluates to true and @var{a}
+is evaluated, but not covered.  This is because @var{a} cannot affect
+the decision independently -- both @var{a} and @var{b} must change
+value for the decision to change.
+
+@smallexample
+$ gcov -t -m -g tmp
+        -:    0:Source:tmp.c
+        -:    0:Graph:tmp.gcno
+        -:    0:Data:tmp.gcda
+        -:    0:Runs:1
+        -:    1:#include <stdio.h>
+        -:    2:
+        1:    3:int main()
+        -:    4:@{
+        1:    5:  int a = 1;
+        1:    6:  int b = 0;
+        -:    7:
+        1:    8:  if (a && b)
+condition outcomes covered 1/4
+condition  0 not covered (true false)
+condition  1 not covered (true)
+    #####:    9:    printf ("Success!\n");
+        -:   10:  else
+        1:   11:    printf ("Failure!\n");
+        -:   12:@}
+@end smallexample
+
 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