uncover - Code Coverage Tool
Instrumentation Step :
uncover
[-?] [-h] [-c] [-d dir] [-m {on | off}]
[-o output-binary-file] [-v] [-V] target
Analysis Step :
uncover
[-?] [-h] [-a] [-c] [-e {on|off}] [-H dir] [-n]
[-t file] [-v] [-V] target.uc
uncover is a command line tool to measure code coverage of your applications. This tool can display information on areas of the application being exercised during testing. The coverage information reported by this tool could be at a function, statement, basic block, or instruction level.
Measurements are done by first instrumenting the binaries, then executing the binaries. After execution, you can query the coverage data based on the execution. You can execute the binaries multiple times, and the coverage data will be the accumulation of these multiple executions.
target is the binary file for which the code coverage data is to be generated. target.uc is the directory where the code coverage data is generated and stored.
uncover is not compatible with binaries compiled with versions of Studio older than Oracle Developer Studio 12 update 1. It works on a SPARC-based or x86-based system running the Solaris 10 10/08 operating system or a later Solaris 10 update, or Oracle Solaris 11 or Oracle Linux OS versions 5.x or a later update.
uncover works with any binary built with Oracle Developer Studio compilers, but works best with binaries built with no optimization option. (Previous releases of uncover required at least the -O1 optimization level.) If your binary is built with an optimization option, uncover results will be better with lower optimization levels (-O1 or -O2). uncover derives the source line level coverage by relating the instructions to line numbers using the debug information generated when the binary is built with the -g option. At optimization levels -O3 and higher, the compiler might delete some code that might never be executed or is redundant, which might result in no binary instructions for some source code lines. In such cases, no coverage information will be reported for those lines.
Binaries compiled with any of the following compiler options are incompatible with uncover: -p, -pg, -qp, -xpg, and -xlinkopt.
See the Oracle Developer Studio 12.6: Discover and Uncover User’s Guide for more information.
uncover accepts the following options:
Output the help message.
Write error data to binary-name.analyze/coverage directory for use by Code Analyzer (the graphic tool code-analyzer or the command-line tool codean).
Turn on reporting of execution counts for instructions, blocks, and functions. By default only information on which code is covered or not covered is reported. Specify this option both when instrumenting your binary and when generating the coverage report.
Create coverage data inside the specified directory dir. If not specified, the current working directory is used. The coverage data directory will be named target.uc underneath the directory dir. Use of this flag is strongly recommended if running the binary in different locations. It assures that no matter where you run the binary and how many times you run it, the coverage data will be accumulated in a single .uc directory for all runs. Also, using -d flag is necessary if the directory where instrumentation happens is different from the run directory. This is because the instrumentation step creates and initializes the .uc directory and the run step accumulates coverage information in the .uc directory.
Turn on or off the invocation of the Performance Analyzer. Default is on.
Display the coverage data in HTML format inside dir. When specified, the default browser will be invoked to display the coverage data stored in dir.
When instrumenting your program, turns thread-safe profiling on and off. 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.
Do not start the GUI viewer to display the coverage data. When both -n and -H options are absent, the Oracle Developer Studio Performance Analyzer will be invoked to display the coverage data.
Write the instrumented binary file to output_binary_file. The default is to overwrite the input binary file with the instrumented file.
Display the coverage data in ASCII text in the file file.
Turn on the verbose mode, showing detailed info on steps of the command.
Print the current version.
This example will instrument the binary a.out, next execute the binary, and finally display the coverage data of a.out stored in a.out.uc by invoking the Performance Analyzer.
% uncover a.out % a.out % uncover a.out.uc
Note: You only need to instrument the binary of interest once.
Example 2 Generate coverage data directory.Similar to example #1, but the coverage data directory a.out.uc is generated underneath the directory abc.
% uncover -d abc a.out % a.out % uncover abc/a.out.ucExample 3 Display coverage data in HTML format.
Similar to example #1, but the binary was executed three times. The coverage data to be displayed are in HTML format inside the directory a.out.html. The default browser will be invoked to display this data.
% uncover a.out % a.out; a.out; a.out % uncover -H a.out.html a.out.ucExample 4 Example of ASCII coverage report generated by uncover.
The following is an example of an ASCII coverage report generated by uncover:
% uncover -t unc.report a.out.uc
Creating experiment database a.out.er ...
% cat unc.report
UNCOVER Code Coverage
Total Functions: 6
Covered Functions: 3
Function Coverage: 50.0%
Total Executable Source Lines (Excludes redundant code removed by
compiler): 38
Source Line Coverage: 57.9%
Total Basic Blocks: 19
Covered Basic Blocks: 11
Basic Block Coverage: 57.9%
Total Basic Block Executions: 11
Average Executions per Basic Block: 0.58
Total Instructions: 149
Covered Instructions: 75
Instruction Coverage: 50.3%
Total Instruction Executions: 75
Average Executions per Instruction: 0.50
Number of times this program was executed: 1
Functions sorted by metric: Exclusive Uncoverage
Excl. Excl. Excl. Excl. Excl. Name
Uncoverage Function Instr Block Instr
Count Exec Covered % Covered %
172 3 75 238 225 <Total>
80 0 0 0 0 t3
60 0 0 0 0 bar
32 0 0 0 0 t2
0 1 16 75 45 foo
0 1 51 63 80 main
0 1 8 100 100 t1
Instruction frequency data from experiment a.out.er
Instruction frequencies of /export/home1/uncover.demo/a.out.uc/a.out
Instruction Executed ()
TOTAL 75 (100.0)
float ops 0 ( 0.0)
float ld st 0 ( 0.0)
load store 12 ( 16.0)
load 8 ( 10.7)
store 4 ( 5.3)
--------------------------------------
Instruction Executed () Annulled In Delay Slot
TOTAL 75 (100.0)
call 13 ( 17.3) 0 0
add 9 ( 12.0) 0 5
sethi 9 ( 12.0) 1 3
nop 7 ( 9.3) 0 7
br 6 ( 8.0) 0 0
lduw 6 ( 8.0) 0 0
or 5 ( 6.7) 0 2
subcc 5 ( 6.7) 0 0
stw 3 ( 4.0) 0 0
save 3 ( 4.0) 0 0
jmpl 3 ( 4.0) 0 0
restore 3 ( 4.0) 0 3
ldsb 2 ( 2.7) 0 1
stb 1 ( 1.3) 0 0
============================================================
Example 5 Getting coverage for shared libraries
Getting coverage data for a shared library is similar. Instrument the library using uncover, run the applications that use this shared library, use uncover to get coverage report.
% uncover -d coverage-dir lib-dir/libfoo.so
Where coverage-dir is the directory where you need the coverage data for all the runs to accumulate in coverage-dir/libfoo.so.uc and lib-dir is the directory where the library libfoo.so resides. Assuming your executables have dynamic dependency on libfoo.so or use dlopen to call libfoo.so, the raw coverage information will get accumulated for all these runs in coverage-dir/libfoo.so.uc.
Use uncover to view the coverage information in any of the four following formats:
Performance Analyzer graphical tool
% uncover coverage-dir/libfoo.so.uc
ASCII report
% uncover -t text-report coverage-dir/libfoo.so.uc
HTML report
% uncover -h html-report coverage-dir/libfoo.so.uc
Code Analyzer report
% uncover -a coverage-dir/libfoo.so.uc
The previous command creates a directory called libfoo.so.analyze in the same directory as libfoo.so. Use codean (text output) or code-analyzer (GUI) to view the results as follows:
% codean lib-dir/libfoo.so
% code-analyzer lib-dir/libfoo.so
It is possible to collect coverage for a running process without it needing to exit. This may be useful for long-running applications which do not exit. This can be done by attaching to the running process using dbx and calling a function called __uncover_update_coverage().This will accumulate the profile to the directory named <binary>.uc.Results can be viewed by running the uncover command on <binary>.uc, just as it is described in the previous sections.
Here is a dbx script for doing this and its usage:
% cat dbx_uncover.sh #!/bin/sh dbx - $1 << END call __uncover_update_coverage() exit END % uncover a.out // Instrument % a.out // Start the application
In a separate window, type the following command:
% dbx_uncover.sh <process id of a.out>
The command above accumulates the profile to a.out.uc.
To view the results, type the following command:
% uncover a.out.uc