Using Uncover

Generating coverage information using Uncover is a three-step process:

1. Instrumenting the binary

2. Running the instrumented binary

3. Generating and viewing coverage reports

Instrumenting the Binary

The input binary can be an executable or a shared library. You must instrument each binary you want to analyze separately.

You instrument the binary with the uncover command. For example, the following command instruments the binary a.out and overwrites the input a.out with the instrumented a.out. It also creates a directory with the suffix .uc (a.out.uc in this case) in which the coverage data will be collected. A copy of the input binary is saved in this directory.

uncover a.out

You can use the following options when instrumenting your binary:

-c

Turn on reporting of execution counts for instructions, blocks, and functions. By default only information on code that is covered or not covered is reported. (Specify this option both when instrumenting your binary and when generating the coverage report.)

-d directory

Tells Uncover to create the coverage data directory in directory. This option is useful when you are collecting coverage data for multiple binaries, so that all of the coverage data directories are created in the same directory. Also, if you run different instances of the same instrumented binary from different locations, using this option ensures that the coverage data from all of these runs is accumulated in the same coverage data directory.

If you do not use the -d option, the coverage data directory is created in the current run directory.

-m on | off

Turns thread-safe profiling on and off. The default is on. Use this option in combination with the -c runtime option. If you instrument a binary that uses threads with -m off, the binary fails at runtime and a message is displayed asking you to reinstrument the binary with -m on.

-o output_binary_file

Writes the instrumented binary file to the specified file. The default is to overwrite the input binary file with the instrumented file.

If you run the uncover command on a input binary that is already instrumented, Uncover issues an error message telling you that the binary cannot be instrumented because it is already instrumented, and that you can run it to generate coverage data.

Running the Instrumented Binary

After you have instrumented your binary, you can run it normally. Every time you run the instrumented binary, code coverage data is collected in the coverage data directory with the .uc suffix that Uncover created during the instrumentation. Since Uncover data collection is multi-thread safe and multi-process safe, there is no restriction on the number of simultaneous runs or threads in the process. The coverage data is accumulated over all of the runs and threads.

Generating and Viewing the Coverage Report

To generate a coverage report, run the uncover command on the coverage data directory. For example:

uncover a.out.uc

This command generates an Oracle Solaris Studio Performance Analyzer experiment directory called binary_name.er from the coverage data in the a.out.uc directory, starts the Performance Analyzer GUI, and displays the experiment. If you have an .er.rc file (see the Oracle Solaris Studio 12.2 Performance Analyzer manual) in the current directory or your home directory, it might affect the way the Analyzer displays the experiment.

You can also use uncover command options to generate the report as HTML and view it in your web browser, as ASCII to view in a terminal window. Or you direct the data to a directory where it can be analyzed and displayed by the Code Analyzer.

-a

Write error data to binary_name.analyze/coverage directory for use by the Code Analyzer.

-c

Turn on reporting of execution counts for instructions, blocks, and functions. By default only information on code that is covered or not covered is reported. (Specify this option both when instrumenting your binary and when generating the coverage report.)

-e on | off

Generate experiment directory for the coverage report and display the experiment in the Performance Analyzer GUI. On by default.

-H html_directory

Save the coverage data as HTML in the specified directory and automatically display it in your web browser. Off by default.

-h or -?

Help.

-n

Generate coverage reports but do not start viewers like the Performance Analyzer or web browser.

-t ascii_file

Generate an ASCII coverage report in the specified file. Off by default.

-V

Print Uncover version and exit.

-v

Verbose. Print a log of what Uncover is doing.

Only one output format is enabled, so if you specify multiple output options, Discover uses the last option in the command.

Examples

uncover a.out

This command instruments the binary a.out, overwrites the input a.out, creates an a.out.uc coverage data directory in the current directory, and saves a copy of the input a.out in the a.out.uc directory. If a.out is already instrumented, a warning message is displayed and no instrumentation is done.

uncover -d coverage a.out

This command does everything that the first example does, except it creates the a.out.uc coverage directory in the directory coverage.

uncover a.out.uc

This command uses the data in the a.out.uc coverage directory to create a code coverage experiment (a.out.er) in your working directory, and starts the Performance Analyzer GUI to display the experiment.

uncover -H a.out.html a.out.uc

This command uses the data in the a.out.uc coverage directory to create an HTML code coverage report in the directory a.out.html and displays the report in your web browser.

uncover -t a.out.txt a.out.uc

This command uses the data in the a.out.uc coverage directory to create an ASCII code coverage report in the file a.out.txt.

uncover -a a.out.uc

This command uses the data in the a.out.c coverage directory to create a coverage report in the binary_name.analyze/coverage directory for use by the Code Analyzer.