Skip to content

Command line reference

OpenCppCoverage edited this page Jun 17, 2019 · 10 revisions

You can display a quick reference with -h or --help as command line argument:

Usage: [options] -- program_to_run optional_arguments:

Command line only:
  -v [ --verbose ]                  Verbose mode.
  -q [ --quiet ]                    Quiet mode.
  -h [ --help ]                     Show help message.
  --config_file arg                 Filename of a configuration file.

Command line and configuration file:
  --modules arg (=*)                The pattern that module's paths should
                                    match. Can have multiple occurrences.
  --excluded_modules arg            The pattern that module's paths should NOT
                                    match. Can have multiple occurrences.
  --sources arg (=*)                The pattern that source's paths should
                                    match. Can have multiple occurrences.
  --excluded_sources arg            The pattern that source's paths should NOT
                                    match. Can have multiple occurrences.
  --input_coverage arg              A output path of export_type=binary. This
                                    coverage data will be merged with the
                                    current one. Can have multiple occurrences.
  --export_type arg (=html)         Format: <exportType>:<outputPath>.
                                    <exportType> can be: html, cobertura or
                                    binary
                                    <outputPath> (optional) export output path.
                                    Must be a folder for html and a file for
                                    cobertura or binary.
                                    Example: html:MyFolder\MySubFolder
                                    This flag can have multiple occurrences.
  --working_dir arg                 The program working directory.
  --cover_children                  Enable code coverage for children
                                    processes.
  --no_aggregate_by_file            Do not aggregate coverage for same file
                                    path.
  --unified_diff arg                Format: <unifiedDiffPath>?<rootFolder>
                                    <unifiedDiffPath> path of the unified diff
                                    file. Git users can use git diff output.
                                    <rootFolder> (optional) root folder for
                                    paths in the diff file.
                                    See documentation for limitations.
  --continue_after_cpp_exception    Try to continue after throwing a C++
                                    exception.
  --optimized_build                 Enable heuristics to support optimized
                                    build. See documentation for restrictions.
  --excluded_line_regex arg         Exclude all lines match the regular
                                    expression. Regular expression must match
                                    the whole line.
  --substitute_pdb_source_path arg  Substitute the starting path defined in the
                                    pdb by a local path.
                                    Format: <pdbStartPath>?<localPath>. Can
                                    have multiple occurrences.

Command line only

These flags can be set only as command line argument.

-v [ --verbose ]

Display additional information in the console and in the log file LastCoverageResults.log:

  • Why a source file is selected or skipped
  • The location of program database file used

As this mode is verbose, it is recommended to use the log file instead of the console.

-q [ --quiet ]

Do not show OpenCppCoverage messages except errors.

-h [ --help ]

Display the command line help.

--config_file arg

If you always use the same flags, it can be convenient to have a configuration file.

You can set a configuration file with --config_file=YourConfigFile.

The configuration format is ArgumentName(without --)=Value. This is the format of the config file of Boost.Program_options. A line starting with # is ignored.

Here is an example named config.txt.

sources=MySources
export_type=html

You can use this configuration with the following command:

OpenCppCoverage.exe --config_file=config.txt -- MyProgram.exe

The previous line is strictly equivalent to:

OpenCppCoverage.exe --sources=MySources --export_type=html -- MyProgram.exe

Only flags in section Command line and Configuration file can be used in a configuration file.

If you set the same flag as command line argument and in a configuration file:

  • If the flag can have multiple occurrences (like --sources), both arguments will be used.
  • If the flag has single occurrence (like --working_dir), only command line argument will be used.

Command line and configuration file

These flags can be set as command line argument and in a configuration file. See --config_file for more information.

--modules arg

By default OpenCppCoverage try to perform code coverage for all modules (executable and shared libraries).

The flag --modules selects only modules whose path contain arg. The value for --modules is often the name of your project root folder.

OpenCppCoverage.exe --modules C:\Dev\MyProject -- MyProgram.exe

In the previous line, only module path containing C:\Dev\MyProject will be selected.

Note: OpenCppCoverage discovers modules based on what was loaded by the program under the code coverage. --modules only filters what was discovered. If you specify a dll not loaded by your program, it will not be in the coverage report regardless of using this option.

Most of the time, you do not need the full path and the next line works too:

OpenCppCoverage.exe --modules MyProject -- MyProgram.exe

You can also use the wildcards ‘*’ that match any characters any times.

OpenCppCoverage.exe --modules MyP*je*t -- MyProgram.exe

As a static library binary code is included inside an executable or a shared library, you cannot use this flag to select static library.

By default --modules is set at * that match all paths.

--excluded_modules arg

It is sometimes useful to exclude specific modules. --excluded_modules is the opposite of --modules.

OpenCppCoverage.exe --excluded_modules C:\Dev\MyProgram -- MyProgram.exe

All modules whose path contains C:\Dev\MyProject will be skipped. You can also use the wildcards ‘*’.

A module is selected if its path:

  • contains at least one --modules pattern
  • does not contain a --excluded_modules pattern.

--sources arg

This is the same as --modules but for source files.

--excluded_sources arg

This is the same as --excluded_modules but for source files.

--input_coverage arg

Load a code coverage report created with --export_type:binary and merge it with the current coverage. The argument is the path of the file to load.

OpenCppCoverage.exe --sources=MySources --input_coverage=MyProgram.cov -- MyOtherProgram.exe

This will create a single report for both MyProgram and MyOtherProgram.

--export_type arg

Set the kinds of export type. The format is the export type followed by an optional ‘:’ and the output path.

OpenCppCoverage.exe --export_type=export_type_value:outputPath -- MyProgram.exe

Supported values for export_type_value are:

  • html: The coverage is reported as Html files. This is the default value if this flag is not set.
  • cobertura: It creates a xml file compatible with Cobertura plugin for Jenkins. See here for more information.
  • binary: The coverage report is saved in a binary file. This file can be reloaded with --input_coverage.

The outputPath is the path where the export will be performed. If it is not specified, a default value will be used:

  • for html: CoverageReport-YYYY-MM-DD-HHhMMmSSs, YYYY-MM-DD-HHhMMmSSs will be replaced by the current date. outputPath must be a folder.
  • for cobertura: ProgramNameCoverage.xml where ProgramName is the name of the executed program or CoverageOutput. outputPath must be a file.
  • for binary: ProgramName.cov where ProgramName is the name of the executed program or CoverageOutput. outputPath must be a file.

You can export in several formats at the same time by specifying several --export_type flags.

OpenCppCoverage.exe --sources=MySources --export_type=html:OutputFolder --export_type=cobertura -- MyProgram.exe

The previous line will create a Html coverage report in the folder OutputFolder and a cobertura file MyProgramCoverage.xml.

--working_dir

Set the working directory for program_to_run.

--cover_children

Create code coverage for program_to_run and also for its children processes. OpenCppCoverage cannot compute code coverage for a child of a debugger (A program that uses WaitForDebugEvent).

--no_aggregate_by_file

OpenCppCoverage aggregates code coverage by filename.

Consider the following code:

// MyHeader.h
#pragma once
inline void Foo(){} // Call from MyLib1.dll
inline void Bar(){} // Call from MyLib2.dll

The code coverage of the file MyHeader.h is 50% for MyLib1.dll and 50% for MyLib2.dll.

By default, OpenCppCoverage reports the coverage of MyHeader.h as 100% because it aggregates the coverage of all modules (MyLib1.dll and MyLib2.dll).

If you prefer to have no aggregation, you can use --no_aggregate_by_file that reports coverage of 50% for each module in the previous case.

Note: --no_aggregate_by_file is the behavior of OpenCppCoverage 0.9.2.1 and older version.

--unified_diff < unifiedDiffPath >?< rootFolder >

unifiedDiffPath

OpenCppCoverage can extract the updated or added lines from a unified diff file and compute the code coverage only for these lines. You can use several flags --unified_diff. In this case, OpenCppCoverage behaves as if all files are concatenated. You can still use --sources and --excluded_sources as additional filters. Here is an example of diff files containing update files (lines are omitted):

  • diff1.patch: foo1, foo2
  • diff2.patch: foo3, bar

OpenCppCoverage --unified_diff diff1.patch --unified_diff diff2.patch --sources foo -- MyProgram.exe

The previous command computes code coverage only for files foo1, foo2 and foo3.

Note: You do not need to use --no-prefix when using git diff command.

** Limitations (Important to understand) **

Consider the following code:

void foo(int) {}

foo(      // Line 10
    42);  // Line 11
          // Line 12
return 0; // Line 13

You cannot put a breakpoint at line 11 in this code in Visual Studio because there is no instruction for the line 11.

In the same way, if you have an updated or created line N in your diff file, OpenCppCoverage considers the line N only if it can be executed otherwise the previous line that can be executed is used.

So, if line 11 is marked as updated in the diff file, line 10 will be considered by OpenCppCoverage because there is no instruction for line 11. This remark is also true for comments or lines with white spaces.

Root folder

Unified diff file contains partial paths. Consider the case of a unified diff file containing the path MyFile.cpp. If your program was compiled with the files C:\MySubDir\MyFile.cpp and C:\MySubDir2\MyFile.cpp, OpenCppCoverage would not be able to find the good one. In this case, you must provide --unified_diff unifiedDiffPath?rootFolder where rootFolder is either C:\MySubDir or C:\MySubDir2.

This is not a common problem and should not happen with git diff. Nevertheless, OpenCppCoverage detects if a unified path can match two different full paths and ask you to set the root folder.

--continue_after_cpp_exception

In the same way as Visual Studio does, OpenCppCoverage can try to continue after an C++ exception. An C++ exception is an exception thrown with the keyword throw. throw 42 and throw std::runtime_error("My error") are C++ exceptions whereas an access violation or RaiseException(EXCEPTION_FLT_DIVIDE_BY_ZERO, ...) are not.

--optimized_build

This option enables heuristics to support optimized build (/O1 /O2 in Visual Studio). It is not required for x86_64 target application.

You can see surprising coverage results when the target is compiled with optimization because there can be a big difference between the source code and the generated code.

Behind the scenes, this flag skips the coverage when it detects a switch jump table optimization. In rare cases, this heuristic can exclude a valid line when you rethrow an exception in a catch block .

--excluded_line_regex

This option excludes all lines from source files that match the whole regular expression. For example --excluded_line_regex “.*else.*” excludes all lines containing else.

The syntax used is the modified ECMAScript regular expression grammar and is described here. Both \n and \r\n are supported as an end of line.

If you want to use Unicode characters, make sure the characters you pass to OpenCppCoverage are encoded in the same way as in your source files.

--substitute_path < pdbStartPath >?< localPath >

When you build a project on one computer but run the code coverage on another one, the source files location may be different. As OpenCppCoverage reads the paths from the PDB files, it needs some additional information.

--substitute_path <pdbStartPath>?<localPath> replaces all paths starting with <pdbStartPath> by <localPath>.

<pdbStartPath>: Must uses windows separator path \

Imagine the following case:

  • Your project was built on a computer A and the source files were located in C:\Dev\MyProject
  • You want to compute the code coverage from a computer B and the source files are located in D:\Dev\MyProject

In this case adding --substitute_path=C:\Dev\MyProject?D:\Dev\MyProject or --substitute_path=C:\Dev?D:\Dev let OpenCppCoverage find the source files.

The easiest way to know the original source files location is to run OpenCppCoverage with --export_type=HTML and look for a missing file. For example, in the image below, the original source file location is C:\Dev\MyProject\MyProject\MyProject.cpp

You can’t perform that action at this time.