Developer Guide and Reference

Contents

Code Coverage Tool

The code coverage tool provides software developers with a view of how much application code is exercised when a specific workload is applied to the application. To determine which code is used, the code coverage tool uses Profile-guided Optimization (PGO) options and optimizations. The major features of the code coverage tool are listed below:
  • Visually presenting code coverage information for an application with a customizable code coverage coloring scheme
  • Displaying dynamic execution counts of each basic block of the application
  • Providing differential coverage, or comparison, profile data for two runs of an application
The information about using the code coverage tool is separated into the following sections:
The tool analyzes static profile information generated by the compiler, as well as dynamic profile information generated by running an instrumented form of the application binaries on the workload. The tool can generate an HTML-formatted report and export data in both text-, and XML-formatted files. The reports can be further customized to show color-coded, annotated, source-code listings that distinguish between used and unused code.
The code coverage tool is available on all supported Intel architectures on Linux*, Windows*, and
macOS*
operating systems.
You can use the tool in a number of ways to improve development efficiency, reduce defects, and increase application performance:
  • During the project testing phase, the tool can measure the overall quality of testing by showing how much code is actually tested.
  • When applied to the profile of a performance workload, the code coverage tool can reveal how well the workload exercises the critical code in an application. High coverage of performance-critical modules is essential to taking full advantage of the Profile-Guided Optimizations that Intel Compilers offer.
  • The tool provides an option useful for both coverage and performance tuning, enabling developers to display the dynamic execution count for each basic block of the application.
  • The code coverage tool can compare the profile of two different application runs. This feature can help locate portions of the code in an application that are unrevealed during testing but are exercised when the application is used outside the test space, for example, when used by a customer.

Code Coverage Tool Requirements

To run the code coverage tool on an application, you must have following items:
  • The application sources.
  • The .spi file generated by the Intel® compiler when compiling the application for the instrumented binaries using the
    -prof-gen=srcpos
    (Linux and
    macOS*
    ) or
    /Qprof-gen:srcpos
    (Windows) option.
    Use the
    –[Q]prof-gen:srcpos
    option if you intend to use the collected data for code coverage and profile feedback. If you are only interested in using the instrumentation for code coverage, use the
    /Qcov-gen
    option. Using the
    /Qcov-gen
    option saves time and improves performance. This option can be used only on Windows platform for all architectures.
  • A
    pgopti.dpi
    file that contains the results of merging the dynamic profile information (.dyn) files, which is most easily generated by the profmerge tool. This file is also generated implicitly by the Intel® compilers when compiling an application with
    [Q]prof-use
    options with available .dyn and .dpi files.
Using the Tool
The tool uses the following syntax:
Tool Syntax
codecov [-codecov_option]
where
-codecov_option
is one or more optional parameters specifying the tool option passed to the tool. The available tool options are listed in the code coverage tools Options section. If you do not use any additional tool options, the tool will provide the top-level code coverage for the entire application.
In general, you must perform the following steps to use the code coverage tool:
  1. Compile the application using
    -prof-gen=srcpos
    (Linux and
    macOS*
    ) or
    /Qprof-gen:srcpos
    (Windows), and/or
    /Qcov-gen
    (Windows) option.
    This step generates an instrumented executable and a corresponding static profile information (
    pgopti.spi
    ) file when the
    [Q]prof-gen=srcpos
    option is used. When the
    /Qcov-gen
    option is used, minimum instrumentation only for code coverage and generation of .spi file is enabled.
    You can specify both the
    /Qprof-gen=srcpos
    and
    /Qcov-gen
    options on the command line. The higher level of instrumentation needed for profile feedback is enabled along with the profile option for generating the .spi file, regardless of the order the options are specified on the command line.
  2. Run the instrumented application.
    This step creates the dynamic profile information (.dyn) file. Each time you run the instrumented application, the compiler generates a unique .dyn file either in the current directory or the directory specified in by the -prof-dir (Linux or
    macOS*
    ) or /Qprof-dir (Windows) option, or PROF_DIR environment variable. On Windows, you can use the /Qcov-dir or COV_DIR environment variable. These have the same meaning as /Qprof-dir and PROF_DIR.
  3. Use the profmerge tool to merge all the .dyn files into one .dpi (
    pgopti.dpi
    ) file.
    This step consolidates results from all runs and represents the total profile information for the application, generates an optimized binary, and creates the dpi file needed by the code coverage tool.
    You can use the profmerge tool to merge the .dyn files into a .dpi file without recompiling the application. The profmerge tool can also merge multiple .dpi files into one .dpi file using the
    profmerge -a
    option. Select an alternate name for the output .dpi file using the
    profmerge -prof_dpi
    option.
    The profmerge tool merges all .dyn files that exist in the given directory. Confirm that unrelated .dyn files, which may remain from unrelated runs, are not present. Otherwise, the profile information will be skewed with invalid profile data, which can result in misleading coverage information and adverse performance of the optimized code.
  4. Run the code coverage tool. The valid syntax and tool options are shown below.
    This step creates a report or exported data as specified. If no other options are specified, the code coverage tool creates a single HTML file (CODE_COVERAGE.HTML) and a sub-directory (CodeCoverage) in the current directory. Open the file in a web browser to view the reports.
Windows* only: Unlike the compiler options, which are preceded by forward slash ("/"), the tool options are preceded by a hyphen ("-").
The code coverage tool allows you to name the project and specify paths to specific, necessary files. The following example demonstrates how to name a project and specify .dpi and .spi files to use:
Example: specify .dpi and .spi files
codecov -prj myProject -spi pgopti.spi -dpi pgopti.dpi
The tool can add a contact name and generate an email link for that contact at the bottom of each HTML page. This provides a way to send an electronic message to the named contact. The following example demonstrates how to add specify a contact and the email links:
Example: add contact information
codecov -prj myProject -mname JoeSmith -maddr js@company.com
This following example demonstrates how to use the tool to specify the project name, specify the dynamic profile information file, and specify the output format and file name.
Example: export data to text
codecov -prj test1 -dpi test1.dpi -txtbcvrg test1_bcvrg.txt
Code Coverage Tool Options
Option
Default
Description
-bcolor
color
#FFFF99
Specifies the HTML color name for code in the uncovered blocks.
-beginblkdsbl
string
Specifies the comment that marks the beginning of the code fragment to be ignored by the coverage tool.
-blockcounts
When used wit