NAME

       ggcov-run - run an instrumented test program

SYNOPSIS

       ggcov-run [options] [--] program args...

DESCRIPTION

       Ggcov-run  can be used to run a test program, instrumented using gcc --coverage when built, under certain
       conditions.  It's use is entirely optional, as the default behaviour of the gcc instrumention is designed
       to be useful under most conditions.

       Ggcov-run takes as arguments a program and it's arguments, and runs the  program  with  some  behavioural
       modifications  (in  the  manner  of  strace).   If  given  no  options,  the  program  is run without any
       modifications.

GCDA FILE LOCATIONS

       One problem with the default behaviour of the gcc instrumentation  involves  the  locations  of  coverage
       data.  Instrumented test programs will read, modify and re-write .gcda files when the program exits.  The
       locations  of  those  files  are  chosen by the compiler at compile time; the files will be placed in the
       build directory next to the corresponding .c file.  The compiler saves this information in the  .o  file.
       For  example,  if  you  compile the file foo.c in the directory /home/me/software/quux, then the pathname
       /home/me/software/quux/foo.gcda is hardcoded in the test  program.   Of  course,  programs  that  examine
       coverage data, like ggcov, look for the .gcda files there.

       For  many  test  applications this works just fine.  Problems arise however when the instrumented program
       needs to be run on another machine, or as another userid, or the build directory is volatile, or  in  any
       other  test  scenario  where  the build directory either does not exist or is not writable by the running
       test program.  In these cases, you need to do some ad-hoc file moving before and after testing  in  order
       to get the .gcda files in the right location on the right machine with the right permissions.

       A  better  approach  is  to  use ggcov-run with the --gcda-prefix option.  This option takes as a value a
       directory which is prepended to the  pathname  of  each  .gcda  file  the  test  program  accesses.   So,
       continuing the above example, running the test program like this:

       me$ ggcov-run --gcda-prefix=/tmp/gcda ./testprogram test-args...

       will  result  in  a  .gcda file being written to /tmp/gcda/home/me/software/quux/foo.gcda.  The directory
       tree will be automatically created as the .gcda files are written, and the file and directory permissions
       will allow read access for all users.

       Note that ggcov also has a --gcda-prefix option which can be used to search for .gcda files in  locations
       other than the build directory.  In our example:

       me$ cd /home/me/software/quux
       me$ ggcov --gcda-prefix=/tmp/gcda -r .

OPTIONS

       -p dir, --gcda-prefix=dir
              Cause  the test program, and any child processes it runs, to redirect any absolute filename ending
              in .gcda to a filename underneath the directory dir.

CAVEATS

       Ggcov-run uses a shared library shim and the LD_PRELOAD  feature  of  the  runtime  linker  to  intercept
       certain  library  calls  by  the  instrumented  program.   For  very good security reasons, LD_PRELOAD is
       disabled for setuid or setgid programs.  So if your test program relies on  setuid  behaviour,  ggcov-run
       will  not  work.   One  possible workaround is to use sudo or su to change userid before using ggcov-run,
       like this:

       me$ sudo -u otheruser ggcov-run --gcda-prefix=/foo ./testprogram

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.

SEE ALSO

       ggcov-run(1).

GGCOV                                               May 2011                                        GGCOV-RUN(1)