covc - Compile

covc [options] compiler ... source ...
BullseyeCoverage/bin/compiler ... source ...

Description

covc compiles C/C++ source files after adding coverage measurement probes. covc preprocesses each source file, adds probes to the preprocessed code, then compiles it using your compiler. The coverage file is created if it does not exist. An entry is created in the coverage file for each source file processed. The coverage file, named test.cov by default, contains all BullseyeCoverage data for all instrumented executables. Measurements are merged into the file by the BullseyeCoverage run-time. The coverage file does not grow in size when the instrumented executable runs. covc does not modify the original source files.

You can invoke covc directly and specify the compiler as the first argument, or you can invoke covc through an interceptor. An interceptor is a link made to the covc program file using the compiler name, in the BullseyeCoverage bin directory.

covc passes control directly to your compiler silently without taking any other action under the following conditions:

covc is invoked through an interceptor and coverage build is disabled.
Option -i/--if-enabled is specified and coverage build is disabled.
The compiler command specifies an action that does not produce any object code. For example, the compiler command produces makefile dependencies only.
The compiler options include -DBullseyeCoverageDisable.

Instrumented object files must be linked with the BullseyeCoverage run-time library. covc adds the appropriate run-time library to the link command unless one of the following conditions occur.

The command does not produce an executable due to a compiler option such as -c, -E, -P, -S.
The command performs a partial link.
The command contains the name of a BullseyeCoverage run-time library, which is a source, object or library beginning with the prefix libcov-.

covc recognizes special commands in source code within #pragma directives, _Pragma expressions and string literals. The commands have the forms shown below.

#pragma BullseyeCoverage command ...
_Pragma("BullseyeCoverage command ...")
"BullseyeCoverage command ..."

where command is one of:

`ignore[:`n`]`	Turn off instrumentation for the following n lines. Without `:`n, instrumentation is turned off for one line.
`off`	Turn off instrumentation.
`on`	Turn on instrumentation.
`save`	Push the current `on`/`off` setting.
`restore`	Pop the current `on`/`off` setting.

covc defines the macro _BullseyeCoverage to the version number in the decimal format xyyzzz where x, yy, and zzz are the major, minor, and release numbers, respectively.

Options

`-d`Dir	`--srcdir` Dir	Store source file names relative to source directory Dir rather than relative to the directory where the coverage file is located. This setting is stored in the coverage file when covc creates the file. When the coverage file already exists, this option is ignored and covc uses the setting stored in the file.
`-h`	`--help`	Display a summary of options.
`-i`	`--if-enabled`	Instrument only if coverage build is enabled. Use this option to control enabling and disabling coverage build when invoking `covc` explicitly.
`-f`Path	`--file` Path	The coverage file is specified by Path. The default is `test.cov`.
`-l`	`--leave`	Leave intermediate source files with probes in the temporary directory. For a large project, this option can consume a lot of file system space. To determine the temporary directory on Unix-like systems, `covc` first checks for the `COVTMPDIR` environment variable, then `TMPDIR`, then `TMP`. If neither variable exists, `covc` uses `/tmp`.
`-q`	`--quiet`	Suppress warnings and the copyright message.
`-t`List	`--select` List	Apply exclusions in the comma-separated List of Regions. Normally you should use the Coverage Browser or covselect to exclude code rather than this option. Do not write spaces in List. Multiple occurrences of this option are allowed.
`-v`	`--verbose`	Show informational messages.
`--crt`		Use the run-time library version that depends on the C standard library. Use this option if you see a run-time error due to a code signing issue. This option only has an effect with compilers that use the Microsoft run-time library.
`--lib` Path		covc uses the BullseyeCoverage run-time library specified by Path rather than automatically selecting a library for the native operating system. You can use this option when cross-compiling as an alternative to modifying linker arguments.
`--kernel`		Use an instrumentation method that may consume less stack space. Do not use this option if the instrumented code contains C++ overloaded logical operators. Calls to the Windows API `FltRegisterFilter` are intercepted to gracefully handle driver unloading. No optimizations to expand inline functions are added. No C++ static constructors or destructors are used for instrumentation. This option is automatically enabled when Microsoft C++ `/kernel` is enabled.
`--macro`		Instrument macro expansions at the point of invocation. Measuring macro expansions is undesirable. It causes dilution of the overall coverage measurements. You cannot see what code is instrumented at the point of a macro invocation. If you wish to measure code in a macro definition, it is recommended to convert the macro to an inline function.
`--mspp` file		This option can be used to work around bugs in the Microsoft traditional preprocessor that are not fully mimicked by the BullseyeCoverage preprocessor. The argument file contains the names of individual macros to expand by spawning the compiler. C and C++ style comments may occur in the file. Using `--mspp` can have a significant performance impact and should be used as a last resort only if the recommendations listed below have been tried. Use the Microsoft standard conforming preprocessor (`cl.exe` option `/Zc:preprocessor`). With this compiler option enabled, the Microsoft and BullseyeCoverage preprocessors behave the same and `--mspp` is ignored. Update to the latest BullseyeCoverage. Update to the latest Windows SDK. Update to the latest version of all third party libraries.
`--no-autox`		Do not automatically exclude compiler, system, and third-party headers. Without this option, `covc` excludes the code listed below. Headers specified by the Microsoft C++ `/external` options Directories specified by the GCC `-isystem` option Windows SDK headers Boost libraries Google Test
`--no-banner`		Suppress startup banner
`--no-lib`		Do not automatically link with the BullseyeCoverage run-time library.
`--section`		Place instrumentation data in sections `.bcovcon` and `.bcovbss`. This option only takes effect if the compiler supports placing data into specific sections. Placing the data may be helpful when targeting an embedded system.
`--strict`		In conformance with standards, always report parsing errors in template definitions. Using this option improves error readability. This option is automatically enabled unless the compiler delays parsing template syntax until instantiation, such as with Microsoft C++ option `/permissive`.
`--symbolic`		Resolve symbolic links in source and object filenames before adding them into the coverage file. Use this option if you have symbolic links that cause source files to appear in more than one directory.

Examples

cov01 -1
cc -c source.c

covc cc -c source.c

You can use directives as shown below to exclude a portion of code without affecting the surrounding selection status.

#pragma BullseyeCoverage save off
/* This code not instrumented */
#pragma BullseyeCoverage restore

Environment Variables

`BULLSEYE_LIB`	Specifies a location to find the BullseyeCoverage run-time libraries rather than BullseyeCoverage`/lib`.
`BULLSEYE_PATH`	Specifies where to search for your compiler, instead of using the `PATH` environment variable. Normally you should not set this variable. You only need to set this variable if you cannot prefix the compiler invocation with "`covc -i` ", and you cannot modify the `PATH` environment variable, and `PATH` does not contain the directory of your compiler. This variable has the same format as `PATH`. Do not set this variable to BullseyeCoverage`/bin`.
`COVAPPDATADIR`	This environment variable applies to Unix-like systems only and specifies the location for settings and cached information. The default is `$HOME/.BullseyeCoverage`, or `/tmp/BullseyeCoverage` if the home directory is not writable.
`COVFILE`	The coverage file. Option `-f` (`--file`) overrides this setting.
`COVSRCDIR`	The source file directory. Option `-d` (`--srcdir`) overrides this setting.
`COVCOPT`	Options in this environment variable are added to the command line after options from configuration files.
`COVCCFG`	Configuration file. See FILES.
`COVTMPDIR`	The temporary directory for intermediate instrumented files.
`TMPDIR`	The temporary directory.
`TMP`	The temporary directory if `TMPDIR` is not set.

Files

If the files listed below exist, they contain initial options separated by white space. Within these files, $NAME is replaced by the value of the environment variable named NAME.

BullseyeCoverage/bin/covc.cfg
home-directory/covc.cfg

Updated: 8 Dec 2023