The Clang code coverage wrapper (//build/toolchain/clang_code_coverage_wrapper.py) is a compiler wrapper that adds code coverage flags to the invocations of Clang C/C++ compiler, which can be used to instrument and generate code coverage data for a subset of the source files. The main use case of this wrapper is to generate code coverage reports for changed files at a per-CL level during try jobs.
One might ask: why this compiler wrapper instead of just instrumenting all the source files?
Efficiency is the main consideration because comparing to instrument everything,
only instrument what-is-needed takes less time to build the test targets,
produces binaries that are 10 times smaller, run tests twice faster and
generates coverage reports significantly faster. An experiment was done to
evaluate the effectiveness of instrument what-is-needed, and in the experiment,
unit_tests is used as the sample test target and 8 randomly chosen C++ source
files are used as the samples files to instrument. The results are presented in
the following table:
| Type | Build time | Binary size | Tests run time | Reports generation time |
|---|---|---|---|---|
| No instrumentation | 43m | 240M | 40s | 0s |
| What-is-needed | 43m | 241M | 40s | 0.14s |
| Everything | 53m | 2.3G | 80s | 1m10s |
It can be seen from the results that the overhead introduced by instrument everything is huge, while it's negligible for instrument what-is-needed.
To get the coverage wrapper hook into your build, add the following flags to
your args.gn file, assuming build directory is out/Release.
use_clang_coverage = true
coverage_instrumentation_input_file = "//out/Release/coverage_instrumentation_input.txt"
The path to the coverage instrumentation input file should be a source root
absolute path, and the file consists of multiple lines where each line
represents a path to a source file, and the specified paths must be relative to
the root build directory. e.g. ../../base/task/post_task.cc for build
directory out/Release.
Then, use the //tools/code_coverage/coverage.py script to build, run tests and generate code coverage reports for the exercised files.
One caveat with this compiler wrapper is that it may introduce unexpected behaviors in incremental builds when the file path to the coverage instrumentation input file changes between consecutive runs, and the reason is that the coverage instrumentation input file is explicitly passed to the coverage wrapper as a command-line argument, which makes the path part of the Ninja commands used to compile the source files, so change of the path between consecutive runs causes Ninja to perform a full rebuild.
Due to the reasons mentioned above, users of this script are strongly advised to
always use the same path such as
${root_build_dir}/coverage_instrumentation_input.txt.
For more background information on how code coverage works in Chromium, please refer to code_coverage.md
We're still evaluating the tools, for any breakage report and feature requests, please file a bug.
For questions and general discussions, please join code-coverage group.