Provided by: ggcov_0.8.3-1ubuntu1_i386 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/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
              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/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@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.