[PPL-devel] [GIT] ppl/ppl(master): Added explanation on the use of lcov to produce coverage information.

[Enea Zaffanella]

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

Author: Enea Zaffanella <zaffanella at 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:}
+