commit 6a2a49e6616702c39e56c21091167316a82fcc85
Author: Taylor Yu <catalyst(a)torproject.org>
Date: Mon Oct 2 14:51:48 2017 -0500
Improve docs on using gcov
Add more explanation in doc/HACKING about how to read gcov output,
including a reference to the gcov documentation in the GCC manual.
Also add details about how our postprocessing scripts modify gcov
output.
---
changes/bug23739 | 3 +++
doc/HACKING/HelpfulTools.md | 22 +++++++++++++++-------
doc/HACKING/WritingTests.md | 6 +++++-
3 files changed, 23 insertions(+), 8 deletions(-)
diff --git a/changes/bug23739 b/changes/bug23739
new file mode 100644
index 000000000..3207b5eaf
--- /dev/null
+++ b/changes/bug23739
@@ -0,0 +1,3 @@
+ o Minor bugfixes (documentation):
+ - Document better how to read gcov and what our postprocessing scripts do.
+ Fixes bug 23739; bugfix on 0.2.9.1-alpha.
diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md
index b8ba2aa40..f919d08ec 100644
--- a/doc/HACKING/HelpfulTools.md
+++ b/doc/HACKING/HelpfulTools.md
@@ -111,15 +111,19 @@ Running gcov for unit test coverage
(On OSX, you'll need to start with `--enable-coverage CC=clang`.)
-Then, look at the .gcov files in `coverage-output`. '-' before a line means
-that the compiler generated no code for that line. '######' means that the
-line was never reached. Lines with numbers were called that number of times.
-
If that doesn't work:
* Try configuring Tor with `--disable-gcc-hardening`
* You might need to run `make clean` after you run `./configure`.
+Then, look at the .gcov files in `coverage-output`. '-' before a line means
+that the compiler generated no code for that line. '######' means that the
+line was never reached. Lines with numbers were called that number of times.
+
+For more details about how to read gcov output, see the [Invoking
+gcov](https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html) chapter
+of the GCC manual.
+
If you make changes to Tor and want to get another set of coverage results,
you can run `make reset-gcov` to clear the intermediary gcov output.
@@ -128,9 +132,13 @@ a meaningful diff between them, you can run:
./scripts/test/cov-diff coverage-output1 coverage-output2 | less
-In this diff, any lines that were visited at least once will have coverage
-"1". This lets you inspect what you (probably) really want to know: which
-untested lines were changed? Are there any new untested lines?
+In this diff, any lines that were visited at least once will have coverage "1",
+and line numbers are deleted. This lets you inspect what you (probably) really
+want to know: which untested lines were changed? Are there any new untested
+lines?
+
+If you run ./scripts/test/cov-exclude, it marks excluded unreached
+lines with 'x', and excluded reached lines with '!!!'.
Running integration tests
-------------------------
diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md
index 4dae41e92..cc393494e 100644
--- a/doc/HACKING/WritingTests.md
+++ b/doc/HACKING/WritingTests.md
@@ -91,6 +91,9 @@ coverage percentage.
For a summary of the test coverage for each _function_, run
`./scripts/test/cov-display -f ${TMPDIR}/*`.
+For more details on using gcov, including the helper scripts in
+scripts/test, see HelpfulTools.md.
+
### Comparing test coverage
Sometimes it's useful to compare test coverage for a branch you're writing to
@@ -117,7 +120,8 @@ 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.
+running ./scripts/test/cov-exclude on them. It marks excluded
+unreached lines with 'x', and excluded reached lines with '!!!'.
Note: you should never do this unless the line is meant to 100%
unreachable by actual code.