From 4043f2c95f4a47e69edc4d451673b7ffda066768 Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Tue, 12 Apr 2016 21:12:10 -0400
Subject: [PATCH] Adopt the LCOV convention for marking lines as unreachable by
 tests.

Document this convention.

Add a script to post-process .gcov files in order to stop nagging us
about excluded lines.

Teach cov-diff to handle these post-processed files.

Closes ticket 16792
---
 changes/lcov_excl           |  7 +++++++
 doc/HACKING/WritingTests.md | 13 +++++++++++++
 scripts/test/cov-diff       |  4 ++--
 scripts/test/cov-exclude    | 28 ++++++++++++++++++++++++++++
 4 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 changes/lcov_excl
 create mode 100755 scripts/test/cov-exclude

diff --git a/changes/lcov_excl b/changes/lcov_excl
new file mode 100644
index 000000000..474181cfa
--- /dev/null
+++ b/changes/lcov_excl
@@ -0,0 +1,7 @@
+  o Minor features (testing):
+    - Use the lcov convention for marking lines as unreachable, so that
+      we don't count them when we're generating test coverage data.
+      Update our coverage tools to understand this convention.
+      Closes ticket #16792.
+
+
diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md
index bd2ee0ea9..7bcadc608 100644
--- a/doc/HACKING/WritingTests.md
+++ b/doc/HACKING/WritingTests.md
@@ -109,6 +109,19 @@ To count new or modified uncovered lines in D2, you can run:
 
     ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l
 
+### Marking lines as unreachable by tests
+
+You can mark a specific line as unreachable by using the special
+string LCOV_EXCL_LINE.  You can mark a range of lines as unreachable
+with LCOV_EXCL_START... LCOV_EXCL_STOP.  Note that older versions of
+lcov don't understand these lines.
+
+You can post-process .gcov files to make these lines 'unreached' by
+running ./scripts/test/cov-exclude on them.
+
+Note: you should never do this unless the line is meant to 100%
+unreachable by actual code.
+
 
 What kinds of test should I write?
 ----------------------------------
diff --git a/scripts/test/cov-diff b/scripts/test/cov-diff
index 48dbec9d5..7da7f0be9 100755
--- a/scripts/test/cov-diff
+++ b/scripts/test/cov-diff
@@ -9,8 +9,8 @@ DIRB="$2"
 
 for A in $DIRA/*; do
   B=$DIRB/`basename $A`
-  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"
-  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"
+  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"
+  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"
   diff -u "$A.tmp" "$B.tmp"
   rm "$A.tmp" "$B.tmp"
 done
diff --git a/scripts/test/cov-exclude b/scripts/test/cov-exclude
new file mode 100755
index 000000000..5117f11ec
--- /dev/null
+++ b/scripts/test/cov-exclude
@@ -0,0 +1,28 @@
+#!/usr/bin/perl -p -i
+
+use warnings;
+use strict;
+our $excluding;
+
+# This script is meant to post-process a .gcov file for an input source
+# that was annotated with LCOV_EXCL_START, LCOV_EXCL_STOP, and LCOV_EXCL_LINE
+# entries.  It doesn't understand the LCOV_EXCL_BR* variations.
+#
+# It replaces unreached reached lines with x:, and reached excluded lines
+# with !!!num:.
+
+BEGIN { our $excluding = 0; }
+
+if (m/LCOV_EXCL_START/) {
+  $excluding = 1;
+}
+if ($excluding and m/LCOV_EXCL_STOP/) {
+  $excluding = 0;
+}
+
+my $exclude_this = (m/LCOV_EXCL_LINE/);
+
+if ($excluding or $exclude_this) {
+  s{^\s*\#\#+:}{        x:};
+  s{^   (\s*)(\d+):}{$1!!!$2:};
+}