ICT ALMA Common Software

Space shortcuts

Page tree

GCOV

GCOV is a tool you can use in conjunction with GCC to test code coverage in your programs.

Build

For building with coverage support you need to add some flags to gcc/g++ compiler and linker:

g++ -fprofile-arcs -ftest-coverage

#Or simply --coverage, which includes the previous flags
g++ --coverage

Using the ACS Makefile, you can take advantage of MAKE_GCOV environment variable:

#Build ACS
cd ACS
MAKE_GCOV=1 make build

#Build a single module
cd <some_module>/src
MAKE_GCOV=1 make clean all install

As a result, you will have a .gcno file for each compiled .o file in your object directory.

Execute

The execution is the same as always, you don't need to use a wrapper application or pass any special flag or environment variable. You can either run an executable manually or use an automated testing system such as TAT.

As a result you will get a .gcda file for each translation unit that was initialized during the execution of your executable(s). The file will be placed by default in the same directory where the corresponding .gcno and .o are. For some scenarios, you may need this to be placed in a different directory, and for this you have the GCOV_PREFIX and GCOV_PREFIX_STRIP environment variables.

These variables need to be set before running any executable, so the .gcda files are created according to them.

As an example we have built code from modules /home/almamgr/Repos/repo/mod1 and /home/almamgr/Repos/repo/mod2, and we want to analyze the .gcda data in /home/almamgr/gcov/data:

export GCOV_PREFIX_STRIP=3
export GCOV_PREFIX=/home/almamgr/gcov/data

#To automate the value for GCOV_PREFIX_STRIP, you could do something like this:
export GCOV_PREFIX_STRIP=$(echo /home/almamgr/Repos/repo |grep -o / |wc -l)

In this case, the .gcda files will be found in /home/almamgr/Repos/repo/mod1/object and /home/almamgr/Repos/repo/mod2/object directories.

Coverage

At this point we have the raw data .gcno and .gcda to generate the coverage information, and here there are a couple of alternatives:

  • gcov
  • gcovr
  • lcov
  • etc.

For the flexibility and ease of use, we decided to go with lcov, which is a frontend for gcov, offering the generation of coverage information without the need for source files and also adding reporting utilities.

For using lcov, go to the base directory you want to analyze for coverage and then execute:

lcov --capture --exclude "/usr/include/*" --exclude "$ALMASW_INSTDIR/TAO/*" -d . --output-file coverage.info

You may need to exclude further paths. In the case of doing coverage for ACS, you may want to only include $ALMASW_INSTDIR/ACSSW:

lcov --capture --include "$PWD/*" --include "$ACSROOT/*" -d . --output-file coverage.info

But in a project scenario, maybe only the $INTROOT or a set of $INTROOTs in an $INTLIST may be more useful. Remember to always include the directory where the .gcno and .gcda files are. In the case above that was achieved by including $PWD directory.

One more thing to notice is that the coverage.info will consider the full path for your files in $PWD, so it may make sense to fix this to have a nice report later:

sed -i "s|$PWD/||g" coverage.info

Report

The simplest report is to retrieve a summary from lcov:

lcov --summary coverage.info
Reading tracefile coverage.info
Summary coverage rate:
  lines......: 14.0% (1659 of 11863 lines)
  functions..: 6.4% (169 of 2622 functions)
  branches...: no data found

A more detailed report can be obtained by listing all files and the coverage of each one with -l or --list:

lcov -l coverage.info

The output will be something like this:

Reading tracefile coverage.info
                                               |Lines      |Functions|Branches  
Filename                                       |Rate    Num|Rate  Num|Rate   Num
================================================================================
[/alma/ACS-2023APR/ACSSW/include/]
ACSErrTypeCommon.h                             | 0.0%    23|    -   0|    -    0
ACSErrTypeCommonC.h                            | 0.0%     1| 0.0%   2|    -    0
acsThread.h                                    |66.7%     3|66.7%   3|    -    0
acsThreadBase.h                                |90.9%    22|75.0%   4|    -    0
acsThreadManager.h                             |90.9%    11|50.0%   4|    -    0
...

[/home/almamgr/gcov/src/ACS/LGPL/CommonSoftware/]
bulkDataNT/include/bulkDataNT.h                | 0.0%     1|    -   0|    -    0
bulkDataNT/include/bulkDataNTCallback.h        |85.7%    14|22.2%   9|    -    0
...
================================================================================
                                         Total:|14.0% 11863| 6.4%  2k|    -    0

Finally, it also includes the genhtml utility which can generate an html report:

genhtml -o report coverage.info

#If sources are not available
genhtml -o report --no-source coverage.info

Example

Pending

  • No labels