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.
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 namedconfig.txt.
sources=MySources
export_type=html
You can use this configuration with the following command:
OpenCppCoverage.exe --config_file=config.txt -- MyProgram.exeThe 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 andMyOtherProgram.
--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-HHhMMmSSswill be replaced by the current date.
- for cobertura: ProgramNameCoverage.xml where ProgramName is the name of the executed program orCoverageOutput.
- for binary: ProgramName.cov where ProgramName is the name of the executed program orCoverageOutput.
You can export in several formats at the same time by specifying several --export_typeflags.
OpenCppCoverage.exe --sources=MySources --export_type=html:OutputFolder --export_type=cobertura -- MyProgram.exeThe previous line will create a Html coverage report in the folder OutputFolder and a cobertura fileMyProgramCoverage.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% forMyLib2.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.
--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 keywordthrow.
throw 42 and throw std::runtime_error("My error") are C++ exceptions whereas an access violation orRaiseException(EXCEPTION_FLT_DIVIDE_BY_ZERO, ...) are not.