Code Coverage With dgcov

Technical instructions on using the dgcov tool to generate and analyze code coverage reports for the MariaDB server.

This page contains background information for MariaDB developers.

The dgcov tool helps you check the coverage for new code. The dgcov.pl script is part of the mariadb-test framework (and any packages that include mariadb-test).

Overview

The dgcov program runs gcov for code coverage analysis aggregates the coverage data, and optionally reports coverage only for those lines that are changed by commits. Commits are specified in the git diff format.

If no commits are specified, the default is to work on all uncommitted changes, if any, otherwise on the last commit (in other words, on git diff HEAD or git diff HEAD^).

It's recommended that a developer runs dgcov on their new code before pushing it into a MariaDB repository.

Usage

./dgcov.pl --help
./dgcov.pl [options] [<commit> [<commit>]]

Options and Variables

Short Option	Long Option	Description
-h	--help	Print help and exit
-v	--verbose	Show commands run.
-p	--purge	Delete all test coverage information, to prepare for a new coverage test.
-o	--only-gcov	Stop after running gcov, don't run git
-s	--skip-gcov	Do not run gcov, assume .gcov files are already in place
-g	--generate	Create .dgcov files for all source files

How to Prepare Code for dgcov

Prior to running this tool, MariaDB should be built like this:

cmake -DENABLE_GCOV=ON

In addition, the test suite should be run. dgcov reports the coverage for all lines modified in the specified commits.

Output

Output .dgcov files have a conventional gcov format: Lines not covered are prefixed with #####, lines without generated code are prefixed with -, and other lines are prefixed with the number of times they were executed. See info gcov for more information.

The patch-like coverage for commits uses gcov format (as above) for lines, changed in these commits, and no prefix at all for lines that were not changed.

Examples

Checking the coverage for all unpushed commits:

dgcov.pl @{u} HEAD

Checking the coverage for all uncommitted changes:

dgcov.pl HEAD

Checking the coverage for a specific commit 1234567:

dgcov.pl 1234567^ 1234567

mariadb-test-run can invoke dgcov automatically:

./mtr --gcov

In the latter case, the coverage for uncommitted changes (or for the last commit) is not printed to stdout, but to the var/last_changes.dgcov file.

Caveats

To be able to run gcov with the mariadb-test framework, you must have gcc version 4.8 or newer.

References

• dgcov was created by Kristian Nielsen and announced here.

• dgcov was reimplemented to aggregate the data, and to work for git and cmake, by Sergei Golubchik.