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 |
ntox86-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:
- 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.
- Running your program, which creates counts files with an extension of .gcda.
- 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/.
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:
- On your development host, compile and link your program:
qcc -fprofile-arcs -ftest-coverage -o my_program my_program.c -lm
- Transfer the binary to your target system.
- 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
- Copy the *.gcda files back to the directory where you compiled the program
on your development host.
- 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:
- By default, my_program it attempts to create the gcda
files based on current working directory when the corresponding source file was compiled:
- /build/my_program/objects/fileA.gcda
- /build/my_program/objects/fileB.gcda
- /build/my_program/objects/fileC.gcda
- If you set GCOV_PREFIX=/tmp, the default paths are prefixed with /tmp:
- /tmp/build/my_program/objects/fileA.gcda
- /tmp/build/my_program/objects/fileB.gcda
- /tmp/build/my_program/objects/fileC.gcda
- Setting GCOV_PREFIX_STRIP=2 strips two prefixes from the default paths:
- /objects/fileA.gcda
- /objects/fileB.gcda
- /objects/fileC.gcda
- Setting GCOV_PREFIX=/tmp GCOV_PREFIX_STRIP=3 strips three prefixes from the default path first,
and then applies the new prefix of /tmp:
- /tmp/fileA.gcda
- /tmp/fileB.gcda
- /tmp/fileC.gcda
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.