NAME

  ccovinstrument - instruments C/C++ code for test coverage analysis

SYNOPSIS

  ccovinstrument code.c > covcode.c
  ccovinstrument code.c [-f] -o covcode.c [-e errs]
     -f    instrument fatal code as well as normal code

DESCRIPTION

Scans C/C++ source (before cpp) and inserts trip-wires in each code path to record execution.

A number of error prone coding styles are also detected. Many of these ideas came from study of the highly regarded perl5 source code (and from my own coding experience :-).

This approach (or almost any approach) to coverage analysis is NOT fullproof! Just because you exercise every code path does NOT mean you have exercised all possibilities. For example, consider the following code:

  char
  fetch_char(int xx)
  {
    static char *string = "Dr. Zorph Trokien";
    if (xx < 0) {
      return 0;
    } else {
      return string[xx];
    }
  }

Unfortunately, you still have to be somewhat intelligent about designing your test scripts. However, assuming you're clever, you can use this tool to know when to stop writing more tests. Thus, thereby achieving test coverage.

CCov SOURCE DIRECTIVES

• /* CCov: off */

  Turns off coverage instrumentation. You probably don't want to analyze debugging code.

• /* CCov: on */

  Turns on coverage instrumentation.

• /* CCov: jump if for do while else return */

  Adds to the list of identifiers that cause a change in execution flow. In addition to the usual keywords, macros used by the perl core and XSUBs are included by default.

• /* CCov: fatal myexit croak panic */

  Adds to the list of identifiers that cause a fatal exception. Instrumentation of these blocks is turned off by default. (You usually want to make sure the code is suppose to work works before you make sure that the code that isn't support to work works.)

CCov LIMITATIONS

• {}

  Braces are required when control-flow directives are nested. This is reasonable since it makes code easier to maintain. Arbitrary cut-and-paste is less likely to mess up correctness.

• ||

  In general, CCov prefers that the || operator not be used in if tests. If you must use it, you can turn off the warning by adding an /*OK*/ comment inside the if expression.

• ?:

  The ?: operator is not checked.

HOW DOES IT WORK?

The instrumenter processes source code before it is seen by cpp. This helps you isolate your testing. Usually, you want to do test analysis on each library/application individually. A global analysis would cause you to test new code and all the libraries you are using (for every single application!).

The instrumentor does not really use a lexer (tokenizer). The techniques are probably more similar to image processing than parsing. As you might imagine, this doesn't work in the general case. CCov tries to be forgiving, but it simply doesn't understand obfuscated code. Rather than calling it a bug, I think it's an significant feature.

Simple code probably has fewer bugs than complex code. Not only is this tool aimed at test coverage analysis, it is also helps you improve your coding style. There are still some rough edges, but I am mostly satisfied with the degree of strictness.

ENVIRONMENT VARIABLE

• REGRESSION_TEST

  The tag used to group together a result set. Defaults to '?FAKE'.

• CCOV_LOG

  The location of the log file. Defaults to '/tmp/ccov.log'.

• CCOV_DB

  The ccovanalyze database. Defaults to './ccov.db'.

• CCOV_VERBOSE

  Cause the instrumented binary to output to stderr complete coverage information upon exit. (Not recommended. Use ccovanalyze!)

BUGS

?

SEE ALSO

Test, Test::Harness

AUTHOR

Copyright © 1998 Joshua Nathaniel Pritikin. All rights reserved.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)