.. _gcov parser:

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

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

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 descriped 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`_) 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: https://github.com/gcovr/gcovr/issues/583#issuecomment-1340762818
