Enabling statically instrumented code coverage from the command line

You can enable static instrumentation of your code from a command line.

About this task

You can only instrument code from a command line if you are working on the same computer where the you installed the product.

To statically instrument your code from a command line:

Configure your CLASSPATH to enable code coverage.
Run the code coverage instrumentation script .

You may also generate code coverage reports from outside the workbench and disable code coverage from the command line.

Procedure

Configure your CLASSPATH to enable code coverage.

Run the code coverage instrumentation script.

On Windows, the instrumentation script is instrument.bat; on Linux, instrument.sh. The format of the instrumentation script is: instrument.bat/sh -in <src-input-directory> [-baseline <baseline-file>] [-saveBackup] [-verbose] [-output <output-dir>] [-javaVerifier {this attribute is necessary if class is complied by Java 7, do not add this attribute if class is complied by Java 6}] [-exclude <class and or packages to exclude from instrumentation>] [-include <class and or packages to include for instrumentation>]

where:

Table 1.
Header	Header
in	Specifies the "path separated" list of the directories which contain the class files that are to be instrumented. The path separator is operating system dependent (a semicolon ";" on Windows and a colon ":" on Linux).
baseline	Specifies the path where the baseline file is stored. Use this only if you intend to generate code coverage reports from outside the workbench. The baseline file is the file against which the instrumented code is compared and the code coverage statistics are generated. It serves as input to the code coverage report generator.
saveBackup	Specifies whether to rename original class and jar files to *.bak. Including the saveBackup option will generate the back up files; omitting the option results in the overwrite (and therefore loss) of the original files.
verbose	Specifies that informational messages should be printed.
output	Specifies the output directory where the instrumented files are to be stored; otherwise, instrumented files are stored in the input directory.
javaVerifier	This attribute is necessary if class is complied by Java™ 7. Do not add this attribute if class is complied by Java 6.
include	Specifies which packages and/or classes to include in instrumentation
exclude	Specifies which packages and/or classes (if any) to exclude from instrumentation

Important: For more information on how to use filtering, its syntax and rules, see Granular filter support for code coverage enabled from command line and an Ant script (Static and Dynamic Instrumentation).

Example

In the following example, code coverage is enabled for the files in the Windows directories C:\java_code and C:\java_tests and no backups are generated for these files. The baseline file is stored in C:\llc\coverage_reports, informational messages are printed, and the output files are stored in C:\instrumented_files, and the attribute is -javaVerifier. This attribute is necessary if the class is complied by Java 7. Do not add this attribute if the class is complied by Java 6.

For class that is compiled by Java 6:

instrument.bat -in C:\java_code;C:\java_tests -baseline C:\llc\coverage_reports -verbose -output C:\instrumented_files

For class that is compiled by Java 7:

instrument.bat -in C:\java_code;C:\java_tests -baseline C:\llc\coverage_reports -verbose -output C:\instrumented_files  -javaVerifier

In the following example, code coverage is enabled for the files in the Linux directories C:/java_source and C:/testcase_source and backups are generated for these files. No baseline file is created, no informational messages are printed, and the output files are stored in C:/instrumented_files

instrument.sh -in /java_source:/testcase_source -saveBackup -output /instrumented_files

What to do next

Generating code coverage reports from outside the workbench: Refer to Generating code coverage reports.
Disabling code coverage from the command line: To disable classes instrumented from the command line, re-compile the project or replace the .class files with the .class.bak files, if saveBackup was enabled.

Note: If you encounter the Probekit error below when you use the JDK shipped with v9.x of the product as JAVA_HOME, add the path of jvm library to the PATH environment variable, for example, on Windows, %JAVA_HOME%\jre\bin;%JAVA_HOME%\jre\bin\classic; on Linux, ${JAVA_HOME}/jre/bin:${JAVA_HOME}/jre/bin/classic.

Probekit error:
source: Driver, message: Error loading the jvm library.  Put the jre/bin and jre/bin/classic in the path.

Feedback