Module: ppl/ppl Branch: master Commit: ed61e6fdbf3c3595b223cda8d955a93f13011692 URL: http://www.cs.unipr.it/git/gitweb.cgi?p=ppl/ppl.git;a=commit;h=ed61e6fdbf3c3...

Author: Enea Zaffanella zaffanella@cs.unipr.it Date: Thu Jun 11 10:56:06 2009 +0200

Added explanation on the use of lcov to produce coverage information.

---

STANDARDS | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/STANDARDS b/STANDARDS index cebaa8a..43654aa 100644 --- a/STANDARDS +++ b/STANDARDS @@ -559,8 +559,13 @@ o Refer to the existing tests for examples. Many tests are written along o Ideally the tests should exercise every line of code in the library. To help ensure that, the test-coverage facilities provided by GCC are very useful. They are described in Chapter 9 of the GCC manual - ("`gcov'---a Test Coverage Program"). For a shorter introduction, - the build tree under test must be configured with the + ("`gcov'---a Test Coverage Program"). For a simpler user interaction + with gcov, also including the generation of nicer HTML output, the + adoption of `lcov' is recommended (LCOV, the Linux Test Project GCOV + extension, http://ltp.sourceforge.net/coverage/lcov.php). + Here we summarize the steps needed to produce coverage information + using `lcov' (see below for a few hints on the direct use of `gcov'). + The build tree under test must be configured with the `--enable-coverage' and `--disable-optimization options' (and possibly also with --enable-profiling). For example:

@@ -570,8 +575,51 @@ o Ideally the tests should exercise every line of code in the library.

Running the tests (with `make check') produces many .gcno and .gcda files in src/.libs and in the test directories. These are data - files for the `gcov' program. The `gcov' program produces coverage - information. For example: + files for the `gcov' program. All the coverage data produced can be + automatically collected by `lcov' using the following command: + + $ lcov --directory . --capture --output-file ppl-lcov.info + + To generate HTML pages with the graphical view of the captured data, + use the `genhtml' command: + + $ genhtml ppl-lcov.info --output-directory ppl-lcov-html + + Coverage info can now be seen by pointing your favorite browser to + file ppl-lcov-html/index.html. The annotated sources will look like + the following (plus color information), where the value on the left + hand side of the colon is the number of executions of the corresponding + line of code (see also below on the use of coverage counters): + + 1636 : PPL_DIRTY_TEMP(N, sum); + 9828 : for (dimension_type k = num_dimensions + 1; k-- > 0; ) { + 6556 : const DB_Row<N>& x_dbm_k = x.dbm[k]; + 39648 : for (dimension_type i = num_dimensions + 1; i-- > 0; ) { + 26536 : DB_Row<N>& x_dbm_i = x.dbm[i]; + 26536 : const N& x_dbm_i_k = x_dbm_i[k]; + 26536 : if (!is_plus_infinity(x_dbm_i_k)) + 55128 : for (dimension_type j = num_dimensions + 1; j-- > 0; ) { + 36904 : const N& x_dbm_k_j = x_dbm_k[j]; + 36904 : if (!is_plus_infinity(x_dbm_k_j)) { + : // Rounding upward for correctness. + 12136 : add_assign_r(sum, x_dbm_i_k, x_dbm_k_j, ROUND_UP); + 12136 : min_assign(x_dbm_i[j], sum); + : } + : } + : } + : } + + Note that the collection of coverage information is incremental: + running again any tests will add to coverage counters (in order + to see the changes, coverage data has to be re-captured using the + `lcov' command and HTML pages re-generated using the `genhtml' command). + Coverage counters can be reset to zero by issuing the command: + + $ lcov --directory . --zerocounters + + As said above, `lcov' is just a wrapper on top of `gcov'. The direct + use of `gcov' produces plain-text based coverage information. + For example:

$ cd src $ gcov -o .libs Grid_public.cc @@ -613,3 +661,4 @@ o Ideally the tests should exercise every line of code in the library. -: 1015: // All checks passed. 48245: 1016: return true; -: 1017:} +