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.
If you have a binary a.out and a shared library mylib.so, instrument them as follows:
$ uncover a.out $ uncover mylib.so
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. For uncover, this option is especially important because all three phases of its usage require access to the same exact directory. The –d option used in conjunction with <full_path_of_coverage_directory> ensures that different phases of uncover look for the coverage directory in the same location. If you do not use the –d with full path names, there could be a mismatch in locating the coverage directory, causing other issues such as multiple profile directories with incomplete information.
Enables or disables thread-safe profiling when collecting execution counts with the –c runtime option. This option must be used in conjunction with the –c option or it has no effect. The –c option enables thread-safe profile counting by default. The default is set to on. To collect profile counts for a single-threaded application, use the –c –m off option. This will turn off the thread-safety feature which is unnecessary for single threaded apps and allows a faster profile run.
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 with binary a.out and shared library mylib.so:
$ uncover a.out.uc $ uncover mylib.so.uc
This command generates an Oracle Developer 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 Developer Studio 12.5: 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 3 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 mylib.so
This command instruments the shared library mylib.so, overwrites the input mylib.so, creates a mylib.so.uc coverage data directory in the current directory, and saves a copy of the input mylib.so in the mylib.so.uc directory. If mylib.so is already instrumented, a warning message is displayed and no instrumentation is performed.
$ 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 mylib.so.uc
This command uses the data in the mylib.so.uc coverage directory to create a code coverage experiment mylib.so.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.uc coverage directory to create a coverage report in the binary-name.analyze/coverage directory for use by Code Analyzer.
Each binary in the application needs to be instrumented separately. For instance, if the application has an executable a.out and a shared library libfoo.so, you need to instrument each one in order to receive coverage for both.
This command instruments the executable a.out and shared library libfoo.so.
% uncover -d <coverage_dir> a.out % uncover -d <coverage_dir> libfoo.so
This command runs the application to collect coverage data in <coverage_dir>/a.out.uc and <coverage_dir>/libfoo.so.uc.
% ./a.out
This command displays the executable a.out.
% uncover <coverage_dir>/a.out.uc
This command views coverage for the shared library libfoo.so.
% uncover <coverage_dir>/libfoo.so.uc