Configuration Reference
covdbg uses a YAML settings file named .covdbg.yaml to define include/exclude filters, the source lines to leave out, the shared libraries (DLLs) to measure, target-specific overrides, child-process following, telemetry, and logging settings.
Configuration File Resolution
covdbg resolves the configuration file using this precedence (first match wins):
| Priority | Source | Description |
|---|---|---|
| 1 | --config |
CLI option specifying path to config file |
| 2 | COVDBG_CONFIG |
Environment variable with path to config file |
| 3 | Auto-discovery | .covdbg.yaml in the working directory covdbg is started from |
| 4 | Auto-discovery | .covdbg.yaml in the same directory as the target executable |
Important: A configuration file is required. If no configuration file is found or cannot be loaded (file not found or invalid YAML), covdbg exits with an error. The error names the file and gives the parser's reason, with its line and column, such as a value of the wrong type. From covdbg 1.5.1, an auto-discovered .covdbg.yaml that cannot be loaded stops the run too: covdbg no longer passes over it to the next place, nor ends with "No configuration file found".
From covdbg 1.5.1, a key whose value has the wrong shape is refused rather than ignored: a single value where a list belongs (include: "src/**", baseline: app.exe, exclude_lines: '.*NOCOV'), a list where a map belongs (files: ["src/**"]), or a map or list inside a list of patterns. covdbg names the key and where its value is, such as Invalid coverage.default.files.include at line 5, column 16: expected a list, found a single value 'src/**', and exits with code 1. A single value is not taken as a one-item list: write include: ["src/**"], or each entry on a line of its own after - . A key with no value at all (include: with nothing after it) is still accepted and means no entries, as [] does.
From covdbg 1.5.1, covdbg warns about a key it does not know, for a run and for covdbg analyze, on stderr and in the log, and names the key with its path, line and column. For a key close to a known one it suggests that one: Warning: Unknown key coverage.default.exclude_line at line 7, column 5: covdbg ignores it; did you mean 'exclude_lines'?. The run goes on, so a configuration written for a newer covdbg still runs. A version other than 1, a type other than extend or override, and a targets: entry without target: are refused, as a value of the wrong shape is, with the key, its line and column, and exit code 1. Before, covdbg ignored an unknown key, read the first two as 1 and extend, and dropped the entry.
Quick Start Examples
Minimal Configuration
Track a single source file:
version: 1
coverage:
default:
files:
include:
- "src/main.cpp"
Typical Project Configuration
Track all source files, exclude build artifacts and system code:
version: 1
coverage:
default:
files:
include:
- "src/**/*.cpp"
- "src/**/*.h"
exclude:
- "build/**"
- "third_party/**"
functions:
exclude:
- "__empty_global_delete"
Complete Example
version: 1
source_root: "."
baseline:
- "build/app.exe"
settings:
log_level: "INFO"
log_file: "C:/logs/covdbg.log"
follow_children: false
telemetry: true
coverage:
default:
files:
include:
- "src/**/*.cpp"
- "src/**/*.h"
- "lib/**/*.cpp"
exclude:
- "build/**"
- "third_party/**"
- "**/*_test.cpp"
functions:
include:
- "*"
exclude:
- "operator*"
- "*::<lambda>*"
modules:
include:
- "mylib*.dll"
- "*_tests.exe" # The test executables too, measured only when selected
targets:
- target: "integration_tests.exe"
type: override
baseline:
- "build/integration_app.exe"
settings:
follow_children: true
files:
include:
- "integration/**"
Top-Level Keys
version
Config format version. Currently only version 1 is supported. From covdbg 1.5.1, any other value is refused: Invalid version at line 1, column 10: expected a whole number, found 'abc'. An empty version:, or none, means 1.
version: 1
source_root
Base directory used to resolve and normalize source paths. Useful when PDBs contain absolute paths from other machines (CI builds).
source_root: "."
Behavior:
- Relative paths are resolved relative to the config file's directory
- Absolute paths are used as-is
- Affects how source files appear in coverage exports
- Names the repository a run is licensed for: the git checkout around the source root, found by walking up from it (from covdbg 1.5.1), so a config in a subfolder of a checkout counts for that checkout. See which repository a run is licensed for
baseline
Optional list of binaries (executables or DLLs) that covdbg analyzes before the normal run. Each baseline binary produces an internal zero-hit .covdb database, then covdbg runs the requested target and merges the baseline databases with the runtime database into the --output file.
baseline:
- "build/app.exe"
- "build/tools/helper.exe"
Behavior:
- Relative paths are resolved relative to the config file's directory
- Paths must point to executables or DLLs that can be analyzed with the configured symbol backend
- A DLL listed here shows at 0% when the run never loads it; when the run does load and measure it, its hits are merged in
- Run mode requires
--outputwhenbaselinecontains entries because the final result is a merged.covdb baseline: []is valid and disables baseline analysis- Target overrides can also define
baseline;type: extendappends to the global list, whiletype: overridereplaces it for that target - Each baseline binary is filtered by the
targets:entry for its own file name, found as described in Target Matching, without regard to case
settings
General settings for logging and runtime behavior.
settings:
log_level: "INFO"
log_file: "C:/logs/covdbg.log"
follow_children: false
telemetry: true
| Setting | Values | Description |
|---|---|---|
log_level |
TRACE, DEBUG, INFO, WARN, ERROR, NONE |
Log file level (default: DEBUG; NONE writes no log file) |
log_file |
File path | Custom log file path (default: .covdbg\Logs\covdbg.log in the working directory) |
follow_children |
true, false |
Also instrument the processes the target spawns, and theirs in turn, and merge their coverage into the output (default: false). A target with no symbols of its own, such as ctest.exe, then runs unmeasured and only the processes it starts are measured |
telemetry |
true, false |
Report the run to the telemetry service afterwards (default: true); see the CLI reference for what is sent |
Note: Command-line options (--log-level, --log-file, --follow-children) and their environment variables override YAML settings; --follow-children and COVDBG_FOLLOW_CHILDREN can only turn following on. A target-specific settings block (see Per-Target Settings) overrides follow_children for one executable.
Coverage Filters
How Filtering Works
The filtering logic follows a specific precedence:
-
Include patterns: If include patterns are specified, ONLY files/functions matching at least one include pattern are considered. If no include patterns are specified, ALL files/functions are included by default.
-
Exclude patterns: Exclude patterns ALWAYS take precedence over include patterns. If a file/function matches any exclude pattern, it is excluded regardless of whether it matched an include pattern.
-
Evaluation order:
- Check if file/function matches any include pattern (or all if no includes)
- If included, check if it matches any exclude pattern
- If it matches an exclude pattern, it is excluded (exclude wins)
- Otherwise, it is included
coverage.default
The default coverage profile applied to all targets unless overridden.
coverage:
default:
files:
include:
- "src/**"
exclude:
- "build/**"
functions:
include:
- "*"
exclude:
- "operator*"
File Patterns
coverage:
default:
files:
include:
- "src/**/*.cpp" # All .cpp files under src/
- "lib/**" # Everything under lib/
exclude:
- "build/**" # Exclude build directory
- "**/test_*" # Exclude test files
Pattern syntax:
*- Match any characters within a path segment?- Match one character;[abc],[a-z]and[!a-z]match one character of a class**- Match any number of path segments (recursive)- Patterns are taken relative to the directory that holds the config file (the base directory) and matched against the source file's path as the PDB records it, ignoring case as Windows compares file names: letters outside ASCII too (
Äandä,Ωandω), without a language's rules (the Turkishİandıare letters of their own).\and/are the same. Changed in 1.5.1: only ASCII letters matched in any case.
How a pattern is anchored:
- For a path below the base directory, the pattern is matched against the path relative to it:
- A pattern with a
/at the start or in the middle is anchored to the base directory:src/**/*.cppand/src/**/*.cppmatch<base>/src/app/main.cpp, but not<base>/lib/src/x.cpp. - A pattern without a
/(*.cpp,main.cpp,third_party), or one that starts with**/(**/tests/**), matches at any depth. - Directory names above the base directory play no part: with the config file in
C:\agent\_work\build\proj,build/**matchesC:\agent\_work\build\proj\build\...only.
- A pattern with a
- A path outside the base directory is a source recorded where the binary was built (another checkout, another machine, a CI runner), a runtime or SDK source a PDB records, or a system DLL.
- In
files:, a pattern rooted at the base directory never matches it, whatever directory names its path has:**itself, and every pattern with a/that does not start with**/(src/**,src/*.cpp,/src/**). With the config file inC:\repo,src/**matchesC:\repo\src\a.cpp, neverD:\a\_work\1\s\src\vctools\..., and**selects every file belowC:\repoand nothing else. - A pattern that starts with
**/(**/vctools/**,**/include/mylib/**), or one without a/other than**(*.cpp,pow.c,*), is tried against the full path and against each part of it after a/: it matches at any depth outside the base directory too. That is how an exclude like**/vctools/**removes the runtime's sources, and how an include can select sources outside the base directory on purpose. - A source path the PDB records relative (
OSS\ARM-software\...,VCCRT\..., as the runtime records some of its own) is outside the base directory: it is not taken relative to the base directory or tosource_root, so a rooted pattern never matches it. The exception is a build that trims its source paths: withsource_root, covdbg reads such a path from there when the file is there, and it is then below the source root. - With
source_rootabove the config file's directory (a config inC:\repo\confwithsource_root: ".."), a path below the source root but outside the base directory is matched as before 1.5.1: every pattern but one with a leading/is tried against the full path and each part of it after a/. - In
modules:, every pattern but one with a leading/is tried against the full path and each part of it after a/, so a bare DLL name still selects a DLL in a system directory.
- In
- A pattern matches a path and everything below it:
buildmatches<base>/build/a.cppand<base>/src/build/gen.cpp. A trailing/is dropped (build/matches likebuild) and does not count as a/for anchoring;out/bin/is anchored. !patterntakes a path back out of the list; within one list the last pattern that matches decides. Exclude wins over include.- An absolute pattern (
C:/Windows/System32/*.dll) is matched against the full path.
Pattern examples:
"src/**/*.cpp"- All .cpp files undersrc/next to the config file, recursively"test/*.cpp"- .cpp files directly intest/next to the config file only"**/basic-1.cpp"- Any file named basic-1.cpp anywhere"cpp/basic-1.cpp"-cpp/basic-1.cppnext to the config file;"**/cpp/basic-1.cpp"matches it in any directory
Changed in 1.5.0: patterns change meaning only for paths below the config file's directory; paths outside it match as before. Before, only a leading / anchored a pattern, and every other pattern was matched against the full path and each part of it after a / for those paths too, so src/**/*.cpp also matched <base>/third_party/x/src/a.cpp. The names of the directories above the base directory counted too: with the config file under D:\build\..., build/**/*.dll in modules: selected every DLL in the checkout, and build/** in files: exclude: excluded every source file, so the same config gave different coverage on different machines. A pattern that relied on matching deeper below the base directory keeps its old meaning with **/ in front: src/foo/*.cpp becomes **/src/foo/*.cpp.
Changed in 1.5.1: in files:, a pattern rooted at the base directory (** itself, or one with a / that does not start with **/) no longer matches a path outside the base directory, nor a relative path. Before, include: ["**"] selected every source of the program's PDBs: the MSVC runtime and Windows SDK sources recorded on the toolchain's build drive (D:\a\_work\1\s\...) and those recorded by relative paths (OSS\ARM-software\..., VCCRT\...), which then looked like files of the repository in Cobertura and LCOV. And src/** matched the src in D:\a\_work\1\s\src\....
- OpenCppCoverage's
--sources <checkout root>isinclude: ["**"]in a.covdbg.yamlat that root, withsource_root: ".". It needs no excludes for the runtime and SDK sources. Its--excluded_line_regex <regex>is an entry ofexclude_lines(see Excluding Lines). - A pattern meant to select files outside the base directory takes
**/in front (third_party/zlib/**becomes**/third_party/zlib/**), or names them by their absolute path (D:/deps/zlib/**). - A config file in a subdirectory of the checkout has the checkout's other directories outside its base directory: its patterns for them take
**/in front too. - A build measured in another checkout (a CI test job on another runner) records its sources outside the base directory. With
source_rootset, covdbg reads them from below the source root, where rooted patterns match them. Where the build's checkout is still on the machine (several runners on one machine), its sources are measured there, outside the base directory, and only patterns that start with**/select them (**/src/**/*.cpp). modules:patterns are matched as before. Whatmodules:selects changed in 1.5.1, see Shared Library Patterns.- A file outside
source_rootthat a pattern does include is named by its absolute path in Cobertura (D:/a/_work/1/s/src/...), as in LCOV, not by a drive and a path that looks repository-relative. A source the PDB records by a relative path has no other path to give, and keeps that one.
Function Patterns
Filter which functions are tracked:
coverage:
default:
functions:
include:
- "*" # Include all functions
exclude:
- "operator*" # Exclude operators
- "*::<lambda>*" # Exclude lambdas
- "std::*" # Exclude std library
Function patterns are case-sensitive, unlike file and module patterns: std::* does not match Std::vector.
Shared Library Patterns
By default covdbg measures only the executable it launches. Code in shared libraries (a DLL your tests link against, a plugin loaded with LoadLibrary, a Python extension) runs, but is not measured, and its source files never enter the database. Select the modules to measure under modules: the libraries, and, from covdbg 1.5.1, the executable too:
coverage:
default:
files:
include:
- "src/**/*.cpp"
modules:
include:
- "mylib*.dll" # By file name, in any directory
- "build/**/plugins/*.dll" # By path, relative to the config file
- "mylib_tests.exe" # The executable, measured only when a pattern selects it
exclude:
- "mylib-thirdparty.dll"
Behavior:
- Libraries are opt-in. Unlike file and function patterns, a missing or empty
modules.includeselects no library at all. Without amodulessection, covdbg measures the executable and no library. - With
modules.include, the executable is a module like the libraries: it is measured only when a pattern selects it (include: ["mylib*.dll", "mylib_tests.exe"]), and so is the executable of each followed child process.modules.excludeleaves an executable out, with or without an include list. A target's ownmodules(see Target-Specific Overrides) applies to its executable as to its libraries. - An executable left out still runs under covdbg, unmeasured: the libraries it loads are instrumented as they load, and with
follow_childrenits children are followed. Its PDB is not read. - Patterns use the file pattern syntax and are matched against the module's full path (the DLL's, or the executable's), ignoring case as Windows compares file names, letters outside ASCII included (from covdbg 1.5.1; see File Patterns). A pattern without a
/matches the file name in any directory, system directories included; for a DLL below the config file's directory, one with a/at the start or in the middle is anchored to that directory (see File Patterns). Exclude wins over include. - File and function patterns still decide which code is measured: a selected library contributes only functions whose source files pass
files, so its sources must be included too. - A selected library is instrumented as soon as Windows maps it, before any of its code (including
DllMain) runs. This holds for DLLs the executable imports and for DLLs loaded later withLoadLibrary. A library unloaded before the process exits keeps the coverage it collected. - Each library appears in the database as its own module, beside the executable when that is measured.
- A selected library without a PDB, or whose sources are all excluded, is left unmeasured.
"*.dll"is therefore safe, but slower, and covdbg reports each system DLL whose PDB it cannot find. - With
follow_children, the same selection applies to every followed process: to its executable and to its libraries. - When libraries are selected, the executable itself may be left out, or have nothing to measure, for example a test host or
python.exe. covdbg then runs it unmeasured and measures only the libraries. If no selected library with functions to track was loaded either, nothing was measured: the program still runs, covdbg writes an empty database and exits2, and says why, for examplemylib_tests.exe is not selected under modules: in .covdbg.yaml(see Nothing Measured). follow_childrenworks the same way for a launcher: an executable with nothing to measure, such asctest.exeorcmd.exe, runs unmeasured and the processes it starts are measured. If none of them had functions to track either, nothing was measured, as above.- A library the run never loads is not in the database at all. List it under
baselineto have it reported at 0%.
Changed in 1.5.1: the executable, and the executable of each followed child process, was always measured beside the selected libraries, and naming it under modules.exclude changed nothing. Where it compiled in sources a selected library has too (a shared core/ library, a header-only dependency), their lines and hits were merged with the library's. A modules.include that lists only libraries ("mylib.dll", "*.dll") now measures those libraries alone. To keep measuring the executable, add its name: include: ["*.dll", "mylib_tests.exe"].
Coming from OpenCppCoverage:
--modules mylib.dllismodules: include: ["mylib.dll"], which measures the library alone, not the program that loads it.- OpenCppCoverage matches
--modulesanywhere in the module's path; covdbg's patterns are globs (see File Patterns), so--modules mylibis"*mylib*". --cover_childrenis--follow-children, orfollow_childrenin.covdbg.yaml.
Excluding Lines
From covdbg 1.5.1. Single source lines can be left out of coverage: by regular expressions under exclude_lines, as OpenCppCoverage's --excluded_line_regex does, and by the marker comments that lcov and gcovr read, which work without any configuration.
version: 1
source_root: "."
coverage:
default:
files:
include: ["**"]
exclude_lines: # OpenCppCoverage: --excluded_line_regex, once for each
- '\s*else.*'
- '\s*\}.*'
- '\s*\{\s*'
exclusion_markers: true # the default; false turns the marker comments off
| Key | Values | Description |
|---|---|---|
exclude_lines |
List of regular expressions | A line that one of them matches as a whole is excluded (default: none) |
exclusion_markers |
true, false |
Read the marker comments in the sources (default: true) |
marker_patterns |
Marker names and regular expressions | Other words for the markers, as lcovrc's lcov_excl_line and its other settings give them (default: lcov's and gcovr's own) |
An excluded line is not an executable line. It is not in the .covdb database at all, so it is in no report and no total made from it: Cobertura, LCOV, GCOV, HTML, and the summary covdbg prints after the run. A function whose lines are all excluded is left out of the functions, as gcovr leaves it out, and a basic block whose lines are all excluded is not measured. A function that keeps a line keeps its name and its other lines.
exclude_lines
-
Each entry is an ECMAScript regular expression (C++'s
std::regex, which OpenCppCoverage uses too) that must match the whole line, as OpenCppCoverage'sstd::regex_matchdoes.\s*else.*needs no^or$;elsealone matches only a line that iselseand nothing else;.*// NOCOVmatches a line that ends with that comment. -
The line is its bytes as the file has them (UTF-8 for most sources), without its
\r\nor\n. A line is excluded when any pattern matches it. -
Write the patterns in single quotes. YAML keeps a backslash in single quotes as it is (
'\s*\{\s*'), where double quotes take\sfor an escape and the file is refused. -
A pattern that is not a regular expression is refused when the configuration is read, and covdbg does nothing (exit code
1):covdbg: Invalid regular expression '\s*(else' in coverage.default.exclude_lines: regex_error(error_paren): The expression contained mismatched ( and ).
Marker Comments
covdbg reads the marker comments as lcov 2's geninfo reads them. A marker is a whole word anywhere in its line, in a comment as a rule. The markers that gcovr knows as well are also read with gcovr's default prefixes, GCOVR_, GCOV_ and LCOVR_ (gcovr's --exclude-pattern-prefix '[GL]COVR?').
| Marker | Effect in covdbg |
|---|---|
LCOV_EXCL_LINE |
Excludes its line |
LCOV_EXCL_START ... LCOV_EXCL_STOP |
Excludes the lines from the start marker's line to the line before the stop marker's: the stop marker's line is not excluded |
LCOV_UNREACHABLE_LINE |
Excludes its line, which should never run. If it runs, the run reports it |
LCOV_UNREACHABLE_START ... LCOV_UNREACHABLE_STOP |
Excludes a region of such lines, as LCOV_EXCL_START does |
GCOVR_EXCL_FUNCTION |
On the line a function starts on, excludes that function: all its lines, and with them the function itself |
LCOV_EXCL_BR_LINE, LCOV_EXCL_BR_START ... LCOV_EXCL_BR_STOP |
Branch markers: no effect, see below |
LCOV_EXCL_EXCEPTION_BR_LINE, LCOV_EXCL_EXCEPTION_BR_START ... LCOV_EXCL_EXCEPTION_BR_STOP |
Branch markers: no effect |
GCOVR_EXCL_BR_SOURCE, GCOVR_EXCL_BR_WITHOUT_HIT: n/m |
gcovr's branch markers: no effect |
LCOV_EXCL_*, LCOV_EXCL_BR_* and the function marker are also read as GCOVR_EXCL_*, GCOV_EXCL_* and LCOVR_EXCL_*. The spellings are one marker, so a GCOVR_EXCL_STOP ends a region an LCOV_EXCL_START began. The unreachable and exception markers are lcov's alone.
int Parse(char const* text)
{
if (text == nullptr)
{
return Fail("no text"); // LCOV_EXCL_LINE
}
// LCOV_EXCL_START
if (Trace())
{
Dump(text);
}
// LCOV_EXCL_STOP
switch (Kind(text))
{
case 'a': return 1;
case 'b': return 2;
default: std::abort(); // LCOV_UNREACHABLE_LINE
}
}
void DebugOnly() // GCOVR_EXCL_FUNCTION
{
Dump("state");
}
How a source's markers are read, as in lcov:
LCOV_EXCL_STARTandLCOV_UNREACHABLE_STARTshare one region. A start marker within a region starts it again, from its own line. A stop marker without a start, or of the other kind (anLCOV_UNREACHABLE_STOPin anLCOV_EXCL_STARTregion), ends the region. covdbg reports both.- A line changes the region once: when it has a start and a stop marker, its start marker counts.
- Of a single line, its own
_EXCL_LINEmarker decides first, then itsLCOV_UNREACHABLE_LINE, then theexclude_linespatterns, and then the region it is in. A line withLCOV_EXCL_LINEin an unreachable region is an excluded line, not an unreachable one. - A region that is not closed runs to the end of the file, and covdbg reports it. gcovr excludes nothing for such a region.
- A start marker within a region does not nest, as it does in gcovr: the first stop marker ends the region.
What covdbg reports: lcov stops with a mismatch or unreachable error unless it runs with --ignore-errors. covdbg prints the same findings and goes on; they do not change its exit code. A file is read once per binary, so a source that several test executables share is reported for each of them.
covdbg: D:\src\parse.cpp: LCOV_EXCL_START on line 40 has no stop marker; the lines to the end of the file are excluded
covdbg: D:\src\parse.cpp: LCOV_EXCL_STOP on line 52 ends no region
covdbg: D:\src\parse.cpp: LCOV_EXCL_START on line 60 is in the region LCOV_EXCL_START started on line 55, which it starts again
covdbg: D:\src\parse.cpp: LCOV_UNREACHABLE_STOP on line 70 ends the region LCOV_EXCL_START started on line 66, which is of the other kind
covdbg: D:\src\parse.cpp:23: a line marked unreachable ran
covdbg: D:\src\parse.cpp:27: GCOVR_EXCL_FUNCTION is on no line a function starts on; it excludes nothing
Unreachable lines: covdbg excludes them, and still watches the code they are on. When one runs, the run names it, as lcov reports a hit in an unreachable region. lcov then keeps the line in its report by default (retain_unreachable_coverpoints_if_executed = 1); covdbg keeps it excluded. A wrong marker therefore shows on the console, not as a changed percentage. covdbg analyze runs nothing, so it reports none.
The function marker excludes the function whose first line is the marker's line. MSVC gives a function the line of its opening brace as its first, so the marker may also be on the line before that brace, when the brace stands on a line of its own (blank lines between them are fine). A function defined inside the excluded one, such as a lambda, keeps the lines that are its own. Template instantiations of one function are all excluded. A marker on a line no function starts on excludes nothing and is reported.
Branch markers exclude branches and never lines, in lcov as in gcovr. covdbg measures lines and basic blocks, not branches (its Cobertura reports a branch-rate of 0 and its LCOV export has no BRDA records), so it reads branch markers as having nothing to exclude. They neither exclude a line nor end a region, and are not reported, as lcov ignores them when branch coverage is off.
Turning the markers off: exclusion_markers: false turns all of them off, as lcov's --no-markers does; exclude_lines still applies.
marker_patterns
lcov lets an lcovrc file change the words it reads as markers, and gcovr its prefix. marker_patterns does the same, by lcovrc's setting names without their lcov_. Each value is a regular expression that covdbg looks for as a whole word, and it replaces that marker's default; an empty value ('') turns that marker off. The markers a profile does not name keep their defaults.
| Key | lcovrc setting | Default |
|---|---|---|
excl_line |
lcov_excl_line |
[GL]COVR?_EXCL_LINE |
excl_start |
lcov_excl_start |
[GL]COVR?_EXCL_START |
excl_stop |
lcov_excl_stop |
[GL]COVR?_EXCL_STOP |
unreachable_line |
lcov_unreachable_line |
LCOV_UNREACHABLE_LINE |
unreachable_start |
lcov_unreachable_start |
LCOV_UNREACHABLE_START |
unreachable_stop |
lcov_unreachable_stop |
LCOV_UNREACHABLE_STOP |
excl_function |
none (gcovr's marker) | [GL]COVR?_EXCL_FUNCTION |
excl_br_line |
lcov_excl_br_line |
[GL]COVR?_EXCL_BR_LINE |
excl_br_start |
lcov_excl_br_start |
[GL]COVR?_EXCL_BR_START |
excl_br_stop |
lcov_excl_br_stop |
[GL]COVR?_EXCL_BR_STOP |
excl_exception_br_line |
lcov_excl_exception_br_line |
LCOV_EXCL_EXCEPTION_BR_LINE |
excl_exception_br_start |
lcov_excl_exception_br_start |
LCOV_EXCL_EXCEPTION_BR_START |
excl_exception_br_stop |
lcov_excl_exception_br_stop |
LCOV_EXCL_EXCEPTION_BR_STOP |
The branch marker keys are accepted, and checked, so that an lcovrc translates in full, but change nothing while covdbg records no branches.
coverage:
default:
marker_patterns:
excl_line: 'LCOV_EXCL_LINE|NO_COVERAGE' # lcovrc: lcov_excl_line = LCOV_EXCL_LINE|NO_COVERAGE
excl_start: 'BEGIN_NO_COVERAGE'
excl_stop: 'END_NO_COVERAGE'
unreachable_line: '' # turns LCOV_UNREACHABLE_LINE off
A key that is no marker's name, or a value that is not a regular expression, is refused when the configuration is read (exit code 1):
covdbg: Invalid pattern 'NOCOV' of lcov_excl_line in coverage.default.marker_patterns: there is no marker 'lcov_excl_line'; the markers are excl_line, excl_start, ...
Where the Source Is Read
covdbg reads each source when it records the program's lines: in a run, in covdbg analyze, and for a baseline binary. It reads the file where the configuration finds it, under source_root when the build's checkout is not on this machine. A source covdbg cannot read keeps all its lines.
The database holds only the lines that are left, so covdbg convert and covdbg merge need no configuration. Databases written with different exclusions are merged as they are: a line that any of them has is a line of the result.
A target's entry under targets extends or overrides exclude_lines like files (see Target-Specific Overrides), and its exclusion_markers and each of its marker_patterns win in either mode.
Coming from OpenCppCoverage, lcov or gcovr
-
OpenCppCoverage: each
--excluded_line_regex <regex>is an entry ofexclude_lines, unchanged. Both tools match a pattern against the whole line with the same regular expression engine. OpenCppCoverage reads no marker comments; to exclude exactly what it excluded, setexclusion_markers: false. Boost'sci/opencppcoverage.ps1(boost-ci) passes these, the first of which covdbg's markers cover anyway:exclude_lines: - '.*// LCOV_EXCL_LINE' - '.*// coverity\[dead_error_line\]' - '\s*[}{]*\s*' - '\s*(\} )?else( \{)?\s*' -
lcov: the markers mean what they mean to lcov 2. An lcovrc's
lcov_excl_lineand the other marker settings go undermarker_patterns, and--no-markersisexclusion_markers: false. lcov's--omit-lines(lcovrcomit_lines) is different fromexclude_lines: its Perl regular expression may match any part of the line, so--omit-lines 'NOCOV'excludes every line withNOCOVin it. As anexclude_linesentry it needs.*around it:'.*NOCOV.*'. For lcov's--erase-functions, usefunctions: exclude:, whose patterns are wildcards, not regular expressions. -
gcovr:
GCOVR_EXCL_*,GCOV_EXCL_*andLCOV_EXCL_*markers work as they are. A project that sets--exclude-pattern-prefix MYPROJlists its markers undermarker_patterns(excl_line: 'MYPROJ_EXCL_LINE', and so on). gcovr's--exclude-lines-by-patternmatches from the start of the line but not to its end, so anexclude_linesentry needs.*at the end. Where gcovr and lcov differ, covdbg follows lcov: a marker must be a whole word, a start within a region does not nest, and a region that is not closed runs to the end of the file. For gcovr's--exclude-function, usefunctions: exclude:.
Target-Specific Overrides
Override or extend filters, shared library selections, and baseline binaries for specific executables. Two modes are available:
Extend Mode (default)
Adds patterns to the default profile. Include patterns are merged (OR logic), exclude patterns are merged (any match excludes), modules patterns are merged the same way, exclude_lines patterns are appended to the default ones, and target baseline entries are appended to the global baseline list. A target's exclusion_markers replaces the default's, and so does each marker it names under marker_patterns.
baseline:
- "src/app.exe"
coverage:
default:
files:
include:
- "src/main.cpp"
functions:
exclude:
- "__empty_global_delete"
targets:
- target: "multi-file.exe"
type: extend
baseline:
- "src/math_utils.exe"
files:
include:
- "src/math_utils.cpp" # Added to default includes
Result: Both main.cpp AND math_utils.cpp are tracked, and both src/app.exe and src/math_utils.exe are analyzed for baseline coverage when running multi-file.exe.
Override Mode
Completely replaces the default profile patterns for that target. files, functions, modules, and exclude_lines are each replaced only when the target defines them. If the target defines baseline, it also replaces the global baseline list for that target. exclusion_markers and marker_patterns work as in extend mode: what the target sets wins, and the rest comes from the default profile.
baseline:
- "src/app.exe"
coverage:
default:
files:
include:
- "src/main.cpp"
- "src/string_utils.cpp"
functions:
exclude:
- "__empty_global_delete"
targets:
- target: "multi-file.exe"
type: override
baseline:
- "src/math_utils.exe"
files:
include:
- "src/math_utils.cpp" # Replaces default includes
Result: ONLY math_utils.cpp is tracked (default patterns ignored), and only src/math_utils.exe is analyzed for baseline coverage.
Per-Target Settings
A target can carry its own settings block. Only follow_children is read there; it replaces the global value for that executable in both extend and override mode:
settings:
follow_children: false
coverage:
default:
files:
include:
- "src/**"
targets:
- target: "integration_tests.exe"
settings:
follow_children: true # This runner launches the program under test
Result: Only integration_tests.exe follows the processes it spawns; every other target is measured on its own. Following costs analysis and instrumentation for each child, so keep it to the targets that need it.
Target Matching
targetis matched against the executable filename (e.g.,my_tests.exe). For a program run by its name alone, that is the file covdbg found onPATH, socovdbg ctestmatchestarget: "ctest.exe"(from covdbg 1.5.1; see Finding the Program)- The name is compared as Windows compares file names: without regard to case, letters outside ASCII included, and with any 8.3 short name written out first.
My_Tests.EXEgets the entrytarget: "my_tests.exe". The program is still shown and recorded by its name as it is spelled on disk - The binaries under
baselineand the--inputofcovdbg analyzefind their entry the same way - If no target matches, the default profile is used
- Each entry needs a
target:with the program's file name, and itstype, if given, isextend(the default) oroverride. From covdbg 1.5.1, an entry withouttarget:and any othertypeare refused, naming the line:Invalid type of target 'my_tests.exe' at line 9, column 13: expected extend or override, found 'overide'
Changed in 1.5.1: the name had to match in case too, so a program started as My_Tests.exe did not get the settings of target: "my_tests.exe".
Entries that differ only in case
Two entries whose names differ only in case, or are the same, name the same program. The first one in the file counts, all of it: the other's files, modules, baseline and settings do not fill in what the first leaves out. covdbg warns about each such entry when it loads the configuration, for a run and for covdbg analyze, on stderr and in the log, naming both entries and the one it uses:
Warning: targets: entries 'My_Tests.exe' and 'my_tests.exe' differ only in case and name the same program; covdbg uses the first, 'My_Tests.exe'
Warning: targets: names 'other_tests.exe' twice; covdbg uses the first entry
Keep one entry per program. Changed in 1.5.1: an entry applied only to a program whose name matched it in case, and covdbg said nothing about an entry that repeated another; follow_children came from the first matching entry that set it.
Common Patterns
Focus on Your Code
Exclude third-party libraries and build artifacts. Patterns such as build/** and third_party/** mean those directories next to the config file; use **/build/** to match them at any depth:
version: 1
source_root: "."
coverage:
default:
files:
include:
- "src/**"
exclude:
- "build/**"
- "third_party/**"
- "external/**"
- "vendor/**"
Exclude Test Code from Coverage
Track only production code:
coverage:
default:
files:
include:
- "src/**"
exclude:
- "**/*_test.cpp"
- "**/test_*.cpp"
- "tests/**"
Exclude Generated Code
coverage:
default:
files:
exclude:
- "**/*.generated.cpp"
- "**/moc_*.cpp"
- "**/ui_*.h"
Measure a DLL Your Tests Load
Test executables that link against your library, or load it as a plugin:
coverage:
default:
files:
include:
- "src/**"
modules:
include:
- "mylib.dll"
targets:
- target: "plugin_tests.exe"
type: extend
modules:
include:
- "myplugin.dll" # Only this test suite loads the plugin
This measures the libraries alone, not the test executables that load them. To measure those too, add their names under include, such as "*_tests.exe".
Different Filters for Different Test Suites
coverage:
default:
files:
include:
- "src/**"
targets:
- target: "unit_tests.exe"
type: override
files:
include:
- "src/core/**"
- target: "gui_tests.exe"
type: override
files:
include:
- "src/ui/**"
Using the Config from CLI
Explicit path:
covdbg --config "C:\project\.covdbg.yaml" --output "results.covdb" "tests.exe"
Environment variable:
$env:COVDBG_CONFIG = "C:\project\.covdbg.yaml"
covdbg --output "results.covdb" "tests.exe"
Automatic discovery (place .covdbg.yaml in the directory you run covdbg from, usually the repository root; a copy next to the executable is found when the working directory has none):
C:\project\
├── .covdbg.yaml
└── build\
├── tests.exe
└── tests.pdb
cd C:\project
covdbg --output "results.covdb" "build\tests.exe"
See Also
- CLI Reference: command-line options
- Quick Start: getting started
- Troubleshooting: filter issues