Merge remote-tracking branch 'catalyst-oniongit/bug23739'

This commit is contained in:
Nick Mathewson 2017-10-03 09:04:21 -04:00
commit bc6769e0d4
3 changed files with 23 additions and 8 deletions

3
changes/bug23739 Normal file
View File

@ -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.

View File

@ -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
-------------------------

View File

@ -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.