commit 6a2a49e6616702c39e56c21091167316a82fcc85 Author: Taylor Yu catalyst@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.