Generating coverage information using Uncover is a three-step process:
This section covers the three steps and provides examples of using Uncover.
The input binary can be an executable or a shared library. You must instrument each binary that 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:
Enable 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.
Creates the coverage data directory in directory. This option is useful when you are collecting coverage data for multiple binaries because 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.
Enables or disables thread-safe profiling. 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.
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 an input binary that is already instrumented, uncover issues an error message that the binary cannot be instrumented because it is already instrumented, and that you can run it to generate coverage data.
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. Because 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.
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. The presence of an .er.rc file in the current directory or your home directory might affect the way Performance Analyzer displays the experiment. For more information about .er.rc files, see Oracle Solaris Studio 12.4: Performance Analyzer
You can generate the report as HTML and view it in your web browser or as ASCII to view in a terminal window. You can also direct the data to a directory where Code Analyzer can analyze and display it.
Write error data to binary-name.analyze/coverage directory for use by Code Analyzer.
Enables 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.)
Determines whether to generate experiment directory for the coverage report and display the experiment in the Performance Analyzer GUI. The default is on.
Save the coverage data as HTML in the specified directory and automatically display it in your web browser.
Display help.
Generate coverage reports but do not start viewers like Performance Analyzer or web browser.
Generate an ASCII coverage report in the specified file.
Print uncover version and exit.
Verbose. Print a log of what Uncover is doing.
Only one output format is enabled. If you specify multiple output options, uncover uses the last option in the command.
Example 2 uncover 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 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 Performance Analyzer 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 Code Analyzer.