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/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
- Do not include in statistics or summaries, code inside C pre-processor
directives which depend on any of the given symbols. 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
- Do not include in statistics or summaries, code on lines which also
contains a single-line comment comprising only one of the given
words. 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,...
- Do not include in statistics or summaries, code on lines between those
containing a single-line comment comprising only startword and the
next single-line comment comprising only endword. 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/ggcov/tests/foo
ggcov-webdb -f - a.out |
(cd /var/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@users.sourceforge.net>.
COPYRIGHT¶
ggcov is Copyright © 2001-2005 Greg Banks
<gnb@users.sourceforge.net>.
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.