LCOVRC(5)

📦

version 2.6 · 14 versions

💖 LCOVRC(5) — the lcovrc manual page, but make it make sense 💖

okay bestie, this is the lcovrc page from the LCOV manual (section 5, group LCOV Configuration) and we're gonna get through it together, no cap. it's giving "configuration file lore" and honestly? kind of iconic. 💅

🌸 NAME 🌸

lcovrc — lcovrc documentation. literally what it says on the tin. ✨

Manual section: 5
Manual group: LCOV Configuration

🌸 NAME 🌸 (yes, again — the manpage said it twice, so we're doing it twice 🎀)

lcovrc is the configuration file for LCOV tools containing default options and settings. it's the little home where all your defaults live. 🏠💖

🦋 DESCRIPTION 🦋

The lcovrc file contains configuration information for the lcov code coverage tool — peep lcov(1) if you wanna meet the whole family. 🌈

The system-wide configuration file is located at $|TOOL_NAME|_HOME/etc/lcovrc. This is typically either /etc/lcovrc or /usr/local/etc/lcovrc but may be wherever you have installed the lcov package. To change settings for a single user, place a customized copy of this file at location ~/.lcovrc. Where available, command-line options override configuration file settings. periodt. 💅

The genhtml, lcov, and geninfo commands also support the --config-file option, which can be used to specify one or more files which should be used instead of the system or user default rc files. Multiple options files may be useful if you have both project- and team-specific common options and want to ensure consistency across multiple users. If you pass multiple --config-file options, they get applied in the order they appear. Note that the --config-file option name must be specified in full and cannot be abbreviated. An error will occur if the option is not recognized. so don't try to be cute with abbreviations, bestie — it will not slay. 😭

Lines in a configuration file can either be:

empty lines or lines consisting only of white space characters. These lines are ignored.
comment lines which start with a hash sign (#). These are treated like empty lines and will be ignored.
statements in the form key = value.
Values may be taken from environment variables via the syntax key = … $ENV{ENV_VAR_NAME} ….
- The substring $ENV{ENV_VAR_NAME} is replaced by the value of the environment variable.
- One or more environment variables may be used to set the RC value. key is ignored if any of the environment variables are not set in your user environment.

A list of valid statements and their description can be found in section ‘OPTIONS’ below. yes, that's later, and yes, it's a lot. we'll get there. 🫶

NOTE, bestie: there is no error checking of keys in the options file — spelling errors are simply seen as values which are not used by some particular tool. If you are unsure of whether your options file is read or its values applied, you can use the --verbose --verbose flag to enable printing of option value overrides. (The option appears twice to enable a higher level of verbosity.) so if your config is acting sus, double verbose is the vibe check. 🔍✨

Both ‘list’ and ‘scalar’ (non list) options are supported in the lcovrc file.

For scalar (non list) options:

if specified on the command line and in the lcovrc file, the value specified on the command line wins. The value from the RC file is ignored.
Scalar options include: criteria_script = …, genhtml_annotate_script = …, version_script = …, etc.

For list options:

the RC file entry can be used multiple times; each use appends to the list. For example, the entry below will result in two omit patterns which will both be checked:

# note explicit start/end line markers in the regexp
omit_lines = ^\\s+//\\s*MY_EXCLUDE_MARKER\\s*$
# Note that the regexp below matches anywhere on the line
omit_lines = NR_CM_DBG_PRINT

If entries are specified on the command line, then the RC file entries are ignored: command line wins. If entries are specified in more than one RC file (i.e., multiple --config-file arguments are supplied), then RC files are applied in order of appearance, and list entries are appended in order. For most list-type options, order is not important.
list options include:

filter = ...
exclude = ...
ignore = ...
substitute = ...
omit_lines = ...
erase_functions = ...
genhtml_annotate_script = ...

etc. For a complete set of list options, see the documentation of each configuration option, below. there are more, bestie, don't worry. 🧚

Example configuration:

Note that this example does not include all possible configuration options. In general: (almost) all command line options can be specified in the configuration file instead, whereas some configuration file options have no command line equivalent.

See the OPTIONS section below for details. 👑

#
# Example |ToolName| configuration file
#
# include some other config file
#   e.g, user-specific options.  Note the environment variable expansion
# config_file = $ENV{HOME}/.user_lcovrc
#   or project specific - hard-coded from environment variable
# config_file = /path/to/myproject/.lcovrc
#   or in the current run directory
# config_file = $ENV{PWD}/.lcovrc

# External style sheet file
#genhtml_css_file = gcov.css

# Use 'dark' mode display (light foreground/dark background)
# rather than default
#genhtml_dark_mode = 1

# Alternate header text to use at top of each page
#genhtml_header = Coverage report for my project

# Alternate footer text to use at the bottom of each page
#genhtml_footer = My footer text

# Coverage rate limits
genhtml_hi_limit = 90
genhtml_med_limit = 75

# Ignore some errors (comma-separated list)
#ignore_errors = empty,mismatch

# Stop emitting message after this number have been printed
# 0 == no limit
max_message_count = 100

# If nonzero, do not stop when an 'ignorable error' occurs - try
#  to generate a result, however flawed.  This is equivalent to
#  the '--keep-going' command line switch.
# Default is 1:  stop when error occurs
#stop_on_error = 1

# If nonzero, treat warnings as error
# note that ignored messages will still appear as warnings
# Default is 0
#treat_warning_as_error = 1

# If set to non-zero, only issue particular warning once per file
# Default is 1
#warn_once_per_file = 1

# extension associated with lcov trace files - glob match pattern
# used as argument to 'find' - to find coverage files contained in
# a directory argument
#info_file_pattern = *.info

# list of file extensions which should be treated as C/C++ code
# (comma-separated list)
#c_file_extensions = h,c,i,C,H,I,cpp,hpp,icc,cc,hh,cxx,hxx

# list of file extensions which should be treated as RTL code
# (*e.g.*, Verilog) (comma-separated list)
#rtl_file_extensions = v,vh,sv

# list of file extensions which should be treated as Java code
#java_file_extensions = java

# list of file extensions which should be treated as perl code
#perl_file_extensions = pl,pm

# list of file extensions which should be treated as python code
#python_file_extensions = py

# maximum number of lines to look at, when filtering bogus branch expressions
#filter_lookahead = 5

# if nonzero, bitwise operators '|', '&', '~' indicate conditional expressions
#filter_bitwise_conditional = 1

# if nonzero, '--filter blank' is applied to blank lines, regardless
# of their hit count
#filter_blank_aggressive = 1

# Width of line coverage field in source code view
genhtml_line_field_width = 12

# Width of branch coverage field in source code view
genhtml_branch_field_width = 16

# Width of MC/DC coverage field in source code view
genhtml_mcdc_field_width = 14

# width of 'owner' field in source code view - default is 20
genhtml_owner_field_width = 20
# width of 'age' field in source code view - default is 5
genhtml_age_field_width = 5

# Width of overview image
genhtml_overview_width = 80

# Resolution of overview navigation
genhtml_nav_resolution = 4

# Offset for source code navigation
genhtml_nav_offset = 10

# Do not remove unused test descriptions if non-zero
genhtml_keep_descriptions = 0

# Do not remove prefix from directory names if non-zero
genhtml_no_prefix = 0

# Do not create source code view if non-zero
genhtml_no_source = 0

# Specify size of tabs
genhtml_num_spaces = 8

# Include color legend in HTML output if non-zero
genhtml_legend = 0

# Include HTML file at start of HTML output
#genhtml_html_prolog = prolog.html

# Include HTML file at end of HTML output
#genhtml_html_epilog = epilog.html

# Use custom HTML file extension
#genhtml_html_extension = html

# Compress all generated html files with gzip.
#genhtml_html_gzip = 1

# Include sorted overview pages
genhtml_sort = 1

# Display coverage data in hierarchical directory structure
# (rather than flat/3 level)
#genhtml_hierarchical = 1

# Display coverage data using 'flat' view
#genhtml_flat_view = 1

# Specify the character set of all generated HTML pages
genhtml_charset=UTF-8

# Allow HTML markup in test case description text if non-zero
genhtml_desc_html=0

# Specify the precision for coverage rates
#genhtml_precision=1

# Show missed counts instead of hit counts
#genhtml_missed=1

# group function aliases in report - see '--merge' section in man(1) genhtml
#merge_function_aliases = 1

# If set, suppress list of aliases in function detail table
#suppress_function_aliases = 1

# If set, derive function end line from line coverpoint data - default ON
#derive_function_end_line = 1

# If set, derive function end lines for all file types.
# By default, we derive end lines for C/C++ files only
#
#derive_end_line_all_files = 0

# Maximum size of function (number lines) which will be checked by '--filter trivial'
#trivial_function_threshold = 5

# Set threshold for hit count which tool should deem likely to indicate
# a toolchain bug (corrupt coverage data)
# excessive_count_threshold = number

# Demangle C++ symbols
# Call multiple times to specify command and command line arguments
#  ('-Xlinker'-like behaviour)
#demangle_cpp = c++filt

# Location of the gcov tool
#geninfo_gcov_tool = gcov

# Adjust test names if non-zero
#geninfo_adjust_testname = 0

# Ignore testcase names in .info file
forget_testcase_names = 0

# Calculate and/or compute checksum for each line if non-zero
checksum = 0

# Enable libtool compatibility mode if non-zero
geninfo_compat_libtool = 0

# Specify whether to capture coverage data for external source
# files
#geninfo_external = 1

and that's the config example, bestie — next up is the OPTIONS section and it's a whole journey, but we're gonna go through every single one together 💖

...and the config file sample keeps going, bestie. We're still scrolling through the giant commented-out example that ships as the default lcovrc — every line here is either a setting you can literally uncomment, or one that's already live. Let's vibe-check the rest of them ✨

          # Specify whether to capture coverage data from compile-time data files
          # which have no corresponding runtime data.
          #geninfo_capture_all = 1

          # Use gcov's --all-blocks option if non-zero
          #geninfo_gcov_all_blocks = 1

          # Adjust 'executed' non-zero hit count of lines which contain no branches
          # and have attribute '"unexecuted_blocks": true'
          #geninfo_unexecuted_blocks = 0

          # Specify compatibility modes (same as \-\-compat option
          # of geninfo)
          #geninfo_compat = libtool=on, hammer=auto, split_crc=auto

Like — geninfo_capture_all is the "grab it even if there's no runtime data" switch, geninfo_gcov_all_blocks literally just hands gcov the --all-blocks flag, geninfo_unexecuted_blocks tweaks the non-zero hit count on lines with no branches that carry "unexecuted_blocks": true, and geninfo_compat is the twin of geninfo's --compat option 🫶

          # Specify if geninfo should try to automatically determine
          # the base-directory when collecting coverage data.
          geninfo_auto_base = 1

          # Use gcov intermediate format? Valid values are 0, 1, auto
          geninfo_intermediate = auto

          # Specify if exception branches should be excluded from branch coverage.
          no_exception_branch = 0

geninfo_auto_base = 1 = geninfo auto-detects the base-directory while collecting. geninfo_intermediate takes 0, 1, or auto (it's auto by default, iconic). And no_exception_branch = 0 means exception branches are not excluded from branch coverage — flip it and they're gone 💅

          # Directory containing gcov kernel files
          lcov_gcov_dir = /proc/gcov

          # Location for temporary directories
          lcov_tmp_dir = /tmp

          # Show full paths during list operation if non-zero
          lcov_list_full_path = 0

          # Specify the maximum width for list output. This value is
          # ignored when lcov_list_full_path is non-zero.
          lcov_list_width = 80

          # Specify the maximum percentage of file names which may be
          # truncated when choosing a directory prefix in list output.
          # This value is ignored when lcov_list_full_path is non-zero.
          lcov_list_truncate_max = 20

Kernel folks, lcov_gcov_dir is your /proc/gcov 🧚 and temp dirs live under /tmp. In list output, lcov_list_full_path = 0 keeps paths short — set it non-zero and you get the whole thing. lcov_list_width = 80 is the max width, but heads up: it gets ignored when lcov_list_full_path is non-zero. Same deal for lcov_list_truncate_max = 20 — that's the max percentage of file names allowed to be truncated when picking a directory prefix, and it also gets ignored when lcov_list_full_path is non-zero. Lowkey the theme of these two 🌸

          # Specify if function coverage data should be collected, processed, and
          # displayed.
          function_coverage = 1

          # Specify if branch coverage data should be collected, processed, and
          # displayed.
          branch_coverage = 0

          # Specify if Modified Condition / Decision Coverage data should be collected,
          #  processed, and displayed.
          mcdc_coverage = 0

Function coverage: on (1). Branch coverage: off by default (0). MC/DC coverage (Modified Condition / Decision Coverage, yes the fancy one): off by default (0) 😭

          # Ask lcov/genhtml/geninfo to return non-zero exit code if branch coverage is
          # below specified threshold percentage.
          #fail_under_branches = 75.0

          # Ask lcov/genhtml/geninfo to return non-zero exit code if line coverage is
          # below specified threshold percentage.
          #fail_under_lines = 97.5

These two are your "be dramatic in CI" buttons 🔥 fail_under_branches = 75.0 makes lcov/genhtml/geninfo exit non-zero if branch coverage drops under the threshold, and fail_under_lines = 97.5 does the same for line coverage.

          # Specify JSON module to use, or choose best available if
          # set to auto
          lcov_json_module = auto

          # Specify maximum number of parallel slaves
          # default: 1 (no parallelism)
          #parallel = 1

          # Specify maximum memory to use during parallel processing, in Mb.
          # Do not fork if estimated memory consumption exceeds this number.
          # default: 0 (no limit)
          #memory = 1024

          # Specify the number of consecutive fork() failures to allow before
          # giving up
          # max_fork_fails = 5

          # Seconds to wait after failing to fork() before retrying
          # fork_fail_timeout = 10

lcov_json_module = auto picks the best JSON module it can find — auto slay. parallel defaults to 1, aka no parallelism at all. memory is the max memory in Mb during parallel processing, and it will not fork if the estimated memory consumption blows past that number — default 0, no limit. max_fork_fails = 5 is how many consecutive fork() failures it tolerates before giving up, and fork_fail_timeout = 10 is the seconds it waits after a failed fork() before retrying 🦋

          # Throttling control:  specify a percentage of system memory to use as
          # maximum during parallel processing.
          # Do not fork if estimated memory consumption exceeds the maximum.
          # this value is used only if the maximum memory is not set.
          # default: not set
          #memory_percentage = 75

          # Character used to split list-type parameters
          #  - for example, the list of "--ignore_errors source,mismatch"
          # default: , (comma)
          #split_char = ,

          # use case insensitive compare to find matching files, for include/exclude
          #  directives, etc
          #case_insensitive = 0

          # read '.info' files - and genhtml udiff files - whose file names use the
          #  other platform's directory separator, translating them as they are read
          #cross_platform_read = 1

          # which platform's path convention this run works in:  auto, posix, windows,
          #  cygwin
          #path_style = auto

memory_percentage = 75 is the throttling vibe — a percentage of system memory to cap at during parallel processing, and again no forking past the estimate. It's only used if the maximum memory is not set, and it's not set by default. split_char is the character that splits list-type params (like the list of "--ignore_errors source,mismatch") and defaults to , ofc 💅 case_insensitive = 0 — flip it for case-insensitive matching of files in include/exclude directives etc. cross_platform_read = 1 reads .info files — and genhtml udiff files — that use the other platform's directory separator, translating as it reads. path_style picks the platform path convention: auto, posix, windows, or cygwin 👑

          # override line default line exclusion regexp
          #lcov_excl_line = LCOV_EXCL_LINE

          # override branch exclusion regexp
          #lcov_excl_br_line = LCOV_EXCL_BR_LINE

          # override exception branch exclusion regexp
          #lcov_excl_exception_br_line = LCOV_EXCL_EXCEPTION_BR_LINE

          # override start of exclude region regexp
          #lcov_excl_start = LCOV_EXCL_START

          # override end of exclude region regexp
          #lcov_excl_stop = LCOV_EXCL_STOP

          # override unreachable line default line exclusion regexp
          #lcov_unreachable_line = LCOV_UNREACHABLE_LINE

          # override start of unreachable region regexp
          #lcov_unreachable_start = LCOV_UNREACHABLE_START

          # override end of unreachable region regexp
          #lcov_unreachable_stop = LCOV_UNREACHABLE_STOP

          # override start of branch exclude region regexp
          #lcov_excl_br_start = LCOV_EXCL_BR_START

          # override start of exclude region regexp
          #lcov_excl_br_stop = LCOV_EXCL_BR_STOP

          # override start of exclude region regexp
          #lcov_excl_exception_br_start = LCOV_EXCL_EXCEPTION_BR_START

          # override start of exclude region regexp
          #lcov_excl_exception_br_stop = LCOV_EXCL_EXCEPTION_BR_STOP

That's the full set of exclusion regexp overrides — line, branch, exception branch, region start/stop, unreachable line + region, branch region start/stop, and exception branch region start/stop. Every one of those is just a default you can swap out. Ngl, that's a lot of knobs, but they're all listed above, so nothing's hiding from you 💖

✨ OPTIONS ✨

Okay bestie, now the actual options file format. Every setting is NAME = VALUE, and NAME is case-insensitive-ish in spirit — no wait, just read the entries 💀

💫 `CONFIG_FILE` = FILENAME 💫

Include another config file. Recursive config-file inception, basically.

Inclusion is equivalent to inserting the text from filename at this point in the current file. So settings from the included file land after earlier settings in the current file, but before later settings in the current file. Which means:

Scalar options set earlier in the current file get overridden by settings from the included file, and scalar options from the included file get overridden by later settings in the current file.
Array options from earlier in the current file appear before settings from the included file, and array options from later in the current file appear after.

Config file inclusion is recursive — an included config file may include another file, and so on forever. BUT: inclusion loops are not supported and will result in a usage error 🚨 No circular bestie behavior allowed.

The most common usecase for config file inclusion is so that a site-wide or project-wide options file can include a user-specific or module-specific options file — for example, as:

          ...
          config_file = $ENV{HOME}/.lcovrc_user
          ...

🌈 `GENHTML_CSS_FILE` = FILENAME 🌈

Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by genhtml. During output generation, a copy of this file will be placed in the output directory ✨

This option corresponds to the --css-file command line option of genhtml.

By default, a standard CSS file is generated.

🎀 `GENHTML_HEADER` = STRING 🎀

Specify header text to use at top of each HTML page.

This option corresponds to the --header-title command line option of genhtml.

Default is “LCOV - (differential )? coverage report”

🎀 `GENHTML_FOOTER` = STRING 🎀

Specify footer text to use at bottom of each HTML page.

This option corresponds to the --footer command line option of genhtml.

Default is LCOV tool version string.

🖤 `GENHTML_DARK_MODE` = `0` | `1` 🖤

If non-zero, display using light text on dark background rather than dark text on light background.

This option corresponds to the --dark-mode command line option of genhtml.

By default, a ‘light’ palette is used.

👑 `genhtml_hi_limit` = hi_limit, `genhtml_med_limit` = med_limit 👑

Specify coverage rate limits for classifying file entries. Use this option to modify the coverage rates (in percent) for line, function and branch coverage at which a result is classified as high, medium or low coverage. This classification affects the color of the corresponding entries on the overview pages of the HTML output:

          High:   hi_limit  <= rate <= 100        default color: green
          Medium: med_limit <= rate < hi_limit    default color: yellow
          Low:    0         <= rate < med_limit   default color: red

Defaults are 90 and 75 percent.

There are also options to configure different thresholds for line, branch, and function coverages. See below 🫶

💚 `genhtml_line_hi_limit` = line_hi_limit, `genhtml_line_med_limit` = line_med_limit 💚

Specify specific threshold for line coverage limits used to decide whether a particular line coverage percentage is classified as high, medium, or low coverage. If the line-specific values are not specified, then the default genhtml_med_limit or genhtml_hi_limit values are used.

💛 `genhtml_branch_hi_limit` = branch_hi_limit, `genhtml_branch_med_limit` = branch_med_limit 💛

Specify specific threshold for branch coverage limits used to decide whether a particular branch coverage percentage is classified as high, medium, or low coverage. If the branch-specific values are not specified, then the default genhtml_med_limit or genhtml_hi_limit values are used.

💜 `genhtml_function_hi_limit` = function_hi_limit, `genhtml_function_med_limit` = function_med_limit 💜

Specify specific threshold for function coverage limits used to decide whether a particular function coverage percentage is classified as high, medium, or low coverage. If the function-specific values are not specified, then the default genhtml_med_limit or genhtml_hi_limit value is used.

🦋 `RTL_FILE_EXTENSIONS` = STR[,STR]+ 🦋

Specify a comma-separated list of file extensions which should be assumed to be RTL code (e.g., Verilog).

If not specified, the default set is ‘v,vh,sv,vhdl?’. There is no command line option equivalent.

This option is used by genhtml and lcov.

⭐ `INFO_FILE_PATTERN` = STR ⭐

Specify a glob-match pattern associated with lcov trace files (suitable as an argument to ‘find’. If not specified, the default is ‘*.info’.

🍓 `C_FILE_EXTENSIONS` = STR[,STR]+ 🍓

Specify a comma-separated list of file extensions which should be assumed to be C/C++ code.

If not specified, the default set is ‘c,h,i,C,H,I,icc,cpp,cc,cxx,hh,hpp,hxx’. If you want all files to be treated as C/C++ code, you can use: c_file_extensions = .*

This parameter must be set from the lcovrc file or via the --rc name=value command line option; note that you may need to protect the value from shell expansion in the latter case. Don't get caught lacking by your shell 💀

🧚 `JAVA_FILE_EXTENSIONS` = STR[,STR]+ 🧚

Specify a comma-separated list of file extensions which should be assumed to be Java code.

If not specified, the default set is ‘java’. If you want all files to be treated as Java code, you can use: java_file_extensions = .*

Same rule as above, bestie: this parameter must be set from the lcovrc file or via the --rc name=value command line option; note that you may need to protect the value from shell expansion in the latter case 🌸

🌸 `PERL_FILE_EXTENSIONS = STR[,STR]+`

Okay bestie, this one tells the tools which file extensions should be treated as Perl code — give it a comma-separated list, periodt.

If you don’t set it, the default set is pl,pm. And if you want literally every file to be treated as Perl code, you can do:

perl_file_extensions = .*

This parameter must be set from the lcovrc file or via the --rc name=value command line option. Quick heads-up: with the command line option you may need to protect the value from shell expansion. iykyk 💅

🐍 `PYTHON_FILE_EXTENSIONS = STR[,STR]+`

Same vibe, but for Python: comma-separated list of file extensions assumed to be Python code.

If not specified, the default set is py. Want every file treated as Python? Slay, use:

python_file_extensions = .*

This parameter must be set from the lcovrc file or via the --rc name=value command line option; note that you may need to protect the value from shell expansion in the latter case. 🫶

🔍 `FILTER_LOOKAHEAD = INTEGER`

This sets the maximum number of lines to look at when filtering bogus branch expressions. A larger number may catch more cases, but it will increase execution time — so don’t go feral with it.

If not specified, the default set is 10. There is no command line option equivalent.

This option is used by genhtml and lcov. ✨

🧚 `FILTER_BITWISE_CONDITIONAL = 0|1`

If set to a non-zero value, bogus branch filtering will assume that expressions containing bitwise operators &, |, ~ are conditional expressions — and will not filter them out.

If not specified, the default set is 0 (do not treat them as conditional). There is no command line option equivalent.

This option is used by genhtml and lcov. 🎀

🫧 `FILTER_BLANK_AGGRESSIVE = 0|1`

If set to a non-zero value, then blank source lines will be ignored whether or not their hit count is zero. See the --filter blank section in genhtml(1) <file://../man/genhtml.1.html>.

If not specified, the default set is 0 (filter blank lines only if they are not hit). There is no command line option equivalent.

Lowkey niche but iconic when you need it. 💖

🙈 `IGNORE_ERRORS = MESSAGE_TYPE(,MESSAGE_TYPE)*`

Specify a message type that should be ignored. Yes, you can use this multiple times in the lcovrc file to ignore multiple message types — collect them all, bestie.

This option is equivalent to the --ignore-errors option to geninfo, genhtml, or lcov. Important plot twist: the lcovrc file message list is not applied (those messages are NOT ignored) if the --ignore-errors command line option is specified.

This option is used by genhtml, lcov, and geninfo. 💅

🦋 `IGNORE_UNREACHABLE_FLAG = 0 | 1`

When parsing a trace file, ignore unreachable flags on branch expressions and MC/DC conditions — effectively, treating them as reachable.

Note that ignore_unreachable_flag is used only when reading a trace file. It has no effect on unreachable flags set by your unreachable_script callback. See the unreachable_script section, below.

This option is used by genhtml, lcov, and geninfo. 🌈

🔥 `EXPECT_MESSAGE_COUNT = MESSAGE_TYPE:EXPR(,MESSAGE_TYPE:EXPR)*`

This is the vibe check for your messages: specify a constraint on the number of messages of one or more types that are expected to be produced during tool execution. If the constraint is not true, an error of type count will be generated. 😭

You can specify multiple constraints with a comma-separated list, or by using the option multiple times.

Substitutions are performed on the expression before it is evaluated:

For example:

expect_message_count = inconsistent : %C == 5

says that you expect exactly 5 messages of this type

expect_message_count inconsistent : %C > 6 && %C <= 10

says that you expect the number of messages to be in the range (6:10].

This option is useful if errors are caused by conditions that you cannot fix — for example, due to inconsistent coverage data generated by your toolchain. In those scenarios, you may decide:

to exclude the offending code, or
to exclude the entire offending file(s), or
to ignore the messages, either by converting them to warnings or suppressing them entirely.

In the latter case, this option provides some additional safety by warning you when the count differs due to some change which occurred, giving you the opportunity to diagnose the change and/or to review message changes.

This option is equivalent to the --expect-message-count command line flag. ⭐

🧮 `MAX_MESSAGE_COUNT = INTEGER`

Set the maximum number of warnings of any particular type which should be emitted. This can be used to reduce the size of log files — because nobody wants a 10,000-line warning novel, bestie.

No more warnings will be printed after this number is reached. 0 (zero) is interpreted as no limit.

This option is used by genhtml, lcov, and geninfo. 🍓

📝 `MESSAGE_LOG = FILENAME`

Specify location to store error and warning messages (in addition to writing to STDERR). If not specified, then the default location is used.

This attribute is equivalent to the --msg-log command line option. The command line option takes precedence if both are specified. periodt.

🛑 `STOP_ON_ERROR = 0|1`

If set to 0, tell the tools to ignore errors and keep going to try to generate a result — however flawed or incomplete that result might be. Note: some errors cannot be ignored, and ignoring some errors may lead to other errors. 😬

The tool will return a non-zero exit code if one or more errors are detected during execution when stop_on_error is disabled. That is, the tool will continue execution in the presence of errors but will return an exit status.

This is equivalent to the --keep-going command line option.

Default is 1: stop when error occurs.

If the ignore_error msgType option is also used, then those messages will be treated as warnings rather than errors (or will be entirely suppressed if the message type appears multiple times in the ignore_messages option). Warnings do not cause a non-zero exit status.

This option is used by genhtml, lcov, and geninfo. 💀

⚠️ `TREAT_WARNING_AS_ERROR = 0|1`

If set to 1, tell the tools that messages which are normally treated as warnings (e.g., certain usage messages) should be treated as errors.

Note that ignored messages will still appear as warnings: see the ignore_errors entry, above.

This option is used by genhtml, lcov, and geninfo. 🎀

🔂 `WARN_ONCE_PER_FILE = 0|1`

If set to 1, tell the tools to emit certain errors only once per file (rather than multiple times, if the issue occurs multiple times in the same file).

Default is 1: do not report additional errors.

This option is used by genhtml, lcov, and geninfo. ✨

🧼 `CHECK_DATA_CONSISTENCY = 0|1`

If set to 1, tell the tools to execute certain data consistency checks — e.g., that a function with a non-zero hit count contains at least one line with a non-zero hit count — and vice versa.

It may be useful to use this option to disable checking if you have inconsistent legacy data and have no way to correct or exclude it.

Default is 1: execute consistency checks.

Consistency is the moment, but legacy data is gonna legacy. 💅

📏 `GENHTML_LINE_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

Specify the width (in characters) of the source code view column containing line coverage information.

Default is 12.

🌿 `GENHTML_BRANCH_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

Specify the width (in characters) of the source code view column containing branch coverage information.

Default is 16.

🧬 `GENHTML_MCDC_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

Specify the width (in characters) of the source code view column containing MC/DC coverage information.

Default is 14.

👑 `GENHTML_OWNER_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

Specify the width (in characters) of the source code view column containing owner information (as reported by your annotation script). This option has an effect only if you are using a source annotation script: see the --annotation-script option in the genhtml man page.

Default is 20.

⏳ `GENHTML_AGE_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

Specify the width (in characters) of the source code view column containing age of the corresponding block (as reported by your annotation script). This option has an effect only if you are using a source annotation script: see the --annotation-script option in the genhtml man page.

Default is 5.

🖼️ `GENHTML_FRAMES = 0 | 1`

Specify whether source detail view should contain a navigation image. See the --frame entry in the genhtml man page. 🦋

🖥️ `GENHTML_OVERVIEW_WIDTH = PIXEL_SIZE`

Specify the width (in pixel) of the overview image created when generating HTML output using the --frames option of genhtml.

Default is 80.

🧭 `GENHTML_NAV_RESOLUTION = LINES`

Specify the resolution of overview navigation when generating HTML output using the --frames option of genhtml. This number specifies the maximum difference in lines between the position a user selected from the overview and the position the source code window is scrolled to.

Default is 4.

🎯 `GENHTML_NAV_OFFSET = LINES`

Specify the overview navigation line offset as applied when generating HTML output using the --frames option of genhtml.

Clicking a line in the overview image should show the source code view at a position a bit further up, so that the requested line is not the first line in the window. This number specifies that offset.

Default is 10.

💌 `GENHTML_KEEP_DESCRIPTIONS = 0 | 1`

If non-zero, keep unused test descriptions when generating HTML output using genhtml.

This option corresponds to the --keep-descriptions option of genhtml.

Default is 0.

✂️ `GENHTML_NO_PREFIX = 0 | 1`

If non-zero, do not try to find and remove a common prefix from directory names.

This option corresponds to the --no-prefix option of genhtml.

Default is 0.

🚫 `GENHTML_NO_SOURCE = 0 | 1`

If non-zero, do not create a source code view when generating HTML output using genhtml.

This option corresponds to the --no-source option of genhtml.

Default is 0.

🔢 `GENHTML_NUM_SPACES = NUM`

Specify the number of spaces to use as replacement for tab characters in the HTML source code view as generated by genhtml.

This option corresponds to the --num-spaces option of genhtml.

Default is 8.

🎨 `GENHTML_LEGEND = 0 | 1`

If non-zero, include a legend explaining the meaning of color coding in the HTML output as generated by genhtml.

This option corresponds to the --legend option of genhtml.

Default is 0.

📜 `GENHTML_HTML_PROLOG = FILENAME`

If set, include the contents of the specified file at the beginning of HTML output.

This option corresponds to the --html-prolog option of genhtml.

Default is to use no extra prolog.

📜 `GENHTML_HTML_EPILOG = FILENAME`

If set, include the contents of the specified file at the end of HTML output.

This option corresponds to the --html-epilog option of genhtml.

Default is to use no extra epilog.

🏷️ `GENHTML_HTML_EXTENSION = EXTENSION`

If set, use the specified string as filename extension for generated HTML files.

This option corresponds to the --html-extension option of genhtml.

Default extension is html. 💖

🎀 `GENHTML_HTML_GZIP = 0 | 1`

If this is set, bestie, all the html files get compressed using gzip. It’s giving “smaller files, cleaner vibes” ✨.

This option corresponds to the --html-gzip option of genhtml.

Default extension is 0.

🌸 `GENHTML_SORT = 0 | 1`

If non-zero, genhtml creates overview pages sorted by coverage rates when it’s generating HTML output. So the coverage table gets a little main-character makeover and sorts itself 💅.

This option can be set to 0 by using the --no-sort option of genhtml.

Default is 1.

🦋 `GENHTML_HIERARCHICAL = 0 | 1`

If non-zero, the HTML report follows the hierarchical directory structure of the source code. Very “respect the folder tree” energy 🌳.

This option is equivalent to using the --hierarchical command line option of genhtml. ‘Hierarchical’ and ‘flat’ views are mutually exclusive — you cannot have both, no cap.

Default is 0.

💜 `GENHTML_FLAT_VIEW = 0 | 1`

If non-zero, the top-level HTML table contains all of the files in the project, and there are no intermediate directory pages. It’s flat, it’s direct, it’s literally all up in one table 🫶.

This option is equivalent to using the --flat command line option of genhtml. ‘Hierarchical’ and ‘flat’ views are mutually exclusive.

Default is 0.

⭐ `GENHTML_SHOW_NAVIGATION = 0 | 1`

If non-zero, the ‘source code’ view summary table gets hyperlinks from the number to the first source line in the corresponding category (‘Hit’ or ‘Not hit’) in the non-differential coverage report. Clickable little shortcuts, love that for us ✨.

Source code hyperlinks are always enabled in differential coverage reports.

This option is equivalent to using the --show-navigation command line option of genhtml.

Default is 0.

👑 `GENHTML_SHOW_OWNER_TABLE = 0 | 1 | ALL`

If non-zero, this is equivalent to the genhtml --show-owners flag: see genhtml(1) (file://../man/genhtml.1.html) for details.

Default is 0.

🍓 `COMPACT_SUMMARY_TABLES = 0 | 1`

If non-zero, suppress the ‘Total’ row in the ‘date’ and ‘owner’ summary table if there is only one element in the corresponding bin. Basically: one item? No need for a whole extra Total row, bestie 💀.

When there are a large number of files with a single author, this can cut the summary table size by almost half.

Default is 1 (enabled).

🌈 `OWNER_TABLE_ENTRIES = INTEGER`

This option tells genhtml the number of ‘owner’ table entries to retain in the summary table (at the top of the page) if owner table truncation is requested.

Authors are sorted by quantity of un-exercised code — so elided entries will be smaller offenders: maximal offenders are retained. If the option is not set, then owner tables are not truncated.

This option has no effect unless genhtml --show-owners is enabled. See the --show-owners option in genhtml(1) (file://../man/genhtml.1.html) for details.

Default is not set (i.e., do not truncate owner tables).

🧚 `TRUNCATE_OWNER_TABLE = COMMA_SEPARATED_LIST`

This option tells genhtml whether to truncate the ‘owner’ table at the top, directory, or file level. It acts together with the owner_table_entries parameter to determine how many author entries are retained.

This option has no effect unless genhtml --show-owners is enabled and the owner_table_entries configuration is set.

If this option is set multiple times in the lcovrc file, the values are combined to form the list of levels where truncation will occur. Similarly, if this option is not set and owner_table_entries is set, then the table will be truncated everywhere.

See the --show-owners option in genhtml(1) (file://../man/genhtml.1.html) for details.

Default is to not truncate the list.

💖 `GENHTML_SHOW_NONCODE_OWNERS = 0 | 1`

If non-zero, equivalent to the genhtml --show-noncode flag: see genhtml(1) (file://../man/genhtml.1.html) for details.

Default is 0.

🔥 `GENHTML_SHOW_FUNCTION_PROPORTION = 0 | 1`

If nonzero, add a column to the “function coverage detail” table to show the proportion of lines and branches within the function which are exercised. It’s giving “show me the receipts” for function coverage 📊.

This option is equivalent to using the --show-proportion command line option of genhtml.

Default is 0.

🎀 `GENHTML_SYNTHESIZE_MISSING = 0 | 1`

If non-zero, equivalent to the genhtml --synthesize-missing flag: see genhtml(1) (file://../man/genhtml.1.html) for details.

Default is 0.

🦋 `GENHTML_CHARSET = CHARSET`

Specify the character set of all generated HTML pages.

Use this option if the source code contains characters which are not part of the default character set. Note that this option is ignored when a custom HTML prolog is specified (see also genhtml_html_prolog).

Default is UTF-8.

💅 `DEMANGLE_CPP = C++FILT`

If set, this option tells genhtml/lcov/geninfo to demangle C++ function names in function overviews, and it gives the name of the tool used for demangling. Set this option to one if you want to convert C++ internal function names to human readable format for display on the HTML function overview page.

If the demangle_cpp option is used multiple times, then the arguments are concatenated when the callback is executed — similar to how the gcc -Xlinker parameter works. This provides a possibly easier way to pass arguments to your tool, without requiring a wrapper script. In that case, your callback will be executed as: | tool-0 ‘tool-1; … Arguments are quoted when passed to the shell, in order to handle parameters which contain spaces.

Note that the demangling tool is called via a pipe, and is expected to read from stdin and write to stdout.

This option corresponds to the --demangle-cpp command line option of genhtml.

Default is not set (C++ demangling is disabled).

🌸 `GENHTML_DESC_HTML = 0 | 1`

If non-zero, test case descriptions may contain HTML markup.

Set this option to one if you want to embed HTML markup (for example to include links) in test case descriptions. When set to zero, HTML markup characters will be escaped to show up as plain text on the test case description page.

Default is 0.

⭐ `GENHTML_PRECISION = 1 | 2 | 3 | 4`

Specify how many digits after the decimal-point should be used for displaying coverage rates. Precision queen behavior, honestly 💅.

Default is 1.

🫶 `MERGE_FUNCTION_ALIASES = 0 | 1`

If non-zero, group function aliases in the function detail table. See man(1) genhtml.

Default is 0.

💜 `GENHTML_MISSED = 0 | 1`

If non-zero, the count of missed lines, functions, or branches is shown as negative numbers in overview pages. Yes, negative — it’s dramatic on purpose 😭.

Default is 0.

🍓 `SUPPRESS_FUNCTION_ALIASES = 0 | 1`

If non-zero, do not show aliases in the function detail table.

If nonzero, implies that merge_function_aliases is enabled. See the genhtml man page for more details.

Default is 0.

🌈 `DERIVE_FUNCTION_END_LINE = 0 | 1`

If non-zero, use ‘line’ coverage data to deduce the end line of each function definition. This is useful when excluding certain functions from your coverage report. See the --erase-functions, --filter trivial and --show-proportion options.

Default is 1.

This option is not required if you are using gcc/9 or newer; these versions report function begin/end lines directly.

Note that end lines are derived only for C/C++ files unless the derive_function_end_lines_all_files option is enabled; see the c_file_extensions setting, above, for the list of extensions used to identify C/C++ files.

Lambda functions are ignored during end line computation. Note that lambdas are identified via function name matching — so you must enable demangling if your toolchain is too old to report demangled names in the GCOV output. See the demangle_cpp setting, above.

For languages other than C/C++: end-line derivation may compute the wrong value — e.g., in cases where there are lines of code in global scope following some function definition. In this case, lcov will incorrectly associate the following code with the preceding function.

If this creates problems — for example, causes lcov to warn about inconsistent coverage data — then there are several possible workarounds:

disable end-line derivation — e.g., via --rc derive_function_end_line=0.
exclude the offending code and/or the entire associated file.
ignore the error message, e.g., via the --ignore-errors command line option.
disable coverage DB consistency checks — e.g., via --rc check_data_consistency=0.

🧚 `DERIVE_FUNCTION_END_LINE_ALL_FILES = 0 | 1`

If non-zero, derive end lines for all functions, regardless of source language. By default, end lines are computed only in C/C++ files.

This option has no effect if derive_function_end_lines is disabled.

Default is 0 (disabled).

🎀 `TRIVIAL_FUNCTION_THRESHOLD = INTEGER`

Set the maximum size of function (in number of lines) which will be checked by --filter trivial filter.

Default is 5.

💀 `EXCESSIVE_COUNT_THRESHOLD = NUMBER`

Set the threshold for hit count that lcov deems excessive/unlikely/indicating a bug somewhere in your toolchain.

For example, it is unlikely that your job can run long enough to rack up tens of billions of hits.

Message type excessive is used to report potential issue — see the genhtml(1), lcov(1), geninfo(1) man pages.

Default is not set. (Do not check for excessive counts.)

🔥 `GENINFO_GCOV_TOOL = PATH_TO_GCOV`

Specify the location of the gcov tool (see gcov(1)) which is used to generate coverage information from data files.

This option can be used multiple times — e.g., to add arguments to the gcov callback. See the geninfo man page for details.

🦋 `GENINFO_ADJUST_TESTNAME = 0 | 1`

If non-zero, adjust test names to include operating system information when capturing coverage data.

Default is 0.

💖 `FORGET_TESTCASE_NAMES = 0 | 1`

If non-zero, ignore testcase names in .info file. This may improve performance and reduce memory consumption if user does not need per-testcase coverage summary in coverage reports.

This is equivalent to the “--forget-test-names” lcov/genhtml option.

Default is 0.

🌸 `CHECKSUM = 0 | 1`

If non-zero, generate source code checksums when capturing coverage data. Checksums are useful to prevent merging coverage data from incompatible source code versions, but checksum generation increases the size of coverage files and the time used to generate those files.

This option can be overridden by the --checksum and --no-checksum command line options.

Default is 0.

Note that this option is somewhat subsumed by the version_script option — which does something similar, but at the ‘whole file’ level.

🫶 `GENINFO_COMPAT_LIBTOOL = 0 | 1`

If non-zero, enable libtool compatibility mode. When libtool compatibility mode is enabled, lcov will assume that the source code relating to a .da file located in a directory named “.libs” can be found in its parent directory.

This option corresponds to the --compat-libtool and --no-compat-libtool command line option of geninfo.

Default is 1.

`GENINFO_EXTERNAL` = 0 | 1

okay so if this is non-zero, geninfo will capture coverage data for external source files 💅

and what even is an external source file, you ask? bestie it's a file that is not chillin' in one of the directories (including sub-directories, yes all the way down 🫶) that you named with the --directory or --base-directory options of lcov / geninfo. also pls go look at the --follow option and the geninfo_follow_symlinks and geninfo_follow_file_links entries for the extra path controls, iykyk ✨

default is 1.

`GENINFO_CAPTURE_ALL` = 0 | 1

non-zero here means: capture coverage data from both runtime data files and compile time data files that have no corresponding runtime data at all 😭 like the compile-time ones are just sitting there with no runtime buddy. see the --all flag description in man(1) geninfo for the full lore 📖

default is 0: we do not process bare compile-time data files. nope. not today 💀

`GENINFO_EXTERNAL` = 0 | 1

(yes bestie this one is literally listed twice in the source page — same words, same default — so here it is again, no cap 🙈)

if non-zero, capture coverage data for external source files.

external source files are files which are not located in one of the directories (including sub-directories) specified by the --directory or --base-directory options of lcov / geninfo. also see the --follow option and the geninfo_follow_symlinks and geninfo_follow_file_links for additional path controls.

default is 1. 💖

`GENINFO_FOLLOW_SYMLINKS` = 0 | 1

this is literally the RC-file twin of the lcov/geninfo --follow command line option. see geninfo(1) for the deets 🦋

default is 0: do not modify follow symbolic links. (like, we leave the symlinks alone, bestie, we're not touching them 💅)

`GENINFO_FOLLOW_FILE_LINKS` = 0 | 1

so if this is non-zero and the lcov/geninfo --follow command line option is specified, then source file pathnames which contain symlinks get resolved to their actual target 🎯

⚠️ heads up bestie: the parent directory of the link target may be considered ‘external’ and thus get removed by the --no-external flag. so like, careful 👀

default is 0: do not modify pathnames.

`GENINFO_GCOV_ALL_BLOCKS` = 0 | 1

if non-zero, we call the gcov tool with option --all-blocks 🔥

using --all-blocks gives you more detailed branch coverage information for each line. set this option to zero if you don't need detailed branch coverage info — that speeds up the whole capturing-code-coverage process — or if you're working around a bug in some versions of gcov which will cause it to endlessly loop when analyzing some files 😭😭 (yes, an infinite loop. the girlies are spinning. it's giving unhinged.)

default is 1.

`GENINFO_UNEXECUTED_BLOCKS` = 0 | 1

if non-zero, adjust the ‘hit’ count of lines which have attribute "unexecuted_block": true but which contain no branches and have a non-zero count. basically we assume those lines are not executed 🙅‍♀️

note that this option is effective only for gcov versions 9 and newer 🧚

default is 0.

`GENINFO_COMPAT` = `MODE=VALUE[, MODE=VALUE,…]`

tell geninfo to enable one or more compatibility modes when capturing coverage data ✨

this option corresponds to the --compat command line option of geninfo.

default is ‘libtool=on, hammer=auto, split_crc=auto’. periodt 💅

`geninfo_adjust_src_path` = pattern => replacement

`geninfo_adjust_src_path` = pattern

adjust source paths when capturing coverage data 🛠️

use this option in situations where geninfo cannot find the correct path to source code files of a project. give it a pattern in Perl regular expression format (see perlre(1)) and an optional replacement string, and you can instruct geninfo to remove or change parts of the incorrect source path 💖

example time, bestie:

when geninfo reports that it cannot find source file

/path/to/src/.libs/file.c

while the file is actually located in

/path/to/src/file.c

use the following parameter:

geninfo_adjust_src_path = /.libs

this will remove all “/.libs” strings from the path. slay 🎀

when geninfo reports that it cannot find source file

/tmp/build/file.c

while the file is actually located in

/usr/src/file.c

use the following parameter:

geninfo_adjust_src_path = /tmp/build => /usr/src

this will change all “/tmp/build” strings in the path to “/usr/src”. iconic 🌟

the adjust_src_path option is similar to the substitution = … option — which is somewhat more general and allows you to specify multiple substitution patterns. also see the resolve_script option 👑

`SOURCE_DIRECTORY` = DIRNAME

add ‘dirname’ to the list of places to look for source files 🔍 also see the --source-directory entry in the lcov, geninfo, and genhtml man pages.

for relative source file paths (e.g., found in some tracefile or in gcov output), we first look for the path from ‘cwd’ (where genhtml was invoked) and then from each alternate directory name in the order specified. the first location matching location is used 🎯

this option can be specified multiple times, to add more directories to the source search path 🦋

note that the command line option overrides the RC file entries (if any). command line stays winning, sorry not sorry 💅

`BUILD_DIRECTORY` = DIRNAME

add ‘dirname’ to the list of places to look for matching GCNO files (geninfo) or source file soft links (genhtml) 🌸 see the --build-directory description in the geninfo and in the genhtml man page.

this option can be specified multiple times, to add more directories to the source search path ✨

note that the command line option overrides the RC file entries (if any). again. the command line is the main character here 👑

`GENINFO_AUTO_BASE` = 0 | 1

if non-zero, apply a heuristic to determine the base directory when collecting coverage data 🧠

use this option when using geninfo on projects built with libtool or similar build environments that work with multiple base directories — i.e. environments where the current working directory when invoking the compiler is not the same directory in which the source code file is located, and in addition, is different between files of the same project 😮‍💨 like it's messy in here.

default is 1.

`GENINFO_INTERMEDIATE` = 0 | 1 | AUTO

specify whether to use gcov intermediate format 🧚

use this option to control whether geninfo should use the gcov intermediate format while collecting coverage data. using the gcov intermediate format should increase processing speed 🔥 it also provides branch coverage data when using the --initial command line option. we love a bonus ✨

valid values are 0 for off, 1 for on, and “auto” to let geninfo automatically use immediate format when supported by gcov.

default is “auto”. 💖

`NO_EXCEPTION_BRANCH` = 0 | 1

specify whether to exclude exception branches from branch coverage 🙈 whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data. so like, it's not entirely on us bestie, it's giving "it depends" 😭

this option is used by lcov, geninfo, genhtml.

the value no_exception_branch = 1 is equivalent to the --filter exception command line option ✅

default is 0.

`GENINFO_CHUNK_SIZE` = INTEGER [%]

specify the number of GCDA files which should be processed per-call in each child process 🍓 this parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent — which then affects the queuing delay. higher queuing delay lowers the effective parallelism 💀 so like, balance it.

the default is 80% of total_number_of_gcda_files / maximum_number_of_parallel_children, the average number of files expected to be processed by each child. see the --parallel entry in the geninfo man page 📖

the argument may be either an integer value to be used as the chunk size or a percentage of the average number files processed per child.

this option has no effect unless the --parallel option has been specified 👀

`GENINFO_DEDICATE_SEGMENT_SIZE` = INTEGER_BYTES

this is the geninfo analog of dedicate_segment_threshold 🧬 at scheduling time the .gcno/.gcda files have not yet been parsed, so — absent per-file history — the only signal for how much work a compilation unit will require is its on-disk size 📏

a history-less coverage file at least this many bytes is given its own dedicated child process (scheduled first), so a single huge compilation unit does not serialize the tail of a parallel geninfo run 🚀 because one giant file hogging the line is not the vibe. when per-file history is available, dedicate_segment_threshold (a predicted-seconds threshold) is used instead.

this is distinct from the --large-file option, which runs a matching file serially in the parent process to avoid a memory spaceout — a memory-safety control rather than a latency one 🧠 a file matched by --large-file is never also given a dedicated child process. never. both. periodt.

set to 0 to disable the feature. the default is 50000000 (50 MB).

this option has no effect unless the --parallel option has been specified 🙈

`GENINFO_INTERVAL_UPDATE` = INTEGER

set the percentage of GCDA files which should be processed between console/progress updates 📊 this setting may be useful for parameter tuning and debugging apparent performance issues 🔧

the default is 5%.

this option has no effect unless the --parallel option has been specified 💅

`LCOV_FILTER_CHUNK_SIZE` = INTEGER [%]

specify the number of source files which should be processed per-call in each child process when applying coverpoint filters — see the filter = … parameter, below 👇 this parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent — which then affects the queuing delay. higher queuing delay lowers the effective parallelism 😮‍💨

the default is 80% of total_number_of_source_files / maximum_number_of_parallel_children. 🍓

the argument may be either an integer value to be used as the chunk size or a percentage of the average number files processed per child.

this option has no effect unless the --parallel option has been specified and lcov_filter_parallel is not zero. two whole conditions bestie 🫶

`LCOV_FILTER_PARALLEL` = 0 | 1

this option specifies whether coverpoint filtering should be done serially or in parallel ⚡ if the number of files to process is very large, then parallelization may improve performance 🚀

this option has no effect unless the --parallel option has been specified 👀

the default is 1 (enabled). 💖

`LCOV_GCOV_DIR` = PATH_TO_KERNEL_COVERAGE_DATA

specify the path to the directory where kernel coverage data can be found 🐧 or leave it undefined for auto-detection.

default is auto-detection. we'll find it ourselves, don't worry ✨

`LCOV_TMP_DIR` = TEMP

specify the parent directory that temporary and intermediate data is written under 📁 a uniquely named subdirectory of temp is created for each run, so several tools or several runs can share the same temp without colliding 🎀 (we do not do collision drama here.) temp is created if it does not exist.

⚠️ unless --preserve is specified, the generated subdirectory and its contents are removed when the tool exits. bye bye 🫡

this option corresponds to the --tempdir option of lcov, geninfo, genhtml and html2lcov.

default is the platform temporary directory: $TMPDIR, $TEMP or $TMP if one of them names a writeable directory, otherwise ‘/tmp’ on Unix or ‘C:\temp’ on Windows. 🪟🐧

`LCOV_LIST_FULL_PATH` = 0 | 1

if non-zero, print the full path to source code files during a list operation 📜

this option corresponds to the --list-full-path option of lcov.

default is 0. 💜

LCOV_LIST_MAX_WIDTH = WIDTH — sets the max width for list output. Heads up: this value is completely ignored when lcov_list_full_path is non-zero. So if you set that to 1, this number is just sitting there doing nothing, living its little life 💅

Default is 80.

LCOV_LIST_TRUNCATE_MAX = PERCENTAGE — caps the max percentage of file names that get truncated when list output picks a directory prefix. Same deal as above: ignored when lcov_list_full_path is non-zero.

Default is 20.

🌸 FUNCTION_COVERAGE = 0 | 1 🌸

Tells lcov / geninfo / genhtml whether they should generate, process, and display function coverage data. 🫶

Setting this to 0 and turning function coverage off can slightly cut down memory and CPU time while lcov is collecting and processing coverage data, plus it shrinks the resulting data files. Lowerkey a whole little glow-up for your resource usage ✨

Heads up bestie: function records in an input tracefile get discarded without being checked when this is off — so a malformed one is not reported. Peep the TRACEFILE FORMAT section of geninfo(1).

This option can be overridden by the --function-coverage and --no-function-coverage command line options. 👑

Default is 1.

🌈 BRANCH_COVERAGE = 0 | 1 🌈

Tells lcov / geninfo whether to generate, process, and display branch coverage data. 🌿

Set it to 0 and branch coverage off, and you can reduce memory and CPU time while lcov is collecting and processing coverage data, and shrink the resulting data files too. Efficiency slay 💅

Same caveat energy: BRDA: records in an input tracefile then get discarded without being checked, so a malformed one is not reported — see the TRACEFILE FORMAT section of geninfo(1).

This option can be overridden by the --branch-coverage and --no-branch-coverage command line options.

Default is 0.

💜 MCDC_COVERAGE = 0 | 1 💜

Tells lcov / geninfo whether to generate, process, and display Modified Condition / Decision Coverage (MC/DC) coverage data. That's the fancy one 😤

Turn it off with 0 and you can reduce memory and CPU time while lcov is collecting and processing coverage data, and reduce the size of the resulting data files. Short king behavior for your tracefiles.

And again: MCDC: records in an input tracefile are then discarded without being checked, so a malformed one is not reported — check the TRACEFILE FORMAT section of geninfo(1).

This option can be overridden by the --mcdc-coverage command line option.

Default is 0 (not enabled).

See the MC/DC section of genhtml(1) for more details.

🎀 EXCLUSION MARKERS 🎀

🦋 LCOV_EXCL_LINE = EXPRESSION 🦋

Sets the regular expression for lines to exclude. Line, branch, and function coverpoints that are associated with lines where this regexp shows up get dropped. 🗑️

There are at least 2 (moderately) common use cases for custom exclusion markers:

You're using multiple tools for coverage analysis, each with its own directives, and you don't want to clutter your source code with directives for every single one of them 🙈
You want to exclude different regions / different types of code in different contexts — for example, ignoring or not ignoring debug/trace code depending on your team 👀

Default is 'LCOV_EXCL_LINE'.

🦋 LCOV_EXCL_BR_LINE = EXPRESSION 🦋

Sets the regular expression for lines to exclude from branch coverage. Branch coverpoints associated with lines where this regexp appears get dropped. (Line and function coverpoints are not affected, bestie — they're safe 🫶)

Default is 'LCOV_EXCL_BR_LINE'.

🦋 LCOV_EXCL_EXCEPTION_BR_LINE = EXPRESSION 🦋

Sets the regular expression for lines to exclude from exception branch coverage. Exception-related branch coverpoints tied to lines where this regexp is found get dropped. (Line and function coverpoints are not affected. Branch coverpoints that aren't exception-related are also not affected — only the exception ones get the boot 👋)

Also see geninfo_no_exception_branch — if that's nonzero, then all identified exception branches get removed.

Ngl, this feature needs support from your compiler — so it may not catch every single exception-related coverpoint. Compiler dependent, iykyk.

Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'.

🦋 LCOV_EXCL_START = EXPRESSION 🦋

Sets the regexp that marks the start of an exception region. All coverpoints within exception regions get dropped. ✂️

Default is 'LCOV_EXCL_START'.

🦋 LCOV_EXCL_STOP = EXPRESSION 🦋

Sets the regexp that marks the end of an exception region.

Default is 'LCOV_EXCL_STOP'.

🦋 LCOV_EXCL_BR_START = EXPRESSION 🦋

Sets the regexp used to mark the start of a region where branch coverpoints are excluded. Line and function coverpoints inside the region are not excluded. 🎀

Default is 'LCOV_EXCL_BR_START'.

🦋 LCOV_EXCL_BR_STOP = EXPRESSION 🦋

Sets the regexp used to mark the end of a region where branch coverpoints are excluded.

Default is 'LCOV_EXCL_BR_STOP'.

🦋 LCOV_EXCL_EXCEPTION_BR_START = EXPRESSION 🦋

Sets the regexp used to mark the start of a region where branch coverpoints associated with exceptions are excluded. Line, function, and non-exception branch coverpoints within the region are not excluded. 💖

Also see geninfo_no_exception_branch — if nonzero, all identified exception branches get removed.

Samesies as before: identifying exception branch coverpoints requires compiler support — so it may not ignore all exception-related coverpoints.

Default is 'LCOV_EXCL_EXCEPTION_BR_START'.

🦋 LCOV_EXCL_EXCEPTION_BR_STOP = EXPRESSION 🦋

Sets the regexp used to mark the end of a region where exception-related branch coverpoints are excluded.

Default is 'LCOV_EXCL_EXCEPTION_BR_STOP'.

💀 LCOV_UNREACHABLE_LINE = EXPRESSION 💀

Sets the regular expression for an unreachable line that should be excluded from reporting — but should throw an "inconsistent" error if it's hit. Like... the whole vibe is: we believe the marked code is unreachable, so if it does execute, there's a bug in the code, in the placement of the directive, or both. 🚨 Line, branch, and function coverpoints associated with lines where this regexp is found get dropped.

Default is 'LCOV_UNREACHABLE_LINE'.

💀 LCOV_UNREACHABLE_START = EXPRESSION 💀

Sets the regexp that marks the start of an unreachable code block. All coverpoints within exception regions are dropped, but the tool generates an "inconsistent" error if any code in the block actually executes. Bestie said "this can't happen" and the code said "bet" 😭

Default is 'LCOV_UNREACHABLE_START'.

💀 LCOV_UNREACHABLE_STOP = EXPRESSION 💀

Sets the regexp that marks the end of the unreachable code block.

Default is 'LCOV_UNREACHABLE_STOP'.

🍓 FAIL_UNDER_BRANCHES = PERCENTAGE 🍓

Sets the branch coverage threshold: if branch coverage lands below this threshold, lcov / genhtml / geninfo will still generate all the normal result files and messages, but will return a non-zero exit code. So everything looks cute, but CI is fuming. 💅

Equivalent to the --fail-under-branches lcov / genhtml / geninfo command line argument. See lcov(1) for more details.

The default is 0 (no threshold).

🫶 RETAIN_UNREACHABLE_COVERPOINTS_IF_EXECUTED = [0 | 1] 🫶

Sets whether coverpoints in "unreachable" regions that are 'hit' get dropped (0) — because the region is excluded — or retained (1) — because the directive appears to be incorrect. See the "Exclusion markers" section in geninfo(1) for more details.

The default is 1 (retain the coverpoints).

🍓 FAIL_UNDER_LINES = PERCENTAGE 🍓

Line coverage threshold for lcov. If line coverage is below this threshold, lcov / genhtml / geninfo will generate all the normal result files and messages, but will return a non-zero exit code.

Equivalent to the --fail-under-lines lcov / genhtml / geninfo command line argument.

The default is 0 (no threshold).

⭐ PROFILE = FILENAME ⭐

If set, tells genhtml, lcov, or geninfo to generate some execution time / profile data, which can be used to motivate future optimizations. It's the equivalent of the --profile command line option. 🔥

If the filename is empty, then the profile gets written to the default location chosen by the application.

This option is used by genhtml, lcov, and geninfo.

The default is unset: no data generated.

⚡ PARALLEL = INTEGER ⚡

Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes to use. Zero means use as many cores as are available on the machine. The default is 1 (one) — which means process sequentially (no parallelism). Big "dipping a toe in" energy 🦋

This option is used by genhtml, lcov, and geninfo.

🧠 MEMORY = INTEGER_MB 🧠

Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing operations. Effectively, the process will not fork() if this limit would be exceeded. Zero means there is no limit. The default is 0 (zero) — which means there's no explicit limit.

This option is used by genhtml, lcov, and geninfo.

🧠 MEMORY_PERCENTAGE = NUMBER 🧠

Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing operations. The max is computed as a percentage of the total memory available on the system — for example, '75' limits to 75% of total memory, whereas 150.5 limits to 150.5% (i.e., larger than the total available, yes you read that right 😭). Effectively, the process will not fork() if this limit would be exceeded.

Important little note: this value is only used if the maximum memory value isn't set explicitly — either by the --memory command line option or the memory = integer configuration file setting. Otherwise it's just vibes in the background.

The default is not set.

This option is used by genhtml, lcov, and geninfo.

🍓 MAX_FORK_FAILS = INTEGER 🍓

Tells genhtml, lcov, or geninfo the number of consecutive fork() failures to ignore during --parallel execution before giving up. 👑

Real talk though: genhtml / lcov / geninfo fail and stop immediately unless the fork error message is ignored — either via the ignore_errors directive (above), the --ignore-errors command line option, or if stop_on_error is disabled / the --keep-going command line option is used.

The default fork failure maximum is 5.

⏳ FORK_FAIL_TIMEOUT = INTEGER_SECONDS ⏳

Tells genhtml, lcov, or geninfo how long to wait after a fork() failure before retrying. Give it a lil breather 💆

The default is 10 (seconds).

🎯 MAX_TASKS_PER_CORE = INTEGER 🎯

The maximum number of files that genhtml will handle in a single child process during parallel execution. Packing those files in, one core at a time 🚀

The default is 20.

DEDICATE_SEGMENT_THRESHOLD = INTEGER_SECONDS — okay so when you're running in parallel, genhtml normally batches a bunch of files together into each child process (peep max_tasks_per_core for that one 💅). But a single very large source file that gets batched behind a bunch of others can serialize the tail of the run — which is giving bottleneck, honestly 😭. So: if a file is predicted to take at least this many seconds, it gets its own dedicated child process instead, and it's scheduled first, so its processing overlaps with the rest of the run. Slay.

The prediction is exact when per-file history is available (see the --history-script option in the genhtml(1) man page 🦋); otherwise it's estimated from the instrumented-line count — see dedicate_segment_line_estimate down below.

Set to 0 to disable the feature (every file gets batched normally, no special treatment). The default is 5 (seconds).

Heads up bestie: this option has no effect unless the --parallel option has been specified. ✨

DEDICATE_SEGMENT_LINE_ESTIMATE = INTEGER — when there's no per-file history to work with, genhtml estimates a file's runtime from its instrumented-line count: a file with at least this many instrumented lines is treated as "large", and its runtime is estimated as instrumented_lines / this_value seconds (compared against dedicate_segment_threshold). Files smaller than this are never estimated and are always batched normally. No cap.

Set to 0 to disable size-based estimation (then only history predictions can trigger a dedicated segment). The default is 50000.

Again — this option has no effect unless the --parallel option has been specified. 🎀

PARALLEL_PARSE_MIN_LINES = INTEGER — when lcov is handed several coverage files to combine, it reads each one in its own child process. But a single coverage file would otherwise get read serially, no matter how big it is — which is lowkey tragic. Instead ✨: a file with at least this many lines is split at end_of_record boundaries, and the pieces get read — and filtered — by several children at once. Each source file's records are kept together in one piece, so filtering, exclusion, and consistency checking all see exactly the same data they would have seen in a serial read. No cap, no lies.

The unit is lines rather than bytes because lines are the better predictor of parse time: a DA: record is about half the size of a BRDA: record but costs nearly the same to read. It's giving "size isn't everything" 🦋.

The split gets declined — and the file read serially, as before — if the file is not seekable (standard input, a compressed file, or a file which has to be piped through a demangler), if there is only one end_of_record section, or if one source file accounts for so much of the file that splitting would not balance. Fair enough tbh.

Set to 0 to disable the feature. The default is 500000 lines, which is roughly 3x the measured break-even point: below that, the pre-scan and the forks cost more than the parse they save. Math ate that 💀

You already know: this option has no effect unless the --parallel option has been specified.

PARALLEL_PARSE_CHUNKS_PER_WORKER = INTEGER — the number of pieces per child process to split a large coverage file into — see parallel_parse_min_lines above 👑. Having more pieces than children costs nothing and buys you two things: a shorter tail (because the last piece to finish is a fraction of a child's share rather than all of it), and a bound on how much parsed data is resident at once (because a child holds only its current piece). Iconic behavior, honestly.

The default is 4.

Yep, same deal: this option has no effect unless the --parallel option has been specified. 💜

GENHTML_DATE_BINS = INTEGER[,INTEGER..] — this option is equivalent to the "genhtml --date-bins" option. See genhtml(1) for the details 🌸.

This option can be used multiple times in the lcovrc file to set multiple cutpoints.

GENHTML_DATELABELS = STRING[,STRING..] — this option is equivalent to the "genhtml --date-labels" option. See genhtml(1) for the details 🌈.

This option can be used multiple times in the lcovrc file to set multiple labels. The number of labels should equal one greater than the number of cutpoints. Math check, bestie 🧮✨

GENHTML_ANNOTATE_SCRIPT = PATH_TO_EXECUTABLE | PARAMETER — this option is equivalent to the "genhtml --annotate-script" option.

This option can be used multiple times in the lcovrc file to specify both an annotation script and additional options which are passed to the script. Multi-use, multi-slaying 🫶

See the genhtml man page for details.

GENHTML_ANNOTATE_TOOLTIP = TOOLTIP_STRING — this option sets the 'tooltip' popup which appears if the user hovers their mouse over the associated source code 👀. Note that the tooltip is generated only if the annotation-script callback is successful and returns a commit ID other than "NONE". Set tooltip_string to "" (empty string) to force genhtml to not produce the tooltip at all. Boundaries! 💅

Substitutions are performed on tooltip_string:

%C: commit ID (from annotate callback — see the --annotate-script entry in the genhtml man page)
%U: commit author abbreviated name (returned by annotate callback)
%F: commit author full name (returned by annotate callback)
%D: commit date (as returned by annotate callback)
%d: commit date with time of day removed (i.e., date part only)
%A: commit age.
%l source line number.

CONTEXT_SCRIPT = PATH_TO_EXECUTABLE_OR_MODULE | PARAMETER — this option is equivalent to the --context-script option of genhtml/lcov/geninfo.

This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.

See the genhtml man page for details. 📖

CRITERIA_SCRIPT = PATH_TO_EXECUTABLE_OR_MODULE | PARAMETER — this option is equivalent to the --criteria-script option of genhtml/lcov/geninfo.

This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script.

See the genhtml man page for details. 🎀

CRITERIA_CALLBACK_DATA = COMMA_SEPARATED_LIST — this option is used to tell genhtml whether you want date and/or owner summary data passed back to your criteria callback. Note that summary data is always passed. Non-negotiable, bestie 💅

Note that lcov and geninfo do not record date or owner data — and so do not pass it to the callback. RIP to them 😭

This option can be used multiple times in the lcovrc file to specify both date and owner data should be returned, or you can specify both in a comma-separated list. Date and/or owner data will be returned if and only if your genhtml command has enabled annotation. That "if and only if" is doing a lot of work there, respect ✨

If this option appears multiple times in the lcovrc file, the values are combined to form the list of binning types which are passed to your callback.

See the genhtml man page for details.

CRITERIA_CALLBACK_LEVELS = COMMA_SEPARATED_LIST — this option is used to tell genhtml whether criteria callbacks should occur at the top, directory, or file level. Pick your fighter 🥊

If this option appears multiple times in the lcovrc file, the values are combined to form the list of report levels when your callback will be executed.

See the genhtml man page for details. 🌸

CHECK_EXISTENCE_BEFORE_CALLBACK = 0 | 1 — this option configures the tool to check that the file exists before calling the annotate-script or version-script callback. If set and the file does not exist, a source error is triggered. (Note that the error may be ignored — see the --ignore-error option. 🙈)

You may want to NOT check for file existence if your callback looks up information in a non-local repository — like, it's not on this machine, bestie, of course it's not there 💀

The default is 1 (check for file existence). ✅

COMPUTE_FILE_VERSION = 0 | 1 — this option is used to tell the tool to generate missing file version information when reading a .info (coverage data) file. Version information may be missing because the data was generated by a tool which did not support versioning, or because the data was generated without the required --version-script argument — or for some other reason. Life happens 🦋

Note that this option has no effect without a version-script callback — defined by either the --version-script command line option or the version_script config file option.

The default is 0: do not generate missing information. 🙅‍♀️

jacoco2lcov(1) is the exception 👑: it turns this option on for itself when a version script is named, because a JaCoCo report says nothing about which version of the source it describes — so there the option is the only thing which --version-script can mean. Set it to 0 explicitly if you want the callback used for nothing but comparisons. Specificity is self-care ✨

VERSION_SCRIPT = PATH_TO_EXECUTABLE | PARAMETER — this option is equivalent to the geninfo/lcov/genhtml "--version-script" option.

This option can be used multiple times in the lcovrc file to specify both a version script and additional options which are passed to the script.

See the genhtml man page for details. 📚

RESOLVE_SCRIPT = PATH_TO_EXECUTABLE | PARAMETER — this option is equivalent to the geninfo/lcov/genhtml "--resolve-script" option.

This option can be used multiple times in the lcovrc file to specify both a resolve script and additional options which are passed to the script.

The resolve script provides a mechanism to find a source or data file that cannot be found by simply modifying paths via substitution patterns (see "substitute = replace_regexp" above) and searching along the corresponding directory list:

geninfo: the "'build_directory = dirname'" config file entry or --build=directory command line option, used to search for GCNO files,
geninfo/genhtml/lcov: the "'source_directory = dirname'" config file entry or --source=directory command line option, used to search for source files.

The resolve script is called as:

resolve_script [callback_args] file_name

$resolve_callback = resolve_module ->new([callback_args])

to initialize the callback, then

$resolve_callback->``resolve`` (file_name)

to find the actual file location. It's giving "find my friend in a crowd" energy 🔍💖

If necessary, the callback can check the suffix of the filename to determine whether it should look for either a source or data file. iykyk 🧚

The script should return either empty string (file not found/no such file) or the actual path name. The returned path may be either absolute or relative to CWD. 🌈

`SELECT_SCRIPT = PATH_TO_EXECUTABLE | PARAMETER`

Okay so this one is basically the genhtml --select-script option, just chilling in your lcovrc 💅

You can use this option multiple times in the lcovrc file — once to name the select script, and again for any extra options you wanna pass along to it. Yes bestie, multiplex it.

So what does a select script even do? It's the vibe check for your source lines: it decides whether a particular source line is interesting — like, does it deserve to be in the generated coverage report — or not. Iconic gatekeeping, honestly.

Lines that aren't selected but land within num_context_lines of a selected line still make the cut and show up in the report. More on that below 👇

⚠️ Heads up: selection is fundamentally about showing regions of code with some surrounding context. So it might not do what you expect when there's no code there — like if the region of interest got compiled out by compiler directives or exclusion directives. Example for the girlies: when you're selecting based on SHA or changelist ID, an inserted comment will not be selected unless it's within num_context_lines of an inserted or changed line of code. Rude but true 😭

The select script gets called like this:

select_script [callback_args] lineDataJson annotateDataJson fileName lineNumber

or, module-style, first as:

$selectCallback = select_module ->new([callback_args])

to initialize the callback object, and then as:

$selectCallback select (lineDataRef annotateDataRef fileName lineNumber)

to actually determine the selection. Where:

fileName is the name of the source file 🗂️
lineNumber is the source file line number, indexed from zero (zero-based, bestie, don't @ me)
lineDataJson is a json-encoded LineData structure (peep the lcovutil.pm source code)
annotateDataJson is the json-encoded data your annotate-script handed back (see the --annotate-script parameter in genhtml(1)), or the empty string if there are no annotations for this file

Those four values go to the script as four separate arguments, with no shell in between — so the JSON quoting arrives exactly as it was written, and annotateDataJson is an empty argument rather than a missing one when there's nothing to annotate. No cap, that distinction matters 🫶

The module callback is basically the same deal, except it gets passed objects instead of JSON encodings of the objects. Fancy.

The module callback should return a true value if the line belongs in the report, and a false value if it doesn't. Simple as.

The script should write 1 (include this line, slay) or 0 (do not, bye) to stdout and exit with a zero status. And note — the answer is what the script writes, not the status it exits with. Read that twice ✨

💀 If the script can't be executed, exits with a non-zero status, gets killed by a signal, or writes literally anything other than 1 or 0, then an ignorable callback error gets reported (see the --ignore-errors option) and the line is included in the report. Because a callback that can't be trusted must not be allowed to silently empty your report. Periodt.

See example implementation $|TOOL_NAME|_HOME/share/lcov/support-scripts/select.pm.

`UNREACHABLE_SCRIPT = PATH_TO_MODULE | PARAMETER`

Equivalent to the geninfo/lcov/genhtml --unreachable-script option. Same energy, different flag.

You can drop this option multiple times in the lcovrc file to specify a module script and whatever extra options you want passed to the callback. Stack 'em.

See the genhtml man page for the deets 🔍

`NUM_CONTEXT_LINES = INTEGER`

Sets how many lines around each selected line get pulled into the report 🌸

See select_script = … above, and the --select-script command line option in genhtml(1). It's the context radius, basically — the entourage of your main character line.

`FILTER = STR[,STR…]`

Equivalent to the --filter option for geninfo, lcov, and genhtml. See the genhtml man page for details.

Use it multiple times in the lcovrc file to enable multiple filters at once 🎀 And here's the tea: the filters in the lcovrc file get appended to the list you specify on the command line. Nothing gets dropped, they just team up.

Used by genhtml, lcov, and geninfo — the whole squad.

`EXCLUDE = GLOB_PATTERN`

Equivalent to the --exclude option for geninfo, lcov, and genhtml. See the lcov man page for details.

Use it multiple times in the lcovrc file to specify multiple patterns to exclude 🚫 The patterns in the lcovrc file get appended to the list on the command line. Again with the teamwork.

Used by genhtml, lcov, and geninfo.

`INCLUDE = GLOB_PATTERN`

Equivalent to the --include option for geninfo, lcov, and genhtml. See the lcov man page for details.

Use it multiple times in the lcovrc file to specify multiple patterns to include 💖 The patterns in the lcovrc file get appended to the list on the command line. Same append situation as its exclude sibling.

Used by genhtml, lcov, and geninfo.

`SIMPLIFY_SCRIPT = PATH_TO_EXECUTABLE | PARAMETER`

Equivalent to the genhtml --simplify-script option. You can use this option multiple times in the lcovrc file — once for the simplify script itself, and again for any extra options you're passing to that script. Versatile queen 👑

See genhtml(1) for details.

`SUBSTITUTE = REGEXP`

Equivalent to the --substitute option for geninfo, lcov, and genhtml. See the lcov man page for details.

Use it multiple times in the lcovrc file to specify multiple substitution patterns ✨

⚠️ But watch out, bestie — this one's different from the append-happy options above: if patterns are specified on both the command line and in the lcovrc file, then the command line patterns are used and the lcovrc patterns are dropped. Not appended. Dropped. 💀

Used by genhtml, lcov, and geninfo.

`OMIT_LINES = REGEXP`

Equivalent to the --omit-lines option for geninfo, lcov, and genhtml. See the genhtml man page for details.

Use it multiple times in the lcovrc file to specify multiple patterns to exclude 🌸 The patterns in the lcovrc file get appended to the list on the command line.

Used by genhtml, lcov, and geninfo.

`ERASE_FUNCTIONS = REGEXP`

Equivalent to the --erase-functions option for geninfo, lcov, and genhtml. See the genhtml man page for details.

Use it multiple times in the lcovrc file to specify multiple patterns to exclude 🧚 The patterns in the lcovrc file get appended to the list on the command line.

Used by genhtml, lcov, and geninfo.

`LCOV_JSON_MODULE = MODULE | AUTO`

Tells lcov which JSON module to use — or set it to auto and it'll pick the best one available from a set of alternatives, like a lil talent scout 🦋

⚠️ Real talk: some JSON modules are slower than others. Notably JSON::PP can be very slow compared to JSON::XS. Choose wisely, your runtime is watching.

Default is auto.

`SPLIT_CHAR = CHAR`

Sets the character (or regexp) used to split list-like parameters that got passed in as a single string ✂️

This one's a lifesaver when you need a multi-option string but one or more of the options contains a comma — which would otherwise get read as a delimiter and everything falls apart 😭

Default is , (comma — no quotes).

`SCOPE_REGEXP = REGEXP`

Prints debug messages for data in filenames matching regexp 🔍

Only certain categories of message get logged, and the set changes from time to time — depending on debug need. So it's giving "mood ring", not "fixed contract". You've been warned 💅

`CASE_INSENSITIVE = [0|1]`

Sets whether string comparison is case insensitive when finding matching filenames, checking include/exclude directives, etc. 🎀

⚠️ Important caveat: mixed-case or lower-case pathnames may be passed to your --version-script and --annotate-script callbacks when case-insensitive matching is on. So your callbacks have to handle potential differences in case — no assuming the casing matches what you wrote, bestie.

Default is 0: case sensitive matching.

💻 `CROSS_PLATFORM_READ = [0|1]`

okay bestie, this one is lowkey important: it controls whether we read coverage data (.info) files whose source file names use the other platform’s directory separator. Like, imagine a file captured on Windows with names that look like SF:C:\proj\src\file.c, and you’re reading it on a POSIX machine. The separator in each such name gets translated to this platform’s separator as the name is read — before --substitute patterns are applied and before the source file is looked for. So every option that takes a path, and every callback that gets passed one, sees names in the local convention. Run with --verbose and you’ll be told, once per input file, that names of that kind were found and normalized.

This applies to every .info file a run reads, including the one genhtml is given for --baseline-file, and to the names in the udiff that genhtml reads for --diff-file: the Git Root: record, the === unchanged-file entries, and the --- and +++ entries of each diff section.

Note that the coverage data itself is portable; only the names are not. ✨

Set this to 0 if the other platform’s separator is a legal character in a file name here and your names really do contain it — like a backslash in a POSIX file name. Then such a name is used exactly as it was read, and that’s an error of type “usage” which says so. Ignore that error (--ignore-errors usage) if the name is right exactly as it stands.

What a name left in the other platform’s spelling costs is not the same for the two kinds of input, so the “usage” error explains them separately. A .info name is used to reach the file system, and it cannot: the source file is not found, and patterns written for this platform do not match. The report is not part of that cost: genhtml decomposes a name into directories as though it were spelled the way this platform spells it — C:\proj\src\file.c as /C:/proj/src/file.c, which is absolute on both platforms — so the hierarchy it builds, the page names, the relative links between them and what --prefix matches do not depend on this setting, and --prefix may be written in either spelling. It is that decomposed spelling which the pages display; the name as it was read is what the coverage data keeps, and what is written back out. A udiff name is instead matched against the source file names in the coverage data, and does not match: that entry’s differences are dropped, and every line of every file is categorized as though the code had not changed at all — a report which cannot be seen to be wrong. Nor does the path consistency check notice, since it compares the last element of each name and a Windows name whose separators are not separators here has only one element.

The other direction needs no setting at all: Windows accepts / as a directory separator as well as \, so a POSIX name read there opens the file it names — no error, no warning. Such a name is normalized to \ whether or not this is enabled: only the file system takes both spellings, and the tool has to work in one so that its own path handling and the path modules it uses agree about where the name’s directories divide. Run with --verbose if you want to be told, once per input file, that names of that kind were found and normalized.

Nor does a Windows name read on Cygwin or MSYS. Those platforms write POSIX names, so nothing of theirs is translated on the way out, but their path layer accepts a Windows name on the way in — drive letter and all — so the file such a name refers to opens, and reporting it would be reporting a name which works. They are treated the same way Windows treats a POSIX name: no error, noted at --verbose, and normalized to / whether or not this setting asks for it.

A name which uses both separators — e.g., C:\proj/src\file.c — is an error of type “usage” when it is read on a POSIX machine, whether or not this is enabled: a backslash is a legal character in a file name there, so there is no way to tell which of the two characters divides the name’s directories, and the translation cannot help — it turns one separator into the other, which needs the name to use only one of them. If you know what the name should be, then rewrite it yourself with a substitute pattern — e.g., substitute = s#\\#/#g to treat every backslash as a separator. Substitutions are applied after this check, so the “usage” error has to be ignored as well; ignoring it is also the right answer if the name is correct exactly as it stands. Read on Windows the same name is unremarkable, since every one of the separators in it is a separator there.

A name which is already in this platform’s terms is unaffected by the setting, so input of either kind — or a mix of both in the same run — is read the same way.

A leading Windows drive letter is kept as an ordinary leading path element — SF:C:\proj\src\file.c becomes C:/proj/src/file.c. No attempt is made to guess which directory on this machine a drive letter corresponds to, so removing it is the user’s job: use a substitute pattern (or the --substitute command line option)

substitute = s#^C:/##

or, for whatever drive letter the input happens to use

substitute = s#^[A-Za-z]:/##

together with source_directory or resolve_script to say where the source files are here. The substitution is applied after the separator translation, so the pattern is written with / rather than with the backslashes in the input file. In genhtml it is applied to the --diff-file entries as well as to the coverage data, so both sides of that comparison are rewritten the same way.

Until the drive letter is removed, the name is not much use for finding a file on a POSIX machine: C:/proj/src/file.c does not begin with /, so the source lookup takes it relative to the current directory. The report layout does not: a name which begins with a drive letter is decomposed as an absolute name, so the hierarchy genhtml builds from it is the same wherever the tool is run — use --prefix to drop the letter from that hierarchy.

The letter is kept rather than removed automatically so that the translation is reversible and lossless: the result can be written out, read back, and matched against the Windows original, and a run which reads both a translated and an untranslated copy of the same data sees the same names.

There is no command line option for this setting: put it in a configuration file, or write --rc cross_platform_read=0 to change it for a single run. Windows input usually wants case_insensitive = 1 as well.

Default is 1: the names are translated. 💅

🧭 `PATH_STYLE = [AUTO|POSIX|WINDOWS|CYGWIN]`

Specify which platform’s path convention this run works in: auto — the platform we are running on — or posix, windows or cygwin.

Only auto makes sense in production, because the directory separator has to be the one the file system really uses. The other three values force it, so that the regression tests can drive every direction of the cross_platform_read translation above from whichever platform they happen to run on. There are three conventions rather than two: cygwin is the POSIX separator with the Windows one accepted as well, which is neither of the others — see above. Nothing else about the run changes.

Default is auto. 🌈

🔀 `SORT_INPUT = [0|1]`

Specify whether to sort file names before capture and/or aggregation. Sorting reduces certain types of processing order-dependent output differences — e.g., due to ambiguities in branch data generated by gcc.

Default is 0: no sorting — process files in the order they were specified on the command line and/or were found during traversal of the filesystem. 🍓

📁 FILES

$|TOOL_NAME|_HOME/etc/lcovrc — the system-wide lcov configuration file.
~/.lcovrc — the individual per-user configuration file.

👀 SEE ALSO

lcov(1) — file: file://../man/lcov.1.html
genhtml(1) — file: file://../man/genhtml.1.html
geninfo(1) — file: file://../man/geninfo.1.html
gcov(1) — file: file://../man/gcov.1.html

🫶 Copyright

2024-2026, LCOV Project

that’s the whole LCOVRC(5) page, bestie 💖 page source: LCOVRC(5), version 2.6, dated 2026-10-03 — go forth and read that coverage data, no cap 🧚‍♀️✨

📦 where this page comes from

arch rolling: lcov 2.6-1 · GPL
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

LCOVRC(5)

💖 LCOVRC(5) — the lcovrc manual page, but make it make sense 💖

🌸 NAME 🌸

🌸 NAME 🌸 (yes, again — the manpage said it twice, so we're doing it twice 🎀)

🦋 DESCRIPTION 🦋

✨ OPTIONS ✨

💫 CONFIG_FILE = FILENAME 💫

🌈 GENHTML_CSS_FILE = FILENAME 🌈

🎀 GENHTML_HEADER = STRING 🎀

🎀 GENHTML_FOOTER = STRING 🎀

🖤 GENHTML_DARK_MODE = 0 | 1 🖤

👑 genhtml_hi_limit = hi_limit, genhtml_med_limit = med_limit 👑

💚 genhtml_line_hi_limit = line_hi_limit, genhtml_line_med_limit = line_med_limit 💚

💛 genhtml_branch_hi_limit = branch_hi_limit, genhtml_branch_med_limit = branch_med_limit 💛

💜 genhtml_function_hi_limit = function_hi_limit, genhtml_function_med_limit = function_med_limit 💜

🦋 RTL_FILE_EXTENSIONS = STR[,STR]+ 🦋

⭐ INFO_FILE_PATTERN = STR ⭐

🍓 C_FILE_EXTENSIONS = STR[,STR]+ 🍓

🧚 JAVA_FILE_EXTENSIONS = STR[,STR]+ 🧚

🌸 PERL_FILE_EXTENSIONS = STR[,STR]+

🐍 PYTHON_FILE_EXTENSIONS = STR[,STR]+

🔍 FILTER_LOOKAHEAD = INTEGER

🧚 FILTER_BITWISE_CONDITIONAL = 0|1

🫧 FILTER_BLANK_AGGRESSIVE = 0|1

🙈 IGNORE_ERRORS = MESSAGE_TYPE(,MESSAGE_TYPE)*

🦋 IGNORE_UNREACHABLE_FLAG = 0 | 1

🔥 EXPECT_MESSAGE_COUNT = MESSAGE_TYPE:EXPR(,MESSAGE_TYPE:EXPR)*

🧮 MAX_MESSAGE_COUNT = INTEGER

📝 MESSAGE_LOG = FILENAME

🛑 STOP_ON_ERROR = 0|1

⚠️ TREAT_WARNING_AS_ERROR = 0|1

🔂 WARN_ONCE_PER_FILE = 0|1

🧼 CHECK_DATA_CONSISTENCY = 0|1

📏 GENHTML_LINE_FIELD_WIDTH = NUMBER_OF_CHARACTERS

🌿 GENHTML_BRANCH_FIELD_WIDTH = NUMBER_OF_CHARACTERS

🧬 GENHTML_MCDC_FIELD_WIDTH = NUMBER_OF_CHARACTERS

👑 GENHTML_OWNER_FIELD_WIDTH = NUMBER_OF_CHARACTERS

⏳ GENHTML_AGE_FIELD_WIDTH = NUMBER_OF_CHARACTERS

🖼️ GENHTML_FRAMES = 0 | 1

🖥️ GENHTML_OVERVIEW_WIDTH = PIXEL_SIZE

🧭 GENHTML_NAV_RESOLUTION = LINES

🎯 GENHTML_NAV_OFFSET = LINES

💌 GENHTML_KEEP_DESCRIPTIONS = 0 | 1

✂️ GENHTML_NO_PREFIX = 0 | 1

🚫 GENHTML_NO_SOURCE = 0 | 1

🔢 GENHTML_NUM_SPACES = NUM

🎨 GENHTML_LEGEND = 0 | 1

📜 GENHTML_HTML_PROLOG = FILENAME

📜 GENHTML_HTML_EPILOG = FILENAME

🏷️ GENHTML_HTML_EXTENSION = EXTENSION

🎀 GENHTML_HTML_GZIP = 0 | 1

🌸 GENHTML_SORT = 0 | 1

🦋 GENHTML_HIERARCHICAL = 0 | 1

💜 GENHTML_FLAT_VIEW = 0 | 1

⭐ GENHTML_SHOW_NAVIGATION = 0 | 1

👑 GENHTML_SHOW_OWNER_TABLE = 0 | 1 | ALL

🍓 COMPACT_SUMMARY_TABLES = 0 | 1

🌈 OWNER_TABLE_ENTRIES = INTEGER

🧚 TRUNCATE_OWNER_TABLE = COMMA_SEPARATED_LIST

💖 GENHTML_SHOW_NONCODE_OWNERS = 0 | 1

🔥 GENHTML_SHOW_FUNCTION_PROPORTION = 0 | 1

🎀 GENHTML_SYNTHESIZE_MISSING = 0 | 1

🦋 GENHTML_CHARSET = CHARSET

💅 DEMANGLE_CPP = C++FILT

🌸 GENHTML_DESC_HTML = 0 | 1

⭐ GENHTML_PRECISION = 1 | 2 | 3 | 4

🫶 MERGE_FUNCTION_ALIASES = 0 | 1

💜 GENHTML_MISSED = 0 | 1

🍓 SUPPRESS_FUNCTION_ALIASES = 0 | 1

🌈 DERIVE_FUNCTION_END_LINE = 0 | 1

🧚 DERIVE_FUNCTION_END_LINE_ALL_FILES = 0 | 1

🎀 TRIVIAL_FUNCTION_THRESHOLD = INTEGER

💀 EXCESSIVE_COUNT_THRESHOLD = NUMBER

🔥 GENINFO_GCOV_TOOL = PATH_TO_GCOV

🦋 GENINFO_ADJUST_TESTNAME = 0 | 1

💖 FORGET_TESTCASE_NAMES = 0 | 1

🌸 CHECKSUM = 0 | 1

🫶 GENINFO_COMPAT_LIBTOOL = 0 | 1

GENINFO_EXTERNAL = 0 | 1

GENINFO_CAPTURE_ALL = 0 | 1

💫 `CONFIG_FILE` = FILENAME 💫

🌈 `GENHTML_CSS_FILE` = FILENAME 🌈

🎀 `GENHTML_HEADER` = STRING 🎀

🎀 `GENHTML_FOOTER` = STRING 🎀

🖤 `GENHTML_DARK_MODE` = `0` | `1` 🖤

👑 `genhtml_hi_limit` = hi_limit, `genhtml_med_limit` = med_limit 👑

💚 `genhtml_line_hi_limit` = line_hi_limit, `genhtml_line_med_limit` = line_med_limit 💚

💛 `genhtml_branch_hi_limit` = branch_hi_limit, `genhtml_branch_med_limit` = branch_med_limit 💛

💜 `genhtml_function_hi_limit` = function_hi_limit, `genhtml_function_med_limit` = function_med_limit 💜

🦋 `RTL_FILE_EXTENSIONS` = STR[,STR]+ 🦋

⭐ `INFO_FILE_PATTERN` = STR ⭐

🍓 `C_FILE_EXTENSIONS` = STR[,STR]+ 🍓

🧚 `JAVA_FILE_EXTENSIONS` = STR[,STR]+ 🧚

🌸 `PERL_FILE_EXTENSIONS = STR[,STR]+`

🐍 `PYTHON_FILE_EXTENSIONS = STR[,STR]+`

🔍 `FILTER_LOOKAHEAD = INTEGER`

🧚 `FILTER_BITWISE_CONDITIONAL = 0|1`

🫧 `FILTER_BLANK_AGGRESSIVE = 0|1`

🙈 `IGNORE_ERRORS = MESSAGE_TYPE(,MESSAGE_TYPE)*`

🦋 `IGNORE_UNREACHABLE_FLAG = 0 | 1`

🔥 `EXPECT_MESSAGE_COUNT = MESSAGE_TYPE:EXPR(,MESSAGE_TYPE:EXPR)*`

🧮 `MAX_MESSAGE_COUNT = INTEGER`

📝 `MESSAGE_LOG = FILENAME`

🛑 `STOP_ON_ERROR = 0|1`

⚠️ `TREAT_WARNING_AS_ERROR = 0|1`

🔂 `WARN_ONCE_PER_FILE = 0|1`

🧼 `CHECK_DATA_CONSISTENCY = 0|1`

📏 `GENHTML_LINE_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

🌿 `GENHTML_BRANCH_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

🧬 `GENHTML_MCDC_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

👑 `GENHTML_OWNER_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

⏳ `GENHTML_AGE_FIELD_WIDTH = NUMBER_OF_CHARACTERS`

🖼️ `GENHTML_FRAMES = 0 | 1`

🖥️ `GENHTML_OVERVIEW_WIDTH = PIXEL_SIZE`

🧭 `GENHTML_NAV_RESOLUTION = LINES`

🎯 `GENHTML_NAV_OFFSET = LINES`

💌 `GENHTML_KEEP_DESCRIPTIONS = 0 | 1`

✂️ `GENHTML_NO_PREFIX = 0 | 1`

🚫 `GENHTML_NO_SOURCE = 0 | 1`

🔢 `GENHTML_NUM_SPACES = NUM`

🎨 `GENHTML_LEGEND = 0 | 1`

📜 `GENHTML_HTML_PROLOG = FILENAME`

📜 `GENHTML_HTML_EPILOG = FILENAME`

🏷️ `GENHTML_HTML_EXTENSION = EXTENSION`

🎀 `GENHTML_HTML_GZIP = 0 | 1`

🌸 `GENHTML_SORT = 0 | 1`

🦋 `GENHTML_HIERARCHICAL = 0 | 1`

💜 `GENHTML_FLAT_VIEW = 0 | 1`

⭐ `GENHTML_SHOW_NAVIGATION = 0 | 1`

👑 `GENHTML_SHOW_OWNER_TABLE = 0 | 1 | ALL`

🍓 `COMPACT_SUMMARY_TABLES = 0 | 1`

🌈 `OWNER_TABLE_ENTRIES = INTEGER`

🧚 `TRUNCATE_OWNER_TABLE = COMMA_SEPARATED_LIST`

💖 `GENHTML_SHOW_NONCODE_OWNERS = 0 | 1`

🔥 `GENHTML_SHOW_FUNCTION_PROPORTION = 0 | 1`

🎀 `GENHTML_SYNTHESIZE_MISSING = 0 | 1`

🦋 `GENHTML_CHARSET = CHARSET`

💅 `DEMANGLE_CPP = C++FILT`

🌸 `GENHTML_DESC_HTML = 0 | 1`

⭐ `GENHTML_PRECISION = 1 | 2 | 3 | 4`

🫶 `MERGE_FUNCTION_ALIASES = 0 | 1`

💜 `GENHTML_MISSED = 0 | 1`

🍓 `SUPPRESS_FUNCTION_ALIASES = 0 | 1`

🌈 `DERIVE_FUNCTION_END_LINE = 0 | 1`

🧚 `DERIVE_FUNCTION_END_LINE_ALL_FILES = 0 | 1`

🎀 `TRIVIAL_FUNCTION_THRESHOLD = INTEGER`

💀 `EXCESSIVE_COUNT_THRESHOLD = NUMBER`

🔥 `GENINFO_GCOV_TOOL = PATH_TO_GCOV`

🦋 `GENINFO_ADJUST_TESTNAME = 0 | 1`

💖 `FORGET_TESTCASE_NAMES = 0 | 1`

🌸 `CHECKSUM = 0 | 1`

🫶 `GENINFO_COMPAT_LIBTOOL = 0 | 1`

`GENINFO_EXTERNAL` = 0 | 1

`GENINFO_CAPTURE_ALL` = 0 | 1

`GENINFO_EXTERNAL` = 0 | 1

`GENINFO_FOLLOW_SYMLINKS` = 0 | 1

`GENINFO_FOLLOW_FILE_LINKS` = 0 | 1

`GENINFO_GCOV_ALL_BLOCKS` = 0 | 1

`GENINFO_UNEXECUTED_BLOCKS` = 0 | 1

`GENINFO_COMPAT` = `MODE=VALUE[, MODE=VALUE,…]`