Provided by: ggcov_0.8.4-3ubuntu1_amd64 bug

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.