Provided by: ggcov_0.9+20190314-0ubuntu1_amd64 
NAME
ggcov-webdb - generate intermediate database for ggcov web interface
SYNOPSIS
ggcov-webdb [[-r] directory|file] ...
DESCRIPTION
Ggcov-webdb generates an intermediate database and tree of source files from a development directory, in
the form of a tarball. The files in this tarball are later used by the ggcov PHP pages to present test
coverage data to WWW browsers.
Test coverage data is produced by C and C++ programs compiled with gcc -fprofile-arcs -ftest-coverage.
So the combination of ggcov-webdb and the ggcov PHP pages is basically a WWW replacement for the gcov
program that comes with gcc.
The intermediate database approach is used to handle the common case where the development machine and
the web server machine are separate. The database contains coverage data in an indexed,
platform-independent, PHP-friendly form. Because the database format is platform-independant the PHP
pages can be deployed on web servers of a different architecture to the development machines. In fact
the ggcov web pages support any web server that meets the following criteria:
• supports PHP version 4.3 or later, and
• provides the dba extension with the db4 provider (which ggcov uses to read the intermediate
database), and
• provides the gd extension (which ggcov uses to generate the bargraphs on the Summary page).
The sourceforge.net project web server is an example of such a server.
Ggcov-webdb produces a gzipped tarball containing the intermediate database itself and copies of all the
source files which are mentioned in the database. This is all the information that the ggcov web pages
need, in one bundle which is convenient to copy from the development machine to the web server. Usually
this tarball would be extracted into a subdirectory of /var/cache/ggcov/tests/ on the web server.
Arguments are used to specify how to find coverage data files. The arguments can combinations of:
directory
The directory is scanned for source files, which are handled as if they had been specified on the
commandline (except that missing coverage data files are silently ignored). If the -r flag is in
effect, sub-directories are scanned recursively. Multiple directories can be specified and are
scanned in the order given.
executable
The executable file is scanned for debugging records which contain source file names, and each
source file which exists is handled as if it had been specified on the command line (except that
missing coverage data files are silently ignored). Any shared libraries on which the executable
depends are also scanned. Multiple executables can be specified and are scanned in the order
given. This feature is only available on some platforms (for example, i386-linux).
source-file
Is any regular file ending in one of the file extensions .c, .cc, .cxx, .cpp, or .C. Source files
are matched to their corresponding coverage data files (.gcno and .gcda files, or .bb, .bbg, and
.da files with older compilers) and object files by searching for a file of the same basename and
the appropriate extension first in the same directory as the source file and then in all the
directories specified on the command line (in the order they were specified).
OPTIONS
-f test.tgz, --output-file=test.tgz
Generate output to filename test.tgz instead of the default ggcov.webdb.tgz. The special filename
- can be used to generate output to stdout.
-o dir, --object-directory=dir
Add the directory dir to the search path for object files and coverage data files.
-r, --recursive
When a directory is specified on the command line, search for coverage data files recursively in
all child directories.
-X symbols, --suppress-ifdef=symbols
Suppress code inside C pre-processor directives which depend on any of the given symbols.
Suppressed code is not included in statistics or summaries. One or more symbols may be given,
separated by commas or whitespace. Ggcov-webdb understands the following subset of the C pre-
processor command set:
• #if SYMBOL
• #if defined(SYMBOL)
• #ifdef SYMBOL
• #ifndef SYMBOL
• #else
• #endif
For example, -X DEBUG will suppress the fprintf() call in this code:
unsigned int
my_function(unsigned int x)
{
x += 42;
#ifdef DEBUG
fprintf(stderr, "my_function: x=%u\n", x);
#endif
return x;
}
This option is useful for suppressing test infrastructure code, debugging code, or other code
which is compiled into the coverage test executable but whose coverage is not significant.
-Y words, --suppress-comment=words
Suppress code on lines which also contain a single-line comment comprising only one of the given
words. Suppressed code is not included in statistics or summaries. One or more symbols may be
given, separated by commas or whitespace. For example, specifying -Y IGNOREME will suppress the
assert() in this code:
unsigned int
my_function(unsigned int x)
{
x += 42;
assert(x >= 42); /* IGNOREME */
return x;
}
This option is useful for suppressing test infrastructure code, debugging code, or other code
which is compiled into the coverage test executable but whose coverage is not significant.
-Z startword,endword,... --suppress-comment-between=startword,endword,...
Suppress code on lines between those containing a single-line comment comprising only startword
and the next single-line comment comprising only endword. Suppressed code is not included in
statistics or summaries. Two or more symbols may be given, in pairs, separated by commas or
whitespace. For example, -Z STARTIGNORE,ENDIGNORE will suppress the entire function in this code:
/* STARTIGNORE */
unsigned int
my_function(unsigned int x)
{
x += 42;
return x;
}
// ENDIGNORE
This option is useful for suppressing test infrastructure code, debugging code, or other code
which is compiled into the coverage test executable but whose coverage is not significant.
EXAMPLES
Generate intermediate database for all the available source in the executable a.out (on some platforms
only), and install as test foo in the default tests location.
mkdir /var/cache/ggcov/tests/foo
ggcov-webdb -f - a.out |
(cd /var/cache/ggcov/tests/foo ; tar -xzf - )
Generate intermediate database for all the C source in the current directory.
ggcov-webdb *.c
Generate intermediate database for all the C source in one directory where the object files and test
coverage data files are in different directories:
ggcov-webdb /foo/obj/ /foo/cov-data/ /foo/src/
AUTHOR
Written by Greg Banks <gnb@fastmail.fm>.
COPYRIGHT
ggcov is Copyright © 2001-2015 Greg Banks <gnb@fastmail.fm>.
This is free software; see the COPYING file for copying conditions. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.