Add configuration options for LCOV markers

[ImmanuelHaffner]

The LCOV_*_START and LCOV_*_STOP markers were hard-coded in bin/geninfo. It was not possible to override them, e.g. in lcovrc. This commit does not alter the default character sequences for these markers, but extends reading the configuration to allow for overriding a marker's character sequence. The man page for lcovrc is updated accordingly.

I have the following motivation for this patch: When the code is shipped to users, they need not know what coverage tool we use nor how the tool is configured. Switching from one tool for coverage to another should require as few changes as possible. Markers should integrate nicely with the project's coding style. Code segments like

/* LCOV_EXCL_START */
void foo()
{
    ...
}
/* LCOV_EXCL_STOP */

may confuse users and are error prone, as someone may believe a comment is superfluous and delete it.

It is common practice for libraries shipping macros to prefix them, e.g. library Xyz may define a macro as

#define XYZ_MY_MACRO ...

Following this idiom, this patch allows for defining in lcovrc

lcov_excl_start = XYZ_EXCLUDE_FROM_COVERAGE_BEGIN
lcov_excl_stop  = XYZ_EXCLUDE_FROM_COVERAGE_END

and somewhere in the project one can define

#define XYZ_EXCLUDE_FROM_COVERAGE_BEGIN
#define XYZ_EXCLUDE_FROM_COVERAGE_END

With this, excluding foo() from coverage looks like

XYZ_EXCLUDE_FROM_COVERAGE_BEGIN
void foo()
{
    ...
}
XYZ_EXCLUDE_FROM_COVERAGE_END

I believe that this expresses intent nicely and aligns well with common practice.

[GitMensch]

Thank you, that's a nice addition for lcov 1.17, @oberpar what do you think?

[henry2cox]

Hi - This is pretty easy to implement the requested functionality after the recent refactoring...but the refactoring means that current PR needs some rewriting to be able to be applied (sorry about that).

1. near line .../lib/lcovutil.pm:842, you need to add hash entries for config file parameters 'lcov_excl_start', 'lcov_excl_end', etc - pointing them to the corresponding $lcovutil::EXCL_START, $lcovutil::EXCL_STOP, etc variables. The rc_common hash is shared by geninfo, lcov, and genhtml - so the override will be honored by all the tools.
2. edit the lcovrc file to include (commented out) sample override usage
3. (ideally) add a testcasse to check that the overrides are doing what we hope. The common usage is probably to apply exclusions in in the lcov --capture ... command - so that is an obvious testcase.

Henry

[ImmanuelHaffner]

Oh man... this PR is one and a half years old by now. I may or may not give it another attempt to get this merged. Not in the near future, though, as I am very busy rn.

FWIW: Is this even the right place to file a PR? Or are you guys just mirroring to GitHub?

[henry2cox]

FWIW: Is this even the right place to file a PR? Or are you guys just mirroring to GitHub?

this is the right place.

The feature itself is 6 lines. The man page entry is another 30 or so. Tests may be a lot (but would use mostly generic and tested infrastructure). Not zero work (for anybody).

Feature will not be in the next lcov release unless it is done quite soon.

[henry2cox]

went ahead and did this myself

[ImmanuelHaffner]

It's appreciated, thanks!