What if I am using clang/llvm rather than gcc?

[henry2cox]

There have been a couple of recent llvm-related issues and/or questions - so maybe it is a good time to mention a few points.

If you are using clang/llvm, then there are a least two coverage use models which are supported by the tools.
(The description below uses elipsis (...) to stand in for other options and flags that you need to pass to the various tools.)

1. gcov model: LLVM can generate gcov-format data - just like gcc

   • clang --coverage -o myfile.o -c myfile.c ... # pass --coverage flag to instrument during compilation
     clang --coverage -o myexe myfile.o myotherfile.o ... # pass --coverage to link coverage-enabled executable
     (you can link both coverage-instrumented and non-instrumented code into the same executable. In that case: you will get coverage data only for the instrumented files.

   • ./myexe ... # run tests and generate coverage data
     You can use GCOV_PREFIX and GCOV_PREFIX_STRIP to write the runtime data to some non-default location

   • use llvm-cov gcov myfile.gcda ... to extract gcov format data from the .gcda/.gcno files for your code.
     Note that this is exactly the same thing that you would do for gcc via gcov myfile.gcda ... - except that you are using the llvm toolchain component llvm-cov.

     • it turns out that the llvm-generated .gcno and .gcda data is in the gcov format that was supported by gcc/4.X (at least as of llvm-15).
       If you like living dangerously, then you can use a gcc/4.X version of gcov rather than llvm-cov to process your data. This will very likely work.

   • you can tell lcov (or geninfo) to use llvm-cov using the --gcov-tool flag to pass the name of the executable ("llvm-cov") and the options ("gcov"):

     • lcov --capture -o mydata.info -d . --gcov-tool llvm-cov --gcov-tool gcov ....
       Note that --gcov-tool appears twice: once to name the tool, once to pass a tool option. See the lcov man page for more information.

   • At this point: you have an lcov-format .info file - and can proceed to generate a HTML report, merge it with other data, or whatever.

2. llvm profile model: use LLVM profile data directly:

   • clang -fprofile-instr-generate -fcoverage-mapping -o myfile.o -c myfile.c ...
clang -fprofile-instr-generate -fcoverage-mapping -o myexe myfile.o myotherfile.o ....

   • ./myexe ... # run tests and generate coverage data
     You can use LLVM_PROFILE_FILE to write runtime data to some non-default location.

   • llvm-profdata merge -sparse *.profraw -o mydata.profdata # transform .profraw files.

   • llvm-cov export -format=lcov --instr-profile mydata.profdata myexe > mydata.info # generate lcov format directly

     • to capture coverage data from more than one executable :
       llvm-cov export -format=lcov --instr-profile mydata.profdata myexe1 --object myext2 --object ... > myCombinedData.info
       Or capture data for each executable, then aggregate.
     • at this point, you have an lcov-format .info file - and can proceed as usual.
     • NOTE: older versions of LLVM do not support branch coverage.
       • The support was checked in in in SHA 9f2967bcfe2f7d1fc02281f0098306c90c2c10a5 in January 2021 (likely LLVM/12.X), with bug fix 9116211d180ca417fa93d4e97e60f4ba849d58d9 in August (likely LLVM/13.X).
         If your LLVM is older than that - then there will be no branch information in the generated .info file
       • If branch coverage is important to you, you will need to either upgrade to a newer LLVM release or use the gcov model described above.

   • the llvm profile use model is described more fully here.

3. Modified Condition / Decision Coverage with LLVM (MC/DC metrics):

   • MC/DC is supported in LLVM/18 and newer (or gcc/14.2 and newer).
   • LLVM's presentation/interpretation of MC/DC is different than gcc's. See man genhtml for details, and see the examples in .../tests/lcov/mcdc.
   • To capture MC/DC data from LLVM, you need to use the llvm2lcov translator, and need to follow the use model described here (and/or see llvm2lcov --help).
     Note that neither the 'gcov model' nor the 'profile model' described above support MC/DC metrics.

I hope that someone finds this useful.
Henry

PS: interesting experiment: generate a coverage report for your project using GCC - then generate another using LLVM. Compare them (differential report).

[henry2cox]

If branch coverage is important to you - note that I just corrected the llvm-profdata discussion, above. (Thank you, Alan Phipps)

[henry2cox]

I should also mention that the LLVM-profile use model seems to produce some other odd artifacts when writing an LCOV-format output file (llvm-cov export -format=lcov ...):

• sometimes, 'line' coverpoints get put on blank lines, lines which contain only a compiler directive (say #include "foo.h"), etc.

For these cases, see --filter blank and --filter directive - as well as --omit regexp if there are other common patterns in the coverage artifacts.