BullseyeCoverage Up Contents Search

Excluding Code

Excluding External Code with Compiler Options

You can exclude header files external to your project with the Microsoft C++ /external options or the GCC/Clang -isystem option. These options specify directories containing headers that are maintained and tested by someone else and cause the compiler to suppress warnings in those headers. BullseyeCoverage recognizes these options and automatically excludes the code in those headers, unless you use the covc --no-autox option.

For example, use the Microsoft C++ compiler option /external:I rather than /I to exclude a directory.

cl /Ic:\external_dir                          ← change this
cl /external:I c:\external_dir /external:W0   ← to this

With GCC, use -isystem instead of -I to exclude a directory.

g++ -I/external_dir                           ← change this
g++ -isystem /external_dir                    ← to this

Excluding Regions with Coverage Browser

After building your code, you can easily exclude regions from both the reported results and from subsequent builds using commands in the Coverage Browser menu Region. Select a region, then choose either Region Exclude or Region Include.

Coverage Browser

Saving Exclusions for Reuse

When you have the exclusions you want, use the menu command File Export Exclusions to save the selections separately from the coverage file.

Coverage Browser

You can apply the saved selections to a new coverage file using covselect --import. It is recommended to apply exclusions with covselect after your build finishes rather than at the beginning. This allows adjusting the exclusions without having to rebuild.

rm -f $COVFILE
cov01 -1
(perform build)
cov01 -0
covselect --import BullseyeCoverageExclusions

Excluding with Wildcards

Coverage Browser

You can easily exclude filenames matching a wildcard pattern after they have already been instrumented. In subsequent builds, BullseyeCoverage does not instrument excluded regions.

  1. Use the menu command View Queries.
  2. Use the menu command View Query New Query.
  3. Enable region kind Source Files only.
  4. Enable Wildcard pattern and enter your wildcard pattern in the Names text box.
  5. Press OK.

    New Query

  6. Select all the regions in the right pane.
  7. Use the menu command Region Exclude.

    Menu command Region Exclude

covselect

You can exclude files from all directories using the covselect action -a/--add with the ** wildcard as shown below.

Using a Unix-like shell such as bash:

covselect -a '!**/pattern'	# Need quotes with Unix-like shell

Using Windows shell:

covselect -a !**/pattern

For example, the command below excludes all files named *_test*.cpp in any directory.

covselect -a '!**/*_test*.cpp'

Verify the settings with action -l/--list.

$ covselect -l -q
exclude source **/*_test*.cpp

Embedding Directives in Source Code

You can prevent BullseyeCoverage from instrumenting specific statements using #pragma directives.

The directive #pragma BullseyeCoverage off prevents instrumentation of code that follows, while code following #pragma BullseyeCoverage on is instrumented. For example,

switch (n) {
    case 1: one++; break;
    case 2: two++; break;
    case 3: three++; break;
#if _BullseyeCoverage
    #pragma BullseyeCoverage off
#endif
    default: abort();
#if _BullseyeCoverage
    #pragma BullseyeCoverage on
#endif
}

Use the directive commands save and restore to preserve the effect of encompassing directives. For example:

switch (n) {
    case 1: one++; break;
    case 2: two++; break;
    case 3: three++; break;
#if _BullseyeCoverage
    #pragma BullseyeCoverage save off
#endif
    default: abort();
#if _BullseyeCoverage
    #pragma BullseyeCoverage restore
#endif
}

If your compiler supports _Pragma, you can define macros for excluding code more concisely.

#if _BullseyeCoverage
    #define BullseyeCoverageSaveOff _Pragma("BullseyeCoverage save off")
    #define BullseyeCoverageRestore _Pragma("BullseyeCoverage restore")
#else
    #define BullseyeCoverageSaveOff
    #define BullseyeCoverageRestore
#endif

switch (n) {
    case 1: one++; break;
    case 2: two++; break;
    case 3: three++; break;
BullseyeCoverageSaveOff
    default: abort();
BullseyeCoverageRestore
}

The ignore directive is appropriate for excluding short sections of code.

assert(p != NULL);
#pragma BullseyeCoverage ignore
if (p != NULL)
	p->function();

#pragma BullseyeCoverage ignore:3
void placeHolder1() { }
void noRealCodeHere() { }
void deadCode() { }

The ignore directive provides a terse method for excluding default labels.

switch (n) {
    case 1: one++; break;
    case 2: two++; break;
    case 3: three++; break;
#pragma BullseyeCoverage ignore
    default: abort();
}

Rather than excluding an impossible switch default, you may wish to replace one of your case labels with default, and assert the intended matching value.

Four branches Three branches
switch (n) {
case 1: one++; break;
case 2: two++; break;
case 3: three++; break;
default: assert(false); break;
}
switch (n) {
case 1: one++; break;
case 2: two++; break;
default: assert(n == 3); three++; break;
}

Updated: 4 Dec 2024