.. program is needed to resolve :option: references
.. program:: gcovr

.. _gcov parser:

GCOV parser
===========

GCOV json output
^^^^^^^^^^^^^^^^

Starting with ``gcc-14`` the ``gcov`` tool can generate a zipped JSON representation of the coverage data.
Only version 2 of the intermediate format is supported. The version generated by your installation can be
checked with the command ``gcov --version``.

If an unsupported version is generated ``gcovr`` is falling back to the :ref:`GCOV text output`.

.. _GCOV text output:

GCOV text output
^^^^^^^^^^^^^^^^

Until ``gcc-13`` or if the json output format is unsupported the ``gcov`` text output is parsed.
The behavior of this parser was informed by the following sources:

* the old GcovParser class
  <https://github.com/gcovr/gcovr/blob/e0b7afef00123b7b6ce4f487a1c4cc9fc60528bc/gcovr/gcov.py#L239>
* the *Invoking Gcov* section in the GCC manual (version 11)
  <https://gcc.gnu.org/onlinedocs/gcc-11.1.0/gcc/Invoking-Gcov.html>
* the ``gcov.c`` source code in GCC
  (especially for understanding the exact number format)
  <https://github.com/gcc-mirror/gcc/blob/releases/gcc-11.1.0/gcc/gcov.c>

Error handling
--------------

By default the parser raises an exception on unrecognized gcov output.

There are several known issues with the files generated by gcov which can be
handled by :option:`--gcov-ignore-parse-errors` which are described here. If
no value is given to the option the value ``all`` is used the whole gcov file
is ignored if the output is not recognized.

Negative hit counts
___________________

A bug in gcov can produce negative hit values (see `gcov comment_negative_hits`_) which are not accepted by default.
This behavior can be changed by using the value ``--gcov-ignore-parse-errors=negative_hits.warn`` or
``--gcov-ignore-parse-errors=negative_hits.warn_once_per_file``. The first form warns on every line
with a negative value the second one only once per processed file and adds a summary with the overall
issues in the file.

.. _gcov comment_negative_hits: https://github.com/gcovr/gcovr/issues/583#issuecomment-1340762818

Suspicious hit counts
_____________________

A bug in gcov can produce very high hit values (see `gcov issue_suspicious_hits`_) which are not accepted by default.
A suspicious value is assumed if the counter is greater than the value of :option:`--gcov-suspicious-hits-threshold`.
This behavior can be changed by using the value ``--gcov-ignore-parse-errors=suspicious_hits.warn`` or
``--gcov-ignore-parse-errors=suspicious_hits.warn_once_per_file``. The first form warns on every line
with a suspicious value the second one only once per processed file and adds a summary with the overall
issues in the file.

.. versionadded:: 8.3

    The threshold for detection of suspicious hits can be configured with :option:`--gcov-suspicious-hits-threshold`.

.. _gcov issue_suspicious_hits: https://github.com/gcovr/gcovr/issues/898