Page MenuHomePhabricator

[docs] Document the source-based code coverage feature
ClosedPublic

Authored by vsk on May 26 2016, 6:02 PM.

Details

Summary

It would be helpful to have a user-friendly guide for code coverage. There is some overlap with [1], but this document visits issues which may affect users in more depth.

Prompted by: https://llvm.org/bugs/show_bug.cgi?id=27781

[1] http://llvm.org/docs/CoverageMappingFormat.html

Diff Detail

Repository
rL LLVM

Event Timeline

vsk updated this revision to Diff 58732.May 26 2016, 6:02 PM
vsk retitled this revision from to [docs] Document the source-based code coverage feature.
vsk updated this object.
vsk added a reviewer: bogner.
vsk added subscribers: kcc, cfe-commits, silvas.

This is looking really good. So based on reading this, a rough sketch of how we can expand this to PGO would be something like:

  • there is a separate PGO page that has similar structure, but is more tuned for the PGO use case.
  • there is a separate page (maybe in the LLVM docs and not clang since other frontends might be using libprofile?) which describes "advanced usage of the profile runtime". That would cover the file and buffer API, __llvm_profile_runtime, runtime counter resetting and merging, etc.

Adding Maggie and Phillip, which are working on coverage at PlayStation.

docs/SourceBasedCodeCoverage.rst
33 ↗(On Diff #58732)

Would it be possible to make these consistent with the later section headers?

61 ↗(On Diff #58732)

Since these are clang's docs, we should just say clang (or clang++)

91 ↗(On Diff #58732)

As a user, this would make me ask "why can't llvm-profdata do the indexing if I pass it a raw profile"?

I think the answer is largely that in a real program there are multiple profraws, so you need to merge them first. You probably want to mention that.

140 ↗(On Diff #58732)

Can you show example output? That is one of the most useful things in a how-to document like this. (for example, a person reading this might be a prospective user of the feature, and seeing the output is valuable to them to see if it provides what they want)

149 ↗(On Diff #58732)

Small wording nit: Instead of saying "It is possible for an instrumented program to..." I would say something like "Advanced use of the profile runtime library allows an instrumented program to..." or something like that.

vsk updated this revision to Diff 58810.May 27 2016, 11:00 AM
vsk marked 4 inline comments as done.

Thanks for the feedback!

  • Addressed Sean's review comments.
  • Fixed the line count displayed in the summary view of foo.
vsk updated this revision to Diff 59078.May 31 2016, 9:04 AM
vsk marked an inline comment as done.
  • Actually link in the new document into Index.rst.
This revision was automatically updated to reflect the committed changes.