Integrating With Your Build Process

The Coverage Build Enable Setting

When coverage build is enabled, BullseyeCoverage intercepts compiler invocations to perform instrumentation. The instrumented code is compiled using your compiler. When disabled, BullseyeCoverage performs no actions and instead passes control directly to your compiler.

You can enable and disable coverage build using any of the methods below.

Coverage Browser menu command Tools Coverage Build.
Microsoft Visual Studio menu command Tools Enable/Disable BullseyeCoverage Build.
The command line program cov01. To enable, use cov01 -1. To disable, use cov01 -0.

By default, the coverage build setting affects all login sessions for the current user account. You can isolate the setting to an individual session by setting environment variable COVBUILDZONE to a unique value within each session.

On Windows, the coverage build setting is stored in the registry at HKEY_CURRENT_USER\Software\Bullseye Testing Technology\BullseyeCoverage. On Unix-like systems, the setting is stored in the directory $HOME/.BullseyeCoverage.

Compiler Interceptors

The BullseyeCoverage/bin directory contains compiler interceptors, which are executable files named the same as a compiler program. When control passes to the compiler interceptor and coverage build is enabled, the compiler interceptor invokes covc to perform instrumentation. With coverage build disabled, the compiler interceptor passes control directly to your compiler. A compiler interceptor is actually a link to (or a copy of) the covc executable image.

The Windows installer creates compiler interceptors for the compilers selected on the Compilers page. The installer for Unix-like systems creates compiler interceptors for all known compilers found in the PATH environment variable. You can choose the compiler interceptors using the Coverage Browser menu command Tools Options.

To manually create a compiler interceptor on Windows:

cd %ProgramFiles%\BullseyeCoverage\bin
copy covc.exe compiler.exe

To manually create a compiler interceptor on Unix-like systems:

cd BullseyeCoverage/bin
ln -s covc compiler

Integration Alternatives

Integration with Microsoft Visual Studio is performed automatically by the installer. Otherwise, check the section Configuring Development Systems to find instructions tailored to your development system. If none of the topics apply, use the integration method below that best matches your build process.

Integration is successful when you see the BullseyeCoverage startup banner when building with coverage build enabled.

BullseyeCoverage Compile C++
Copyright (c) Bullseye Testing Technology

BullseyeCoverage should intercept both compile and link commands. Integrating for compiling but not linking may result in linker errors.

Method 1: Find Interceptors with the PATH

Choose this method if you want your build process to operate similarly regardless of whether BullseyeCoverage is installed or not.

Set the PATH environment variable with BullseyeCoverage/bin before your compiler. When your build system invokes the compiler, it finds and invokes the interceptor. BullseyeCoverage finds your compiler further along in the PATH.
For example, on Windows:
```
set PATH=%ProgramFiles%\BullseyeCoverage\bin;%ProgramFiles%\Microsoft Visual Studio\VC\bin;%PATH%
```
For example, on Unix-like systems:
```
PATH=/opt/BullseyeCoverage/bin:/opt/compiler/bin:$PATH
```
Your makefile or build script invokes the compiler using its basename, rather than its absolute path. For example, in a makefile:
```
CC = /opt/compiler/bin/cc     # wrong
CC = cc                       # correct
```

Example commands invoked by your build system:

cc -c source1.c
cc -c source2.c
...
cc -o program source1.o source2.o ...

Method 2: Invoke covc Directly

Choose this method if either you cannot modify the PATH environment variable or you must invoke your compiler using an absolute path.

With this method, your build process invokes the covc program, passing your compiler command as arguments.

Example 1:

CC = cc -g                                      # Without BullseyeCoverage
CC = /opt/BullseyeCoverage/bin/covc -i cc -g    # With BullseyeCoverage

Example 2:

CC = /opt/compiler/bin/cc -g                                        # Without BullseyeCoverage
CC = /opt/BullseyeCoverage/bin/covc -i /opt/compiler/bin/cc -g      # With BullseyeCoverage

Example commands invoked by your build system:

/opt/BullseyeCoverage/bin/covc -i /opt/compiler/bin/cc -c source1.c
/opt/BullseyeCoverage/bin/covc -i /opt/compiler/bin/cc -c source2.c
...
/opt/BullseyeCoverage/bin/covc -i /opt/compiler/bin/cc -o program source1.o source2.o ...

Method 3: Invoke Interceptor Directly

Choose this method if you cannot use method 2 because you must specify your compiler as a single filename, rather than a command with arguments.

With this method, your build process invokes the interceptor using an absolute path. BullseyeCoverage finds your compiler in a directory listed in the BULLSEYE_PATH environment variable, which has the same format as the PATH environment variable.

For example,

CC = /opt/compiler/bin/cc           # Without BullseyeCoverage

BULLSEYE_PATH = /opt/compiler/bin   # With BullseyeCoverage
CC = /opt/BullseyeCoverage/bin/cc

Example commands invoked by your build system:

/opt/BullseyeCoverage/bin/cc -c source1.c
/opt/BullseyeCoverage/bin/cc -c source2.c
...
/opt/BullseyeCoverage/bin/cc -o program source1.o source2.o ...

The Run-Time Library

The BullseyeCoverage instrumentation requires some supporting functions, which are implemented in the BullseyeCoverage run-time library. BullseyeCoverage automatically links your programs with this library for native programs and some embedded targets.

If you encounter an unresolved symbol with prefix cov_, first check Configuring Development Systems for instructions tailored to your development system. If none of the topics apply, see Embedded Systems.

Determining Whether an Object or Executable Is Instrumented

To determine whether a linked executable image (program, shared library or DLL) is instrumented, scan the file to see if the text BullseyeCoverage occurs. For example, you can use the commands below. On Windows, find these commands in Cygwin or MSYS2 .

$ strings program.exe | grep "^BullseyeCoverage "
BullseyeCoverage 9.1.2      ← software version
BullseyeCoverage 8.20.0     ← coverage file format version

To determine whether an object file or static library is instrumented, look for an unresolved symbol named cov_probe_vN. For example, you can use the commands below.

$ strings object.obj | grep cov_probe
cov_probe_v12

Updated: 26 Sep 2023