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).