Creating coverage statistics using gcov
=======================================

$Id: README.coverage.txt,v 1.1 2000/12/03 04:09:49 pascal Exp $

What is gcov
============

The program gcov creates coverage statistics for C source files. Coverage
statistics show how often every line in a source file has been executed.
This helps to ensure that the code is tested thoroughly.


Creating coverage statistics for Mobilizer
==========================================

Look at the Makefile in the top-level directory of Mobilizer. Make sure it
contains a line saying:

 COVERAGE=yes

Then, recompile by typing:

   $ make clean
   $ make test
   
After the test application has been successfully built, you can type:

   $ make coverage

This target automatically executes the test application and runs gcov for
all the .cpp files that it can find. If everything goes well (i.e. the
system has gcov and it works allright), then two files will be created:

   documentation/coverage/STATISTICS

which contains statistical information of the form:

   ...
   100.00% of 1 source lines executed in file WMLScriptContinueException.h
   Creating WMLScriptContinueException.h.gcov.
     0.00% of 1 source lines executed in file WMLScriptCorruptParseTreeException.h
   Creating WMLScriptCorruptParseTreeException.h.gcov.
    91.91% of 519 source lines executed in file WMLScriptInterpreter.cpp
   Creating WMLScriptInterpreter.cpp.gcov.
   ...

And the file

   documentaiton/coverage/coverage-<date>.tar.gz

Containing all the .gcov output files. A .gcov output file looks like the
original source code, but with every line of code prefixed by the number of
times that that line of code was executed. If a line of code was never
executed, it is prefixed by '######'.

For more information on gcov, type:

   $ info gcc
   
And follow the links from the table of contents.

Bugs
====

- gcov aborts and dumps core on many input files when using Red Hat 7.0. Try
another system.

