To see some examples of |TOOL_NAME| generated HTML coverage reports::

    $ cp -r $|TOOL_NAME|_HOME/share/lcov/example .
    $ cd example
    $ make

Review the 'make' log and the generated
data, and then point a web browser into the resulting reports.

The example builds with GCC by default.
You will need to make a few changes if you want to use LLVM instead.


- Default view:

  - Point your browser to ``output/index.html``

- Hierarchical view:

  - Point your browser to ``hierarchical/index.html``

  - Note that that the coverage data is the same - only the report
    format is different:

    - Follows directory structure, similar to MS file viewer
      (``--hierarchical`` flag)

    - Additional navigation links also enabled
      (``--show-navigation`` flag)

- Differential coverage:

  - Point your browser to ``exampleRepo/differential/index.html``

  - This example is slightly complicated because it emulates a moderately
    realistic project in that it pretends to see project changes:

    - updates to two project source files ``example.c`` and ``iterate.c``

    - change to the test suite: only one test of updated
      code rather than 3 of the original code

    The Makefile simulates this by checking code into a git repo,
    building an executable and then updating a few source files, rebuilding,
    and running some tests.

- Code review:

  - point your browser to ``exampleRepo/review/index.html``

  - This example builds on the **Differential coverage** example, above
    to emulate a possible code review methodology in which adds code
    coverage to the review criteria.
    The intent is to generate a reduced report which shows only the
    code changes which negatively affect code coverage - while removing
    other details which only distract from the review.

    - Use the ``genhtml --select-script ...`` feature to show only new
      source code which was negatively affected by the change under
      review (uncovered and/or lost code).
      You might want to modify the select criteria to include positive
      change (*e.g.*, GNC, GBC, and GIC categories).

    - Real use cases are likely to use more sophisticated select-script
      callbacks (*e.g.*, to select from a range of changelists).

    - The example uses caching and profile history to improve runtime
      performance - see the man pages for a more detailed description
      of the features.  There is no effect with a tiny example - but
      a real project may see benefit.
      The ``spreadsheet.py`` application script can be used to convert
      JSON profile files into more readable excel spreadsheets.  This
      can be useful to see the effect (if any) of the caching and/or
      history features, and can show where time is spent for your example.
      This can be helpful, to suggest opportunities to optimize the |ToolName|
      implementation.

Feel free to edit the Makefile or to run the lcov utilities directly,
to see the effect of other options that you find in the lcov man pages.
