Analyze Coverage
This program uses the 'gcov' code coverage analysis program to determine which 
source lines in a set of files have been used by one or more programs 
execution.

The source files must be compiled by gcc with the flags 
"-fprofile-arcs -ftest-coverage -O0". 
>> Optimization will produce incorrect results.<< 

To do this, set your environment variables like this:
export CFLAGS="-fprofile-arcs -ftest-coverage -O0"
export CXXFLAGS="fprofile-arcs -ftest-coverage -O0"
before performing the configure.

Compilation will create files with the extensions "bb" and "bbg" in addition 
to the ".o". These are used by gcov and serve as proof the the object code 
will support gcov. Once a program which uses the code has been run there will 
also be a file with the extension ".da" for each object file that has code 
that has been used in the execution of the program. No ".da" file will exist 
if the program has not used any of the functions in that object file. 
The ".da" file contains the information about execution that is processed by 
the gcov program. These files record information cumulatively; each execution 
of a program that uses this object code will add further usage information. 
The code line usage statistics represent the sum of the usage by each program 
execution. This allows you to determine the test coverage of a single program 
run several time with different input arguments as well as different programs.

"analyze_coverage" processes all files in one or more directories of object 
code to compute the fraction of each file's executable lines of code have 
actually been used. These statistics are combined for summary statistics of 
about usage and are reported individually for each file. These are combined 
into a single line with the values separated by commas, the standard .csv 
format for ready import into a spreadsheet. 

The analyze_coverage command line uses very few options:
 -h or -help for the simple help message
-H or --Header to print a header line for the spreadsheet. 
-t or --testname, the identifying name that will be the first entry in the 
output line to identify the run. This is important if  several different runs 
of analyze_coverage are to be combined into a single spreadsheet.

The remaining arguments are used to identify the directories that contain the 
object code. All object files in all directories listed will be processed and 
reported. 
Each successive argument after the flags defines a directory that will be 
processed by analyze_coverage. This path is relative to your current directory.
The safest means of defining the directories is with a full path. 

analyze_coverage is designed to be run several times with different sets of 
test programs. The first run will use the -Header flag to add a header line for
the spreadsheet. The results of each run of analyze_coverage should 
concatenated to generate a two dimensional spreadsheet. A series of tests can 
be automated by the higher level program 'coverage_test' which repetitively 
calls analyze_coverage to generate the full spread sheet. 'coverage_test' is 
described in the file "README.coverage_test" in this directory.

Read the man page for more details about 'gcov'.

Note: coverage_test is a python program; the python interpreter should already 
      be in your path. If you have problems running the coverage test program
      confirm that you can execute python.
