G Parent topic: G

gcov

Updated: October 28, 2024

Gather code coverage data (GNU)

Syntax:

gcov_variant [options] sourcefile

where gcov_variant depends on the target platform, as follows:

Target platform gcov_variant
ARMv7 ntoarmv7-gcov
AArch64 ntoaarch64-gcov
x86 64-bit ntox86_64-gcov

Runs on:

Linux, Mac, Microsoft Windows

Options:

-b or --branch-probabilities
Write branch frequencies to the output file and branch summary info to standard output. This lets you see how often each branch was taken.
-c or --branch-counts
Write branch frequencies as the number of branches taken instead of the percentage of branches taken.
-f or --function-summaries
Output summaries for each function in addition to the file level summary.
-h or --help
Display gcov command-line options, and then exit.
-l or --long-file-names
Create long file names for included source files.

For example, if x.h was included in a.c, then running gcov -l on a.c will produce a.c##x.h.gcov instead of x.h.gcov. This can be useful if x.h is included in multiple source files.

-n or --no-output
Don't create the output file.
-o directory|file or --object-directory directory, --object-file file
Specify the directory containing the gcov data files or the object path name.

The gcov utility searches for the .bb, .bbg, and .da data files using this option. If a directory is specified, the data files are in that directory and named after the source file name without its extension. If a file is specified, the data files are named after that file without its extension. If this option isn't specified, it defaults to the current directory.

-p or --preserve-paths
Preserve complete path information in the names of generated .gcov files.

Without -p only the filename component is used. With -p, all directories are used, with / characters translated to # characters, . directory components removed and .. components renamed to ^. This is useful if source files are in several different directories.

The -p option also affects the -l option.

-v or --version
Display the gcov version number on the standard output, and then exit.

Description:

You can use the gcov utility to test code coverage in your programs. Gathering code-coverage data involves the following steps:

  1. Compiling and linking your program and libraries with the -fprofile-arcs and -ftest-coverage options to qcc. This step generates notes files with an extension of .gcno.
  2. Running your program, which creates counts files with an extension of .gcda.
  3. Using gcov to generate the code-coverage information from the counts file. This step generates data files with an extension of .gcov.

You can use the Code Coverage perspective in the Integrated Development Environment (IDE) to gather and visually interpret this information. For more information, see “Code Coverage” in the IDE User's Guide. For detailed documentation about gcov, see https://gcc.gnu.org/onlinedocs//gcc/Gcov.html#Gcov in the GCC documentation at https://gcc.gnu.org/.

When compiling for coverage on a host operating system such as Windows which can use a file path separator other than ' / ' (forward slash), the .gcda files when generated on a nto target may have unexpected naming. The directory name of the .gcda file in these instances may contain elements of the directory path structure on the compiling host. The nto file system will only recognize the forward slash as a file path separator.

A .gcda file could be created such as: 

c:\win_dir1\win_dir2/c_file.gcda

The generated directory name on the nto target would be c:\win_dir1\win_dir2 and GCOV_PREFIX_STRIP=1 with GCOV_PREFIX= would produce a file named c_file.gcda.

If you want to use lcov (which we don't provide) on a Linux host to view coverage data, configure it to work with our version of gcov by adding a line such as the following to your .lcovrc file: 

geninfo_gcov_tool=ntox86_64-gcov

Gathering data from the command line

If you want to gether code-coverage data from the command line, you may have to adjust some paths, because the tools create the gcda files based on the current working directory when the corresponding source file was compiled. For example:

  1. On your development host, compile and link your program: 
    qcc -fprofile-arcs -ftest-coverage -o my_program my_program.c -lm
  2. Transfer the binary to your target system.
  3. Run your binary, using the GCOV_PREFIX and GCOV_PREFIX_STRIP environment variables to send the output to the location that you want. GCOV_PREFIX_STRIP indicates how many directories to strip from the path, and GCOV_PREFIX specifies a prefix to add to the path. For example, to send the output to /tmp, run: 
    GCOV_PREFIX_STRIP=9990 GCOV_PREFIX=/tmp/ /tmp/my_program

    To send the output to your current directory, run: 

    GCOV_PREFIX_STRIP=9999 ./my_program
  4. Copy the *.gcda files back to the directory where you compiled the program on your development host.
  5. Run the appropriate variant of gcov, and then examine the results in the *.gcov files (my_program.c.gcov in this example).

Here's another example. Suppose you do the following: 

cd /build/my_project/objects
qcc -fprofile-arcs -ftest-coverage -c -o fileA.o ../source/fileA.c
qcc -fprofile-arcs -ftest-coverage -c -o fileB.o ../source/fileB.c
qcc -fprofile-arcs -ftest-coverage -c -o fileB.o ../source/fileC.c
cd /build/my_project/
qcc -fprofile-arcs -ftest-coverage -o my_program objects/fileA.o objects/fileB.o objects/fileC.o

and you transfer the binary to your target system, and then run your program. Let's examine how GCOV_PREFIX and GCOV_PREFIX_STRIP affect where the code-coverage files go:

Note: When you transfer the gcda files back to your development host, make sure to put them in the same directories as the corresponding gcno files.

For more information, see https://gcc.gnu.org/onlinedocs/gcc/Cross-profiling.html in the GNU documentation.

Exit status:

0
Success.
not 0
An error occurred.

Contributing author:

GNU

Related reference
g++, gcc
q++, qcc
Parent topic: G