pydcov 1.0.2

Incremental C/C++ code coverage tools for CMake projects

PyDCov - Incremental C/C++ Code Coverage Tools

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

pip install pydcov

Standalone Executables

Pre-built standalone executables are available for Linux and macOS from the GitHub 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:

# Ubuntu/Debian
sudo apt-get install gcc gcov lcov

# macOS
brew install gcc lcov

For Clang:

# Ubuntu/Debian  
sudo apt-get install clang llvm

# macOS
brew install llvm

Quick Start

1. Initialize CMake Integration

In your C/C++ project directory:

pydcov init-cmake

This copies the CMake integration files to your project.

2. Update CMakeLists.txt

Add this line to your root CMakeLists.txt:

include(cmake/coverage.cmake)

3. Run Incremental Coverage

# 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

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

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

Python API

PyDCov can also be used programmatically:

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_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

# 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

# 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
• Report issues on GitHub

License

MIT License. See LICENSE file for details.

Contributing

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