Code coverage with dgcov
Contents
The dgcov tool helps you check the coverage for new code.
Overview
The dgcov program runs gcov for code coverage analysis, and reports missing coverage only for those lines that are changed by the specified revision(s). Revisions are specified in any bzr supported format, as individual revisions or ranges.
If no revisions are specified, the default is to work on all unpushed
revisions (bzr missing --this).
It's recommended that a developer runs dgcov on his new code before pushing it into a mariadb repository.
Usage
./dgcov.pl --help ./dgcov.pl [options] [revisionspec [revisionspec ...]]
Options and Variables:
| Short Option | Long Option | Description |
|---|---|---|
-h | --help | Print help and exit |
-v | --verbose | Show commands run. |
-a | --all | All lines modified in revisions are printed. |
-c N | --context=N | Show N (default 3) lines of context around reported lines. |
-p | --purge | Delete all test coverage information, to prepare for a new coverage test. |
-g | --only-gcov | Stop after running gcov, don't run bzr |
-s | --skip-gcov | Do not run gcov, assume .dgcov files are already in place |
-l | --local | Add revisions from bzr missing --this (default if no revisions given and not using -u). |
-u | --uncommitted Also consider changes not committed (slow). |
How to prepare the code for dgcov
Prior to running this tool, the analyzed program should be compiled
with -fprofile-arcs -ftest-coverage (for MySQL,
BUILD/compile-pentium-gcov script does just that),
and the testsuite should be run. dgcov will report all lines that are
modified in the specified revisions and that are reported as not
covered by gcov.
Output
Lines not covered are marked by '#', lines without generated code are
marked with '-', and other lines are marked with the number of times they
were executed. See info gcov for more information.
Lines modified by revisions are pre-fixed by '|', context lines not included
in the specified revisions are prefixed by '.'. Non-modified context lines
that are not covered by tests are marked with '+++++' instead of '#'.
How to suppress not coveraged lines
Reports of non-covered lines may be suppressed by 'purecov' annotations:
| Marker | Description |
|---|---|
| inspected | For code that cannot be covered (like out of memory conditions), but which has been reviewed and is considered correct. |
| deadcode | Unreachable code. |
| tested | Code that is not covered by automatic tests, but which has been manually tested. |
Markers are used in comments, prefixed with purecov:. This is done to be compatible with the old purecov tool from IBM. You can mark more than one line with a begin...end block.
Note that if annotated lines are actually covered, they will be reported as errors as well (since the annotations are then clearly wrong).
Example
Annotations may be for a single line:
if((p= malloc(10)) == NULL) return 0; /* purecov: inspected */
or for a span of lines:
<
/* purecov: begin deadcode */ tmp= x; x= y; y= tmp; /* purecov: end */
Where to get the code
You can find the code for it at bzr branch lp:mariadb-tools or http://bazaar.launchpad.net/~maria-captains/mariadb-tools/trunk/view/head:/dgcov.pl.
References
dgcov was first announced here by Kristian Nielsen.
