Hardware Hacking Laboratory Logo
Hardware Hacking Laboratory

FramaCovr: from Frama-C coverage to the gcovr format

H2Lab is releasing FramaCovr, a tool dedicated to code coverage on projects analyzed with Frama-C. The repository is available on GitHub and the package is published on PyPI.

Why FramaCovr

Frama-C provides, through its metrics plugin, a view of the coverage reached during an analysis: the reached functions, their call counts, and the traversed entry points. This information is valuable, but it stays locked in a format specific to Frama-C, which is difficult to exploit in a continuous integration pipeline already tooled around gcovr.

FramaCovr closes this gap: it turns the JSON metrics reports emitted by Frama-C into a JSON report compliant with the gcovr format. This report can then be consumed by gcovr to produce a detailed HTML report, a SonarQube export, a Cobertura report, or any other output already supported by the tool.

How it works

The principle is straightforward:

  1. each metrics report is read; the defined-functions node provides the number of calls of every reached symbol, and the entry-points node lists the traversed symbols;
  2. Frama-C symbol instances are canonicalized (a _<n> suffix denotes a static instance, a __fc_inline_<n> suffix a static inline one), then merged with their call counts summed;
  3. the source directories are walked and parsed with tree-sitter and its C grammar, in order to bind each function name to its implementation file and its executable source lines;
  4. a gcovr JSON document is emitted: a function called at least once is considered covered, and all its executable lines carry its call count.

Usage

framacovr \
  --framac-metrics-files given-framac-run-metrics-coverage.json \
                         another-framac-run-metrics-coverage.json \
  --source-dirs kernel/src kernel/include \
  --source-root . \
  -o framacovr.json

The resulting report then integrates directly with gcovr:

gcovr \
  --root . \
  --json-add-tracefile framacovr.json \
  --html-details coverage-html/coverage.html

Other output formats are available the same way, such as the SonarQube export (--sonarqube) or the text summary (--txt).

Availability

FramaCovr is written in Python (3.11 or newer) and distributed under the Apache 2.0 license. It installs with a single command:

pip install framacovr

The source code, tests, and full documentation are available on the GitHub repository.