Command-line reference

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: binary, cobertura, html
                                   <outputPath> (optional) output file or
                                   directory for the export.
                                   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.

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. 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.

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

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

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.
  • for cobertura: ProgramNameCoverage.xml where ProgramName is the name of the executed program or CoverageOutput.
  • for binary: ProgramName.cov where ProgramName is the name of the executed program or CoverageOutput.

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.

Last edited Mar 5 at 3:53 PM by OpenCppCoverage, version 26