GCT 1.4 Patchlevel 0 Jan 28, 1993 The Generic Coverage Tool (GCT) is a freeware coverage tool that measures how thoroughly tests exercise C programs. Version 1.4 is the "ease of use" release. It contains no new types of coverage, but it makes coverage easier to use and provides more powerful reporting tools. GCT can measure the following: - how often branches have been taken in either direction. (branch coverage) - how often cases in switches have been taken. - how often nested logical conditions have evaluated to true and false (multiple condition coverage) - how often loops have iterated zero, one, and more than one times (loop coverage) - how often the boundaries of relational operators have been probed (relational coverage) - how often routines have been entered - how often call sites have been exercised - how often routines have had multiple threads of execution in them - weak mutation coverage (a research technique). If you use branch coverage, you will find the combination of branch, multiple condition, loop, and relational operator coverage to be more effective at little extra cost. Routine and call coverage are useful for system testing. Race coverage is useful for system testing of multiprocessor systems. The tool has been widely used in production environments, including testing the UNIX kernel. MECHANISM The tool takes C source code, adds instrumentation, then uses the system C compiler (or a compiler of your choice) to produce an object file. Alternately, the instrumented source can be captured and moved to another machine for compilation. GCT is designed to work with existing makefiles (or other system build mechanisms). Most makefiles will require no changes. For efficiency's sake, coverage information is stored in an internal log. The log is written on exit (or, in the case of an unending program like the UNIX kernel, extracted from the running program). Instrumented programs run slower than the original programs. How much slower depends on the program, how much of it is instrumented, and what types of coverage are measured. An instrumented GCT runs 44% slower than normal. (I instrument GCT to measure branch, loop, multiple condition, and relational coverage.) Reporting tools produce detailed or summary reports on missing coverage. They can also report on particular routines or files. RETRIEVING GCT GCT is available via anonymous FTP from cs.uiuc.edu. The current version is in the directory pub/testing/gct.files. To retrieve GCT, go to that directory and fetch one of these files: ftp.ps (postscript) or ftp.txt (formatted to be read online). Follow those instructions. If you do not have access to anonymous FTP, you can use a mail server to mail you GCT (in pieces). Send mail to ftpmail@decwrl.dec.com. The body of the message should include these commands: reply who-you-are@where-you-are connect cs.uiuc.edu binary compress dir pub/testing/gct.files chdir pub/testing/gct.files get ftp.ps quit MAILING LIST Gct@cs.uiuc.edu is a mailing list for GCT users. It is used to distribute bug reports, bug fixes, troubleshooting hints, proposed major and minor revisions, documentation errata, and anything else of interest to GCT users. Mail to Gct-Request@cs.uiuc.edu will get you added to the list. DEFICIENCIES 1. The tool itself runs only on UNIX, although the instrumented code may be compiled wherever you like. (An earlier version of GCT also ran on Apollo Aegis SR10; porting this version is probably trivial.) 2. The tool is based on the GNU C compiler and still contains the original code generation and optimization routines. This has two practical disadvantages: - The tool is large. For the full installation (which includes the source, compiled executables, a large test suite, and all the documentation), you will need roughly 33,000 1K blocks. (The tests - which are not required - take up about 17,000 blocks.) The final executables will require roughly 3000 1K blocks. - The original compiler is made portable through machine and system configuration files. These must still be used. The distribution includes configuration files for many different machines. If there isn't one for your machine, you may be able to use one for a similar machine. ADVERTISING I provide GCT as a public service - and as a concrete demonstration of my skills. I provide testing tools, training, and consulting. Contact me at: Brian Marick Testing Foundations 913 W. White Champaign, IL 61821 (217) 351-7228 marick@testing.com NEW FEATURES This is a list of changes from GCT 1.3: - GCT now behaves like a true compiler. After instrumenting, it calls the C compiler. The original source is never touched. The old behavior is retained as an option. - GCT can insert gct_readlog and gct_writelog calls for you. You needn't edit the source. Original behavior is retained as an option. - More flexible reporting tools (including per-file and per-routine reports from greport and gsummary) - Better control over the interface to different C compilers. - More flexibility in editing (suppressing, ignoring) mapfile entries. - Previously unsupported ANSI C constructs now supported - Optional locking of logfiles - Numerous minor usability improvements UPGRADING FROM GCT 1.3 1. The tutorial describes most of the changes; be sure to run it. 2. (options files) has gone away. (options instrument) now plays roughly the same role. 3. Expect to change any GCT target in your makefile. In the best case, you won't need any GCT target. Just type % gct-init % make CC=gct 4. If you've made any changes to gct-ps-defs.c, be aware that gct-init now overwrites that file. 5. gct-init still does not overwrite gct-write.c and gct-defs.h. Since they've both changed in GCT 1.4, you'll have to delete old versions manually. (gclean(1) is a good idea.) 6. `gct' is now a shell script that interfaces the true executable to `cc'. By new convention, each compiler has its own shell script. For example, to compile instrumented code with `xcc', use a shell script called `gct-xcc'. These scripts should be created at installation time. 7. Routines in included files are not instrumented. Set (options instrument-included-files) if that's what you want.