Configuration Reference

covdbg uses a YAML settings file named .covdbg.yaml to define include/exclude filters, 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):

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.

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

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

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 --output when baseline contains entries because the final result is a merged .covdb
• baseline: [] is valid and disables baseline analysis
• Target overrides can also define baseline; type: extend appends to the global list, while type: override replaces it for that target

settings

General settings for logging and runtime behavior.

settings:
  log_level: "INFO"
  log_file: "C:/logs/covdbg.log"
  follow_children: false
  telemetry: true

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:

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

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

3. 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 any number of path segments (recursive)
• Patterns are matched against the normalized source file paths

Pattern examples:

• "src/**/*.cpp" - All .cpp files under src/ recursively
• "test/*.cpp" - .cpp files directly in test/ folder only
• "**/basic-1.cpp" - Any file named basic-1.cpp anywhere
• "cpp/basic-1.cpp" - Specific file path

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

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 libraries to measure under modules:

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
      exclude:
        - "mylib-thirdparty.dll"

Behavior:

• Libraries are opt-in. Unlike file and function patterns, a missing or empty modules.include selects no library at all, so existing configurations behave as before.
• Patterns use the file pattern syntax and are matched against the DLL's full path, ignoring case. A pattern without a / matches the file name in any directory; one with a / is relative to the config file's directory. 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 with LoadLibrary. 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.
• 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 the libraries of every followed process.
• When libraries are selected, the executable itself may have nothing to measure, for example a test host or python.exe. covdbg then runs it unmeasured and measures only the libraries, where it would otherwise stop with "no functions to track". If no selected library with functions to track was loaded either, the run fails with "Nothing was measured".
• A library the run never loads is not in the database at all. List it under baseline to have it reported at 0%.

---

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, and target baseline entries are appended to the global baseline list.

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, and modules are each replaced only when the target defines them. If the target defines baseline, it also replaces the global baseline list for that target.

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

• target is matched against the executable filename (e.g., my_tests.exe)
• Matching is case-sensitive
• If no target matches, the default profile is used

---

Common Patterns

Focus on Your Code

Exclude third-party libraries and build artifacts:

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

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