Izzy's eXtension Modules

Appearance

Source-based Code Coverage ​

For more information on the LLVM source-based code coverage implementation, see its documentation page. This component is considered missing if the Required targets in IMPORTED Targets cannot be found.

Targets ​

The following IMPORTED targets are created when the LLVM component is required.

Coverage::LLVM
Provides LLVM's source based code coverage compiler and linker options
This target is available if the C or C++ compiler supports the -fcoverage-mapping compiler flag and the -fprofile-instr-generate linker flag.
Type: LIBRARY
Required: YES
Coverage::LLVM::ProfileData
The llvm-profdata executable
Type: PROGRAM
Required: YES
Coverage::LLVM::Tool
The llvm-cov executable
Type: PROGRAM
Required: YES
Coverage::LLVM::C++Filter
The llvm-cxxfilter executable.
Type: PROGRAM

TIP

Sadly, not all distributions of Clang are made equal. The Windows installer provided by the LLVM project does not install llvm-cxxfilter. However the tarball distribution it provides does. If the filtering of symbols when viewing code coverage on Windows is important, ensure that this tool is installed.

Commands ​

add_llvm_coverage ​

This creates a target that can be referred to directly with set_property and, when built, will collate the raw profile data (.profraw files) from executed tests into a .profdata, and then convert them into a format defined by the user.

NOTE

This command uses add_custom_target internally, which does not permit creating alias targets, nor does it permit creating "scoped" targets (e.g., ${PROJECT_NAME}::coverage). As a result, all targets passed to this command must be globally unique.

Required Parameters ​

name
name of the target to create

Keyword Parameters ​

ALL
Add this target to the all target's dependencies.
EXPORT
Where to output the exported coverage information.
By default, this is set to ${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.lcov.info.
OUTPUT
Where to output the .profdata file.
By default, this is set to ${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.profdata.
GITHUB
Name of the GitHub Actions output parameter to writ the final EXPORT value to.
By default, this is the value passed to name.
No actions are taken if not under GitHub Actions.
TARGETS
A list of targets to filter source files from.
IGNORE_FILENAME_REGEX
Skip source code files with file paths that match the given regular expressions.

Example ​

cmake
add_llvm_coverage(coverage
  TARGETS ${PROJECT_NAME}
  IGNORE_FILENAME_REGEX
    $<PATH:RELATIVE_PATH,${FETCHCONTENT_BASE_DIR},${CMAKE_BINARY_DIR}>
    $<PATH:RELATIVE_PATH,${CMAKE_CURRENT_SOURCE_DIR},${PROJECT_SOURCE_DIR}>)
foreach (test IN LISTS tests)
  add_executable(${test} ${test}.cpp)
  target_link_libraries(${test} PRIVATE Coverage::LLVM)
  # Set properties to work with `coverage` target.
  set_target_properties(${test}
    PROPERTIES
      ADDITIONAL_CLEAN_FILES $<GENEX_EVAL:$<TARGET_PROPERTY:LLVM_PROFILE_FILE>>
      LLVM_PROFILE_FILE ${PROJECT_BINARY_DIR}/$<CONFIG>/${PROJECT_NAME}-${test}.profraw
      LLVM_COVERAGE_PREFIX_MAP ${PROJECT_SOURCE_DIR}=.)
  add_test(NAME ${PROJECT_NAME}::${test} COMMAND ${test})
  set_property(TARGET coverage APPEND
    PROPERTY
      LLVM_PROFRAW_SOURCES $<GENEX_EVAL:$<TARGET_PROPERTY:${test},LLVM_PROFILE_FILE>>)
endforeach()

Properties ​

Some properties need to be mentioned directly on targets that will link against a given target, others are specifically for a coverage target.

LLVM_MODIFIED_CONDITION_DECISION_COVERAGE
Pass -fcoverage-mcdc to the compiler
Type: boolean
Scopes: TARGET
Default: <empty>
LLVM_COVERAGE_PREFIX_MAP
Remap file source paths <old> to <new> in coverage mapping. If there are multiple options, prefix replacement is applied in reverse order starting from the last one
Type: list
Default: <empty>
LLVM_PROFRAW_SOURCES
TODO
LLVM_TEST_EXECUTABLES
TODO
LLVM_IGNORE_FILENAME_REGEX
TODO
LLVM_PROFILE_FILENAME
TODO
LLVM_MERGE_FAILURE_MODE
llvm-profdata's failure mode when merging .profraw files into a .profdata file.
Type: enum
Values: warn, any, all
Default: any
LLVM_SOURCES
Source files to be read from when exporting coverage information.
Type: list
Scope: TARGET
Default: $<TARGET_PROPERTY:SOURCES>

© Izzy Muerte