[![Build Status](https://travis-ci.com/RPGillespie6/fastcov.svg?branch=master)](https://travis-ci.com/RPGillespie6/fastcov)
[![Code Coverage](https://img.shields.io/codecov/c/github/rpgillespie6/fastcov.svg)](https://codecov.io/gh/RPGillespie6/fastcov)
[![PyPI Version](https://img.shields.io/pypi/v/fastcov.svg)](https://pypi.org/project/fastcov/)

# fastcov
A massively parallel gcov wrapper for generating intermediate coverage formats *fast*

The goal of fastcov is to generate code coverage intermediate formats *as fast as possible*, even for large projects with hundreds of gcda objects. The intermediate formats may then be consumed by a report generator such as lcov's genhtml, or a dedicated front end such as coveralls. fastcov was originally designed to be a drop-in replacement for lcov (application coverage only, not kernel coverage).

Currently the only intermediate formats supported are gcov json format, fastcov json format, and lcov info format. Adding support for other formats should require just a few lines of python to transform gcov json format to the desired shape.

In order to achieve the speed gains, a few constraints apply:

1. GCC version >= 9.0.0

These versions of GCOV have support for JSON intermediate format as well as streaming report data straight to stdout. This second feature (the ability for gcov to stream report data to stdout) is critical - without it, fastcov cannot run multiple instances of gcov in parallel without loss of correctness.

If your linux distribution doesn't ship with GCC 9, the current easiest way (in my opinion) to try out fastcov is to use the fastcov docker image, which has a GCC 9 compiler, Python3, and CMake inside:

```bash
docker pull rpgillespie6/fastcov:latest
```

If you need other dependencies, just modify the Dockerfile and rebuild.

2. Object files must be either be built:

- Using absolute paths for all `-I` flags passed to the compiler

or

- Invoking the compiler from the same root directory

If you use CMake, you are almost certainly satisfying this second constraint (unless you care about `ExternalProject` coverage).

## Quick Start

Assuming you now have access to GCC 9, fastcov is easy to use:

(Optional - if using docker image):
```bash
$ docker run -it --rm -v ${PWD}:/work -w /work -u $(id -u ${USER}):$(id -g ${USER}) rpgillespie6/fastcov
$ <build project>
```

Once the project is built:
```bash
$ cd build_dir
$ fastcov.py --zerocounters
$ <run unit tests>
$ fastcov.py --exclude /usr/include --lcov -o report.info
$ genhtml -o code_coverage report.info
```

Note that many of the options (such as `--exclude`) can take a list of parameters. For example, you could do something like:

```bash
$ fastcov.py --exclude /usr/include test/ ext/ --lcov -o report.info
```

Check out `fastcov.py --help` for more features and filtering options!

## Installation

A minimum of Python 3.5 is currently required.

Fastcov is a single source python tool. That means you can simply copy `fastcov.py` from this repository and run it directly with no other hassle.

However, fastcov is also available as a Python3 package that can be installed via pip3.

Install newest stable fastcov release from PyPI:

```bash
$ pip3 install fastcov
```

Install development version from GitHub:

```bash
$ pip3 install git+https://github.com/rpgillespie6/fastcov.git
```

## Benchmarks

Anecdotal testing on my own projects indicate that fastcov is over 100x faster than lcov and over 30x faster than gcovr:

Project Size: ~250 .gcda, ~500 .gcov generated by gcov

Time to process all gcda and parse all gcov:

- fastcov: ~700ms
- lcov:    ~90s
- gcovr:   ~30s

Your mileage may vary depending on the number of cores you have available for fastcov to use!