NAME

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

SYNOPSIS

ccovinstrument code.c > covcode.c
ccovinstrument code.c -o covcode.c [-e errs]

DESCRIPTION

Scans the 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 myexit croak panic */

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

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 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. Try ccovanalyze!)

BUGS

The code to infer where to add braces {} is horrible.

C++ support untested & probably broken.

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)