Document the process of generating code coverage

Update the script to check coverage generation is enabled, and provide a sensible error message if it is not.

Change-Id: I42f2b97d18bb3be2d081200cb682ea310476943f
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/70520
Kokoro: Kokoro <noreply+kokoro@google.com>
Commit-Queue: Ben Clayton <bclayton@chromium.org>
Reviewed-by: David Neto <dneto@google.com>
This commit is contained in:
Ben Clayton 2021-11-23 17:57:37 +00:00 committed by Tint LUCI CQ
parent e85efca13f
commit 5af571bcbc
2 changed files with 39 additions and 2 deletions

24
docs/coverage-info.md Normal file
View File

@ -0,0 +1,24 @@
# Generating and viewing Tint code-coverage
Requirements:
* Host running Linux or macOS
* Clang toolchain on the `PATH` environment variable
## Building Tint with coverage generation enabled
Follow the steps [to build Tint with CMake](../README.md), but include the additional `-DTINT_EMIT_COVERAGE=1` CMake flag.
## Generate coverage information
Use the `<tint>/tools/tint-generate-coverage` script to run the tint executable or unit tests and generate the coverage information.
The script takes the executable to invoke as the first command line argument, followed by additional arguments to pass to the executable.
For example, to see the code coverage for all unit tests, run:
`<tint>/tools/tint-generate-coverage <build>/tint_unittests --gtest_brief`
The script will emit two files at the root of the tint directory:
* `coverage.summary` - A text file giving a coverage summary for all Tint source files.
* `lcov.info` - A binary coverage file that can be consumed with the [VSCode Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) extension.

View File

@ -44,9 +44,22 @@ PROFDATA_FILE="${ROOT_DIR}/tint.profdata"
LCOV_FILE="${ROOT_DIR}/lcov.info"
SUMMARY_FILE="${ROOT_DIR}/coverage.summary"
# Remove any existing coverage data and intermediate files
if [ -f "$PROFRAW_FILE" ]; then rm ${PROFRAW_FILE}; fi
if [ -f "$PROFDATA_FILE" ]; then rm ${PROFDATA_FILE}; fi
if [ -f "$LCOV_FILE" ]; then rm ${LCOV_FILE}; fi
if [ -f "$SUMMARY_FILE" ]; then rm ${SUMMARY_FILE}; fi
# Run the executable to generate the raw coverage data
# https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#running-the-instrumented-program
LLVM_PROFILE_FILE="${PROFRAW_FILE}" $@
LLVM_PROFILE_FILE="${PROFRAW_FILE}" "$@"
# Check that coverage information was generated
if [ ! -f "$PROFRAW_FILE" ]; then
echo "lcov.info was not generated. Is coverage generation enabled?"
echo "To enable, run cmake with -DTINT_EMIT_COVERAGE=1".
exit 1
fi
# Fail on any error after running the target executable
set -e
@ -62,5 +75,5 @@ llvm-cov export --instr-profile="${PROFDATA_FILE}" --format=lcov --object=${TARG
# Generate summary report
llvm-cov report --ignore-filename-regex="(.*_test\.cc|third_party/.*)" --instr-profile="${PROFDATA_FILE}" --object=${TARGET_EXE} > "${SUMMARY_FILE}"
# Clean up
# Clean up intermediate files
rm ${PROFRAW_FILE} ${PROFDATA_FILE}