split lcov and genhtml cmake opts for the Coverage profile

[tevio]

Summary

Introduce HTML_OPTS for genhtml with a sensible default: inherit LCOV_OPTS when HTML_OPTS is not provided. This removes duplication for shared settings while keeping a clear escape hatch for genhtml-specific control.

Background (previous behavior)

• The HTML report generator (genhtml) always received LCOV_OPTS.
• This worked well for shared runtime config (notably --rc flags like branch_coverage=1) but made it awkward to pass options that apply only to genhtml.

What’s changing

• Add a dedicated variable, HTML_OPTS, for genhtml.
• Default behavior: if HTML_OPTS is omitted, pass LCOV_OPTS to genhtml (maintains the historical behavior and keeps shared config in sync).
• Override behavior: if HTML_OPTS is provided, use it instead of LCOV_OPTS for genhtml.
• Empty override: if HTML_OPTS is explicitly set to an empty string, pass no extra options to genhtml and do not inherit LCOV_OPTS.

Why this change

• lcov and genhtml are separate tools with partially overlapping options.
• Many useful settings are shared (e.g., --rc), but some are genhtml-only (e.g., --title).
• This change avoids duplicating shared options while enabling precise control of genhtml when needed.

User-facing behavior

• Omitted: genhtml receives LCOV_OPTS automatically.
• Provided: genhtml receives HTML_OPTS instead of LCOV_OPTS.
• Explicitly empty: genhtml receives no options; nothing is inherited.

Examples

# Single place to enable branch coverage (LCOV 2.x) for both tools
cmake -DLCOV_OPTS="--rc branch_coverage=1" -P build/Coverage.cmake

# genhtml-only customization (does not affect lcov)
cmake -DHTML_OPTS="--title 'Knots Coverage'" -P build/Coverage.cmake

# Intentionally pass no genhtml options (do not inherit LCOV_OPTS)
cmake -DHTML_OPTS="" -P build/Coverage.cmake

Implementation notes

• In cmake/script/CoverageInclude.cmake.in:
  • Detect whether HTML_OPTS was defined (even if empty) before splitting.
  • Set GENHTML_OPTS to HTML_OPTS when defined; otherwise fall back to LCOV_OPTS.
  • Build GENHTML_COMMAND with GENHTML_OPTS.

Key snippet:

# HTML_OPTS is optionally passed via -D flag.
# If HTML_OPTS is not provided at all, implicitly pass LCOV_OPTS to genhtml.
# If HTML_OPTS is provided but empty (e.g. -DHTML_OPTS=""), use an empty list
# and do NOT inherit LCOV_OPTS.
set(_HTML_OPTS_WAS_DEFINED FALSE)
if(DEFINED HTML_OPTS)
  set(_HTML_OPTS_WAS_DEFINED TRUE)
endif()
separate_arguments(HTML_OPTS)
if(_HTML_OPTS_WAS_DEFINED)
  set(GENHTML_OPTS ${HTML_OPTS})
else()
  set(GENHTML_OPTS ${LCOV_OPTS})
endif()
set(GENHTML_COMMAND ${GENHTML_EXECUTABLE} --show-details ${GENHTML_OPTS})

Backward compatibility

• Matches historical default: when HTML_OPTS is omitted, genhtml still receives LCOV_OPTS.
• Existing setups that already provided HTML_OPTS continue to behave as before.
• Adds a new, explicit way to pass no genhtml options via -DHTML_OPTS="".

Documentation

• Updated doc/developer-notes.md to describe the default inheritance, the explicit override, and the empty override, with examples using a genhtml-only flag (--title).

Impact and risk

• Low risk, confined to coverage tooling. Improves consistency for shared settings while enabling genhtml-specific customization and intentional minimalism.

[kwsantiago]

I recommend moving lines 5-17 to after the find_program() calls (after line 40) to ensure variables exist before use.

[kwsantiago]

Previously genhtml incorrectly received LCOV_OPTS

Now that they are properly separated, you may want to document the behavior change to confirm no one was relying on passing genhtml options via LCOV_OPTS

Also may want to rename HTML_OPTS to GENHTML_OPTS throughout for consistency and clarity.

[tevio]

Previously genhtml incorrectly received LCOV_OPTS

Now that they are properly separated, you may want to document the behavior change to confirm no one was relying on passing genhtml options via LCOV_OPTS

Also may want to rename HTML_OPTS to GENHTML_OPTS throughout for consistency and clarity.

hi @kwsantiago yes I was thinking about that yesterday in the point you make about confirming no one was relying on passing LCOV_OPTS - haven't tried it yet but could solve it by falling back to LCOV_OPTS by default and then only overriding with HTML_OPTS if it's passed and that way no ones existing setups would be affected

[kwsantiago]

Have you tested this?

From my understanding, --exclude boost is a lcov option not a genhtml option, so this example will fail.

[tevio]

it is an option for both lcov and genhtml - so I've used it as a reference, certainly tested it to filter out the boost entries in the coverage report, however, because there is currently no genhtml distribution in homebrew you need to install a custom binary which may or may not support the same options. In my case the version I'm using doesn't support the same options.

[tevio]

might be better to provide a reference in the docs for a compatible genhtml implementation that would officially "work" on macOs/windows (if it exists) that would render this OPTS overriding change irrelevant, but I don't know what that is or would look like currently