# covdbg

> covdbg is a Windows-based code coverage tool for native C/C++ applications using dynamic binary instrumentation. No recompilation required-just run your existing debug builds.

## Product Overview

covdbg collects line-level code coverage from Windows executables (x64) at runtime. It uses debug symbols (PDB files) to map machine instructions back to source code. Unlike compiler-based coverage tools, covdbg requires no build changes-works with any debug build that has PDBs.

**Key capabilities:**
- Dynamic binary instrumentation (no recompilation)
- Line-level coverage from PDB symbols
- LCOV and GCOV export formats
- CI/CD integration (GitHub Actions, Codecov)
- YAML-based filtering configuration
- Coverage database merging
- Free for open source projects

**Platform:** Windows 10/11 or Windows Server (x64 only)

## Quick Start

### 1. Install covdbg

Download installer: https://covdbg.com/download/latest/installer

Or portable ZIP: https://covdbg.com/download/latest/portable

### 2. Create configuration file (.covdbg.yaml)

```yaml
version: 1
source_root: "."
coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
        - "src/**/*.h"
      exclude:
        - "build/**"
        - "third_party/**"
```

### 3. Run coverage

```powershell
# Set license (commercial) or use --fetch-license (open source)
$env:COVDBG_LICENSE = "<your-jwt-token>"

# Run tests with coverage
covdbg --config .covdbg.yaml --output coverage.covdb tests.exe

# Export to LCOV
covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov
```

## CLI Reference

### Run Mode (Default)

Execute a program under coverage tracking:

```powershell
covdbg [OPTIONS] <program> [args...]
```

**Essential options:**
- `--config <path>` or `-c`: Path to .covdbg.yaml (required)
- `--output <path>` or `-o`: Output .covdb file
- `--license <JWT>`: License token (or env: COVDBG_LICENSE)
- `--license-file <path>`: License file path (or env: COVDBG_LICENSE_FILE)
- `--fetch-license`: Auto-fetch OSS license for public repos
- `--log-level <level>`: TRACE, DEBUG, INFO, WARN, ERROR, NONE

**Examples:**

```powershell
# Basic usage
covdbg --config .covdbg.yaml --output results.covdb tests.exe

# Pass arguments to target
covdbg -c .covdbg.yaml -o results.covdb tests.exe --gtest_filter="MyTest.*"

# Open source (auto license)
covdbg --fetch-license -c .covdbg.yaml -o results.covdb tests.exe
```

### Convert Subcommand

Export .covdb to standard formats:

```powershell
covdbg convert --input <file.covdb> --format <FORMAT> --output <path>
```

**Formats:**
- `LCOV`: Single text file (for Codecov, CI services)
- `GCOV`: Directory of .gcov files

**Examples:**

```powershell
# Export to LCOV
covdbg convert -i results.covdb -f LCOV -o coverage.lcov

# Export to GCOV
mkdir gcov-output
covdbg convert -i results.covdb -f GCOV -o gcov-output\
```

### Merge Subcommand

Combine multiple coverage databases:

```powershell
covdbg merge --input <a.covdb> --input <b.covdb> --output <merged.covdb>
```

**Example:**

```powershell
covdbg merge -i unit.covdb -i integration.covdb -o merged.covdb
```

### Analyze Subcommand

Extract coverable lines from binaries without execution (for including uncovered code in reports):

```powershell
covdbg analyze --input <binary> --output <out.covdb> [--config <path>]
```

**Example:**

```powershell
# Analyze for uncovered code
covdbg analyze -i app.exe -o app-symbols.covdb -c .covdbg.yaml

# Merge with test coverage for complete picture
covdbg merge -i app-symbols.covdb -i tests.covdb -o complete.covdb
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `COVDBG_LICENSE` | License JWT token |
| `COVDBG_LICENSE_FILE` | Path to license file |
| `COVDBG_FETCH_LICENSE` | Auto-fetch OSS license (true/false) |
| `COVDBG_CONFIG` | Path to .covdbg.yaml |
| `COVDBG_OUTPUT` | Output .covdb path |
| `COVDBG_APPDATA` | App data directory (logs, cache) |
| `COVDBG_MODE` | Execution mode (ONE_SHOT, PERSISTENT) |
| `COVDBG_LOG_LEVEL` | Console log level |
| `COVDBG_LOG_FILE` | Custom log file path |
| `COVDBG_HTTP_TIMEOUT` | HTTP timeout in seconds (default: 30) |

## Configuration File (.covdbg.yaml)

### Minimal Example

```yaml
version: 1
coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
```

### Complete Example

```yaml
version: 1
source_root: "."
settings:
  log_level: "INFO"
coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
        - "src/**/*.h"
        - "lib/**/*.cpp"
      exclude:
        - "build/**"
        - "third_party/**"
        - "**/*_test.cpp"
    functions:
      exclude:
        - "operator*"
        - "*::<lambda>*"
  targets:
    - target: "integration_tests.exe"
      type: override
      files:
        include:
          - "integration/**"
```

### Pattern Syntax

- `*` matches characters within a path segment
- `**` matches any number of path segments (recursive)
- Exclude patterns always override include patterns

## GitHub Actions Integration

### Complete Workflow Example

```yaml
name: Coverage

on: [push, pull_request]

jobs:
  coverage:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup covdbg
        uses: covdbg/setup-covdbg@v0
        with:
          version: '1.0.0'

      - name: Build
        run: |
          cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
          cmake --build build

      - name: Run Coverage
        shell: pwsh
        env:
          COVDBG_APPDATA: .covdbg
          COVDBG_FETCH_LICENSE: true  # Open source
          # Or for commercial: COVDBG_LICENSE: ${{ secrets.COVDBG_LICENSE }}
        run: |
          covdbg --config .covdbg.yaml --output tests.covdb build/tests.exe

      - name: Convert to LCOV
        run: covdbg convert -i tests.covdb -f LCOV -o coverage.lcov

      - name: Upload to Codecov
        uses: codecov/codecov-action@v5
        with:
          files: coverage.lcov
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

### Open Source Projects

```yaml
- name: Run Coverage
  env:
    COVDBG_FETCH_LICENSE: true
  run: covdbg --config .covdbg.yaml -o coverage.covdb tests.exe
```

### Commercial Projects

```yaml
- name: Run Coverage
  env:
    COVDBG_LICENSE: ${{ secrets.COVDBG_LICENSE }}
  run: covdbg --config .covdbg.yaml -o coverage.covdb tests.exe
```

## Codecov Integration

### Basic Usage

```yaml
# 1. Run tests with coverage
- name: Run tests
  run: covdbg -c .covdbg.yaml -o coverage.covdb tests.exe

# 2. Convert to LCOV
- name: Convert
  run: covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov

# 3. Upload
- name: Upload to Codecov
  uses: codecov/codecov-action@v5
  with:
    files: coverage.lcov
  env:
    CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

### Advanced Usage (Include Uncovered Code)

For complete coverage including unexecuted code paths:

```yaml
# 1. Run tests
- run: covdbg -c .covdbg.yaml -o tests.covdb tests.exe

# 2. Analyze binaries for all coverable lines
- run: |
    covdbg analyze -i app.exe -o app.covdb -c .covdbg.yaml
    covdbg analyze -i lib.dll -o lib.covdb -c .covdbg.yaml

# 3. Merge coverage with symbols
- run: covdbg merge -i tests.covdb -i app.covdb -i lib.covdb -o merged.covdb

# 4. Convert and upload
- run: covdbg convert -i merged.covdb -f LCOV -o coverage.lcov
- uses: codecov/codecov-action@v5
  with:
    files: coverage.lcov
  env:
    CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

## Common Workflows

### Single Test Suite

```powershell
covdbg -c .covdbg.yaml -o coverage.covdb tests.exe
covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov
```

### Multiple Test Suites

```powershell
covdbg -c .covdbg.yaml -o unit.covdb unit_tests.exe
covdbg -c .covdbg.yaml -o integration.covdb integration_tests.exe
covdbg merge -i unit.covdb -i integration.covdb -o merged.covdb
covdbg convert -i merged.covdb -f LCOV -o coverage.lcov
```

### Complete Coverage Report (Include Unexecuted Code)

```powershell
# Run tests
covdbg -c .covdbg.yaml -o tests.covdb tests.exe

# Analyze all code (captures functions never called)
covdbg analyze -i app.exe -o symbols.covdb -c .covdbg.yaml

# Merge for complete picture
covdbg merge -i tests.covdb -i symbols.covdb -o complete.covdb

# Export
covdbg convert -i complete.covdb -f LCOV -o coverage.lcov
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error (invalid args, license issues, etc.) |
| 2 | No functions passed coverage filter |

## Troubleshooting

### No coverage output
- Check license is set (`COVDBG_LICENSE` or `--fetch-license`)
- Ensure PDB files exist alongside binaries
- Use `--log-level DEBUG` for detailed output

### Exit code 2 (no functions to track)
- Review .covdbg.yaml include/exclude patterns
- Start with broad includes: `include: ["**/*.cpp"]`

### Missing source files in export
- Check include patterns match your source structure
- Set `source_root` to normalize paths

## Licensing

- **Open Source**: Free for public repositories (use `--fetch-license`)
- **Commercial**: JWT license token required
- **Enterprise**: Volume licensing available

Contact: info@covdbg.com

## Sitemap

### Documentation
- https://covdbg.com/docs/ - Documentation hub
- https://covdbg.com/changelog/ - Release notes
- https://covdbg.com/getting-started/ - Getting started overview
- https://covdbg.com/installation/ - Installation guide
- https://covdbg.com/quick-start/ - Quick start tutorial

### Guides
- https://covdbg.com/guides/ - Guides overview
- https://covdbg.com/report-formats/ - LCOV and GCOV export formats

### Use Cases
- https://covdbg.com/use-cases/ - Use cases overview
- https://covdbg.com/ci-cd/ - CI/CD automation
- https://covdbg.com/enterprise/ - Enterprise software coverage
- https://covdbg.com/legacy-refactoring/ - Legacy code refactoring
- https://covdbg.com/open-source/ - Open source projects (free)

### Integrations
- https://covdbg.com/integrations/ - Integrations overview
- https://covdbg.com/codecov/ - Codecov integration guide
- https://covdbg.com/github-actions/ - GitHub Actions setup

### Reference
- https://covdbg.com/reference/ - Reference documentation
- https://covdbg.com/cli-reference/ - CLI command reference
- https://covdbg.com/configuration/ - .covdbg.yaml configuration
- https://covdbg.com/troubleshooting/ - Troubleshooting guide

### Product
- https://covdbg.com/download/ - Download covdbg
- https://covdbg.com/pricing/ - Pricing information
- https://covdbg.com/request-quote/ - Request enterprise quote

### Support
- https://covdbg.com/support/ - Support options
- https://covdbg.com/resources/ - Resources hub

### Programs
- https://covdbg.com/programs/ - Programs overview
- https://covdbg.com/open-source-program/ - Open source program details

### Company
- https://covdbg.com/company/ - About Liasoft
- https://covdbg.com/contact/ - Contact information

### Legal
- https://covdbg.com/eula/ - End user license agreement
- https://covdbg.com/privacy/ - Privacy policy
- https://covdbg.com/terms/ - Terms of service
- https://covdbg.com/security/ - Security statement
- https://covdbg.com/cookies/ - Cookie policy
- https://covdbg.com/responsible-disclosure/ - Security disclosure policy

## Quick Reference Card

| Task | Command |
|------|---------|
| Run coverage | `covdbg -c .covdbg.yaml -o out.covdb tests.exe` |
| Export LCOV | `covdbg convert -i out.covdb -f LCOV -o coverage.lcov` |
| Export GCOV | `covdbg convert -i out.covdb -f GCOV -o ./gcov/` |
| Merge databases | `covdbg merge -i a.covdb -i b.covdb -o merged.covdb` |
| Analyze binary | `covdbg analyze -i app.exe -o symbols.covdb` |
| Silent mode | `covdbg --log-level NONE -c .covdbg.yaml -o out.covdb tests.exe` |
| Debug mode | `covdbg --log-level DEBUG -c .covdbg.yaml -o out.covdb tests.exe` |
| Open source | `covdbg --fetch-license -c .covdbg.yaml -o out.covdb tests.exe` |

## Links

- Website: https://covdbg.com
- Documentation: https://covdbg.com/docs/
- GitHub (Quick Start): https://github.com/covdbg/quick-start
- Setup Action: https://github.com/covdbg/setup-covdbg
- Support: support@covdbg.com
- Sales: info@covdbg.com