ggcov-run - run an instrumented test program
] program args...
can be used to run a test program, instrumented using gcc
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.
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.
One problem with the default behaviour of the gcc instrumentation involves the
locations of coverage data. Instrumented test programs will read, modify and
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
in the directory /home/me/software/quux
, then the
is hardcoded in the test
program. Of course, programs that examine coverage data, like ggcov
look for the .gcda
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
. 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 .
- -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.
uses a shared library shim and the LD_PRELOAD
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,
will not work. One possible workaround is to use sudo
to change userid before using ggcov-run
, like this:
me$ sudo -u otheruser ggcov-run --gcda-prefix=/foo ./testprogram
Written by Greg Banks <firstname.lastname@example.org>
ggcov is Copyright © 2001-2011 Greg Banks
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.