pydcov 1.0.6
Incremental C/C++ code coverage tools for CMake projects
Requires Python: >=3.11
Keywords: coverage, incremental, c, cpp, cmake, testing, gcov, llvm-cov

# PyDCov - Incremental C/C++ Code Coverage Tools

[![PyPI version](https://badge.fury.io/py/pydcov.svg)](https://badge.fury.io/py/pydcov)
[![Python Support](https://img.shields.io/pypi/pyversions/pydcov.svg)](https://pypi.org/project/pydcov/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A streamlined incremental coverage tracking system for CMake-based C/C++ projects. PyDCov provides modern Python tools for incremental coverage collection and reporting with support for both GCC/gcov and Clang/llvm-cov toolchains, plus CMake integration setup.

## Features

- **Cross-platform support**: Linux, macOS, Windows
- **Multiple compiler support**: GCC/gcov and Clang/llvm-cov
- **CMake integration**: Seamless integration with CMake build systems
- **Incremental coverage**: Efficient incremental collection and reporting
- **Framework-agnostic**: Works with any testing framework (pytest, unittest, custom executables)
- **Modern Python API**: Clean, well-documented Python interface

## Installation

### Python Package

```bash
pip install pydcov
```

### Standalone Executables

Pre-built standalone executables are available for Linux and macOS from the [GitHub Releases](https://github.com/ethan-li/pydcov/releases) page. These executables don't require Python to be installed on the target system.

- **Linux (x64)**: `pydcov-linux-x64`
- **macOS (ARM64)**: `pydcov-macos-arm64`

### System Requirements

PyDCov requires the following system tools to be installed:

**Build Tools:**
- CMake (3.10 or later)
- Make or Ninja
- GCC or Clang compiler

**Coverage Tools (choose one):**

For GCC:
```bash
# Ubuntu/Debian
sudo apt-get install gcc gcov lcov

# macOS
brew install gcc lcov
```

For Clang:
```bash
# Ubuntu/Debian  
sudo apt-get install clang llvm

# macOS
brew install llvm
```

## Quick Start

### 1. Initialize CMake Integration

In your C/C++ project directory:

```bash
pydcov init-cmake
```

This copies the CMake integration files to your project.

### 2. Update CMakeLists.txt

Add this line to your root CMakeLists.txt:

```cmake
include(cmake/coverage.cmake)
```

### 3. Run Incremental Coverage

```bash
# Initialize incremental tracking
pydcov init

# Add coverage data from test runs
pydcov add python -m pytest tests/test_module1.py
pydcov add python -m pytest tests/test_module2.py

# Generate combined report
pydcov report
```

## Command Reference

### Incremental Coverage Commands

```bash
pydcov init                          # Initialize incremental tracking
pydcov init --pydcov-dir /path/data  # Initialize with custom coverage directory
pydcov add python -m pytest tests/  # Add coverage data from test run
pydcov merge                         # Merge coverage data
pydcov report                        # Generate incremental report
pydcov status                        # Show incremental status
pydcov clean                         # Clean all coverage data
```

### Utility Commands

```bash
pydcov init-cmake              # Copy CMake integration files
pydcov --version               # Show version
pydcov --help                  # Show help
```

## Python API

PyDCov can also be used programmatically:

```python
from pydcov import IncrementalCoverageManager

# Incremental coverage workflow
manager = IncrementalCoverageManager()
manager.init()
manager.add(["python", "-m", "pytest", "tests/module1/"])
manager.add(["python", "-m", "pytest", "tests/module2/"])
manager.merge()
manager.report()
```

## CMake Integration

PyDCov provides a comprehensive CMake module that automatically:

- Detects available compilers and coverage tools
- Configures appropriate coverage flags
- Creates coverage targets (`coverage-clean`, `coverage-report`)
- Supports both GCC/gcov and Clang/llvm-cov workflows
- Integrates with incremental coverage collection

Example CMakeLists.txt:

```cmake
cmake_minimum_required(VERSION 3.10)
project(MyProject)

# Include PyDCov coverage support
include(cmake/coverage.cmake)

# Your project configuration
add_executable(my_app src/main.cpp)

# Coverage will be automatically configured
```

## Examples

### Basic C++ Project

```bash
# Setup
mkdir my-cpp-project && cd my-cpp-project
pydcov init-cmake

# Create CMakeLists.txt with coverage support
echo 'cmake_minimum_required(VERSION 3.10)
project(MyApp)
include(cmake/coverage.cmake)
add_executable(my_app main.cpp)' > CMakeLists.txt

# Run coverage
pydcov init
pydcov add python -m pytest tests/
pydcov report
```

### Integration with CI/CD

```yaml
# GitHub Actions example
- name: Install PyDCov
  run: pip install pydcov

- name: Setup coverage
  run: pydcov init-cmake

- name: Run coverage
  run: |
    pydcov init
    pydcov add python -m pytest tests/
    pydcov report
```

## Troubleshooting

### Common Issues

**"Coverage tools not found"**
- Install GCC/gcov or Clang/llvm-cov
- Ensure tools are in PATH

**"CMake configuration failed"**
- Verify CMake is installed and accessible
- Check that `include(cmake/coverage.cmake)` is in CMakeLists.txt

**"No coverage data found"**
- Ensure tests are actually running
- Verify executables are built with coverage flags

### Getting Help

- Check the [documentation](https://github.com/ethan-li/pydcov)
- Report issues on [GitHub](https://github.com/ethan-li/pydcov/issues)

## License

MIT License. See LICENSE file for details.

## Contributing

Contributions are welcome! Please see the contributing guidelines in the repository.