Gcovr User Guide
==================
:doctype: article

:cpp: {basebackend@docbook:c++:cpp}
:makefile: {basebackend@docbook:make:makefile}

:numbered!:
[abstract]
Abstract
--------

Gcovr provides a utility for managing the use of the GNU
http://gcc.gnu.org/onlinedocs/gcc/Gcov.html[gcov] utility and
generating summarized code coverage results. This command is inspired
by the Python  http://nedbatchelder.com/code/coverage/[coverage.py]
package, which provides a similar utility in Python. The +gcovr+
command produces either compact human-readable summary reports,
machine readable XML reports (in
http://cobertura.sourceforge.net/[Cobertura] format) or simple HTML
reports.  Thus, +gcovr+ can be viewed as a command-line alternative
to the http://ltp.sourceforge.net/coverage/lcov.php[lcov] utility,
which runs gcov and generates an HTML-formatted report.  This documentation describes
Gcovr 3.2.

:numbered:


Overview
--------

Gcovr is a Python package that includes a self-contained +gcovr+
command.  Gcovr is an extension of +gcov+, a GNU utility that
summarizes the lines of code that are executed - or "covered" -
while running an executable.  The +gcovr+ command interprets +gcov+
data files to summarize code coverage in sevearl formats:

* Text output with coverage statistics indicated with summary statistics and lists of uncovered line, and
* XML output that is compatible with the Cobertura code coverage utility.

////
* HTML output with coverage rates indicated using colored bar graphs.
////


The http://gcovr.com[Gcovr Home Page] is
http://gcovr.com[http://gcovr.com].  This webpage contains links
for documentation in
http://gcovr.com/guide.html[HTML],
http://gcovr.com/guide.pdf[PDF], and
http://gcovr.com/guide.epub[EPUB] formats.  The
http://gcovr.com[Gcovr Home Page] also includes developer
resources (e.g. https://software-login.sandia.gov/hudson/view/gcovr/[automated
test results]).  Gcovr is available under the
http://www.gnu.org/licenses/bsd.html[BSD]
license.

The Gcovr User Guide provides the following documentation:

 - <<gettingStarted,Getting Started>>: Some simple examples that illustrate how to use Gcovr
 - <<gcovrCommand,The +gcovr+ Command>>: Description of command-line options for +gcovr+
 - <<installation,Installation>>: How to install Gcovr
 - <<discussion,Status and Future Plans>>: Comments on the past, present and future of Gcovr


[[gettingStarted]]
Getting Started
---------------

The +gcovr+ command provides a summary of the lines that have been
executed in a program.  Code coverage statistics help you discover
untested parts of a program, which is particularly important when
assessing code quality.  Well-tested code is a characteristic of
high quality code, and software developers often assess code coverage
statistics when deciding if software is ready for a release.

The +gcovr+ command can be used to analyze programs compiled with
GCC.   The following sections illustrate the application of +gcovr+
to test coverage of the following program:
[source,{cpp},numbered]
----
include::examples/example1/example1.cpp[]
----
This code executes several subroutines in this program, but some lines in the program are not
executed.


Tabular Output of Code Coverage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We compile +example1.cpp+ with the GCC compiler as follows:
[source,bash]
----
include::examples/.example1_compile.sh[]
----
Note that we compile this program without optimization, because
optimization may combine lines of code and otherwise change the
flow of execution in the program.  Additionally, we compile with
the +-fprofile-arcs -ftest-coverage -fPIC+ compiler options, which
add logic to generate output files that can be processed by the
+gcov+ command.

The compiler generates the +program+ executable.  When we execute this command:
[source,bash]
----
include::examples/.example1_run.sh[]
----
the files +example1.gcno+ and +example1.gcda+ are generated.  These
files are processed with by +gcov+ to generate code coverage
statistics.  The +gcovr+ command calls +gcov+ and summarizes these
code coverage statistics in various formats.  For example:
[source,bash]
----
include::examples/.example1_gcovr.sh[]
----
generates a text summary of the lines executed:

----
include::examples/example1.txt[]
----
Each line of this output includes a summary for a given source file,
including the number of lines instrumented, the number of lines
executed, the percentage of lines executed, and a summary of the
line numbers that were not executed.  To improve clarity, gcovr
uses an aggressive approach to grouping uncovered lines and will
combine uncovered lines separated by "non-code" lines (blank,
freestanding braces, and single-line comments) into a single region.
As a result, the number of lines listed in the "Missing" list may
be greater than the difference of the "Lines" and "Exec" columns.

The +-r+ option specifies the root directory for the files that are
being analyzed.  This allows +gcovr+ to generate a simpler report
(without absolute path names), and it allows system header files
to be excluded from the analysis.

Note that +gcov+ accumulates statistics by line.  Consequently, it
works best with a programming style that places only one statement
on each line.  In +example1.cpp+, the +MACRO+ macro executes a
branch, but +gcov+ cannot discern which branch is executed.


Tabular Output of Branch Coverage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The +gcovr+ command can also summarize branch coverage using the +--branches+ option:
[source,bash]
----
include::examples/.example3_gcovr.sh[]
----
This generates a tabular output that summarizes the number of branches, the number of
branches taken and the branches that were not completely covered:

----
include::examples/example3.txt[]
----


XML Output
~~~~~~~~~~

The default output format for +gcovr+ is to generate a tabular
summary in plain text.  The +gcovr+ command can also generate an
XML output using the +--xml+ and +--xml-pretty+ options:
[source,bash]
----
include::examples/.example2_gcovr.sh[]
----
This generates an XML summary of the lines executed:

----
include::examples/example2.txt[]
----
This XML format is in the
http://cobertura.sourceforge.net/xml/coverage-03.dtd[Cobertura XML]
format suitable for import and display within the
http://www.jenkins-ci.org/[Jenkins] and http://www.hudson-ci.org/[Hudson]
continuous integration servers using the
https://wiki.jenkins-ci.org/display/JENKINS/Cobertura+Plugin[Cobertura
Plugin].

The +--xml+ option generates a denser XML output, and the +--xml-pretty+
option generates an indented XML output that is easier to read.
Note that the XML output contains more information than the tabular
summary.  The tabular summary shows the percentage of covered lines,
while the XML output includes branch statistics and the number of
times that each line was covered.  Consequently, XML output can be
used to support performance optimization in the same manner that
+gcov+ does.


HTML Output
~~~~~~~~~~~

The +gcovr+ command can also generate a simple
HTML output using the +--html+ option:
[source,bash]
----
include::examples/.example4_gcovr.sh[]
----
This generates a HTML summary of the lines executed.  In this
example, the file +example1.html+ is generated, which has the
following output:

image::examples/example1.png[align="center"]

The default behavior of the +--html+ option is to generate HTML for
a single webpage that summarizes the coverage for all files.  The
HTML is printed to standard output, but the +-o+ (+--output+) option
is used to specify a file that stores the HTML output.

The +--html-details+ option is used to create a separate web page
for each file.  Each of these web pages includes the contents of
file with annotations that summarize code coverage.  Consider the following
command:
[source,bash]
----
include::examples/.example5_gcovr.sh[]
----
This generates the following HTML page for the file +example1.cpp+:

image::examples/example2_example1_cpp.png[align="center"]

Note that the +--html-details+ option can only be used with the
+-o+ (+--output+) option.  For example, if the +--output+ option
specifies the output file +coverage.html+, then the web pages
generated for each file will have names of the form
+coverage.<filename>.html+.



[[gcovrCommand]]
The +gcovr+ Command
-----------------

The +gcovr+ command recursively searches a directory tree to find
+gcov+ coverage files, and generates a text summary of the code
coverage.  The +--help+ option generates the following summary of
the +gcovr+ command line options:

----
include::examples/gcovr.out[]
----
The following sections illustrate the use of these command line options.


////
WEH: This section needs to be added to explain the options that
specify where files are located.

Controlling Coverage
~~~~~~~~~~~~~~~~~~~~

TODO: document options that control where data files and gcov files
are found and filtering options for them.

////


[[installation]]
Installation
------------

Gcovr requires virtually no installation.  The +gcovr+ command can
be downloaded and used directly without installing additional files.

If you have
https://pip.pypa.io/en/latest/[pip]
installed, then
you can install +Gcovr+ from the PyPI network servers by executing
[source,bash]
----
pip install gcovr
----
This places the +gcovr+ executable in the +bin+ or +Scripts+ directory
for you python installation.

The +gcovr+ script has been tested with many different versions of
Python:  2.5 - 3.3.  Note that this script has only been tested
with the CPython implementation.



[[discussion]]
Status and Future Plans
-----------------------

The Gcovr 3.0 release is the first release that is hosted a GitHub.
Previous Gcovr development was hosted at Sandia National Laboratories
as part of the FAST project.  However, Gcovr is now widely used
outside of Sandia, and GitHub will facilitate the integration of
contributions from a wider set of developers.

:numbered!:

[[acknowledgements]]
Acknowledgements
----------------

The following developers contributed to the Gcovr 3.2 release:

* Sylvestre Ledru
* Kevin Cai
* Luke Woydziak
* Nikolaj Schumacher
* William Hart

The Gcovr documentation is generated using
http://www.methods.co.nz/asciidoc/[AsciiDoc].

We would like to thank the following organizations for providing
web hosting and computing resources: GitHub and Sandia National
Laboratories.  The development of Gcovr has been partially supported
by Sandia National Laboratories.  Sandia National Laboratories is
a multi-program laboratory managed and operated by Sandia Corporation,
a wholly owned subsidiary of Lockheed Martin Corporation, for the
U.S.  Department of Energy's National Nuclear Security Administration
under contract DE-AC04-94AL85000.


[appendix]
[[appendix_C]]
Testing Gcovr
---------------

In the +gcovr/tests+ directory, you can execute
[source,bash]
----
python test_gcovr.py
----
to launch all tests.  By default, this test script executes test suites
on a variety of code configurations that reflect different use-cases for
+gcovr+.

You can execute a specific test suite by giving its name as an
argument to this test script.  For example, the command
[source,bash]
----
python test_gcovr.py GcovrXml
----
executes the +GcovrXml+ test suite, which tests +gcovr+ with XML output.

To run the +test_gcovr.py+ script, you will need to install the
https://pypi.python.org/pypi/pyutilib.th[pyutilib.th] package.
If you have
https://pip.pypa.io/en/latest/[pip]
installed, then
you can install this package from PyPI by executing
[source,bash]
----
pip install pyutilib.th
----


// vim: ft=asciidoc
