Ubuntu Manpage: lcovrc - lcov configuration file

name
description
options
files
see also

NAME

       lcovrc - lcov configuration file

DESCRIPTION

       The lcovrc file contains configuration information for the lcov code coverage tool (see lcov(1)).

       The  system-wide  configuration  file  is  located at /etc/lcovrc.  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.

       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 multiple --config-file options  are  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.

       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.

       A list of valid statements and their description can be found in section 'OPTIONS' below.

       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: 'genhtml_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 = ^/MY_EXCLUDE_MARKER$
              # 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 = ...'  'include = ...'  , 'substitute = ...'   ,
              'omit_lines = ...'  , erase_functions = ...'  , etc.

       Example configuration:

              #
              # Example LCOV configuration file
              #

              # 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 set, 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

              # list of file extensions which should be treated as C/C++ code
              # (comma-separated list)
              #c_file_extensions = h,c,cpp,hpp

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

              # maxmimum 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

              # 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 '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

              # Highlight lines with converted-only data if non-zero
              genhtml_highlight = 0

              # 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

              # 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

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

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

              # Name of the tool used for demangling C++ function names
              # This argument is deprecated - please use demangle_cpp' instead
              #genhtml_demangle_cpp_tool = c++filt

              # Specify extra parameters to be passed to the demangling tool
              #  this argument is deprecated - use Xlinker-like demangle_cpp
              #  paramter instead
              #genhtml_demangle_cpp_params = ""

              # 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

              # 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

              # Adjust path to source files by removing or changing path
              # components that match the specified pattern (Perl regular
              # expression format)
              #geninfo_adjust_src_path = /tmp/build => /usr/src

              # 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

              # 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

              # 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

              # Ask LCOV to return non-zero exit code if line coverage is
              # below specified threshold percentage.
              lcov_fail_under_lines = 97.5

              # 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
              # 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

              # override line default line exclusion regexp
              #lcov_excl_line = LCOV_EXCL_LINE

              # overide 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 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

OPTIONS

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 ta 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: orange
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.

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'. There is no command
line option equivalent.
This option is used by genhtml and lcov.

filter_lookahead = integer

Specify the maximum number of lines to look at when filtering bogus branch expressions. A larger
number may catch more cases, but will increase execution time.

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 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.

ignore_errors = message_type(,message_type)*

Specify a message type which should be ignored.

This option can be used multiple times in the lcovrc file to ignore multiple message types.

This option is equivalent to the --ignore-errors option to geninfo, genhtml, or lcov. Note that
the lcovrc file message list is not applied (those messages NOT ignored) if the '--ignore-errors'
command line option is specified.
This option is used by genhtml, lcov, and geninfo.

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.

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.

stop_on_error = 0|1

If set to 1, tell the tools to ignore errors and keep going to try to generate a result - however
flawed or incomplete that result might be. Note that ignoring some errors may lead to other
errors.

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).

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

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_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_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_highlight = 0|1

If non-zero, highlight lines with converted-only data in HTML output as generated by genhtml.

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

Default is 0.

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 set, compress all html files using gzip.

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

Default extension is 0.

genhtml_sort = 0|1

If non-zero, create overview pages sorted by coverage rates when generating HTML output using
genhtml.

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 will follow the hierarchical directory structure of the source code.

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

Default is 0.

genhtml_flat_view = 0|1

If non-zero, the top-level HTML table will contain all of the files in the project and there will
be no intermediate directory pages.

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

Default is 0.

genhtml_show_navigation = 0|1

If non-zero, the 'source code' view summary table will contain hyperlinks from the number to the
first source line in the corresponding category ('Hit' or 'Not hit') in the non-differential
coverage report. 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_function_proportion = 0|1

If nonzero, add column to "function coverage detail" table to show the proportion of lines and
branches within the function which are exercised.

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

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 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 diabled).

genhtml_demangle_cpp_tool = path_to_c++filt

Specify the location of the demangle tool (see c++filt(1)) used to convert C++ internal function
names to human readable format for display on the HTML function overview page.

This option is deprecated and will be removed from a future lcov release. Please use demangle_cpp
= path_to_c++filt instead.

genhtml_demangle_cpp_params = parameters

Specify extra parameters to be passed to the demangling tool

Use this option if your environment requires additional parameters such as --no-strip-underscore
for correctly demangling C++ internal function names. See also c++filt(1)).

This argument is deprecated. Please use the Xlinker-like demangle_cpp argument instead.

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.

Default is 1.

genhtml_missed = 0|1

If non-zero, the count of missed lines, functions, or branches is shown as negative numbers in
overview pages.

Default is 0.

suppress_function_aliases = 0|1

If non-zero, do not show aliases in the function detail table. 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 and
--filter trivial options.

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

Default is 1.

trivial_function_threshold = integer

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

Default is 5.

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.

geninfo_checksum = 0|1
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.

The backward compatible geninfo_checksum option is deprecated. Please use checksum instead. The
new option is preferred as it is more clear that the option is used by lcov and genhtml as well as
geninfo,

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

Default is 0.

Note that this options 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

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.

Default is 1.

geninfo_gcov_all_blocks = 0|1

If non-zero, call the gcov tool with option --all-blocks.

Using --all-blocks will produce more detailed branch coverage information for each line. Set this
option to zero if you do not need detailed branch coverage information to speed up the process of
capturing code coverage or to work around a bug in some versions of gcov which will cause it to
endlessly loop when analyzing some files.

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. Assume that these 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,...]

Specify that geninfo should 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'.

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. By providing a pattern in Perl regular expression format (see perlre(1)) and an optional
replacement string, you can instruct geninfo to remove or change parts of the incorrect source
path.

Example:

1. 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.

2. 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".

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.

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. The use of the gcov intermediate format should increase processing
speed. It also provides branch coverage data when using the --initial command line option.

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".

geninfo_no_exception_branch = 0|1
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.

This option is used by lcov, geninfo, genhtml.

The backward compatible geninfo_no_exception_branch option is deprecated. Please use
no_exception_branch instead. The new option is preferred as it is more clear that the option is
used by lcov and genhtml as well as geninfo,

Default is 0.

lcov_gcov_dir = path_to_kernel_coverage_data

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

Default is auto-detection.

lcov_tmp_dir = temp

Specify the location of a directory used for temporary files.

Default is '/tmp'.

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

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

Default is 80.

lcov_list_truncate_max = percentage

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.

Default is 20.

function_coverage = 0|1

Specify whether lcov/geninfo/genhtml should generate, process, and display function coverage data.

Turning off function coverage by setting this option to 0 can sligly reduce memory and CPU time
consumption when lcov is collecting and processing coverage data, as well as reduce the size of
the resulting data files.

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

Backward-compatible RC options lcov_function_coverage and genhtml_function_coverage are supported
but deprecated. Please use the new option instead.

Default is 1.

branch_coverage = 0|1

Specify whether lcov/geninfo should generate, process, and display branch coverage data.

Turning off branch coverage by setting this option to 0 can reduce memory and CPU time consumption
when lcov is collecting and processing coverage data, as well as reduce the size of the resulting
data files.

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

Backward-compatible RC options lcov_branch_coverage and genhtml_branch_coverage are supported but
deprecated. Please use the new option instead.

Default is 0.

lcov_excl_line = expression

Specify the regular expression of lines to exclude. Line, branch, and function coverpoints are
associated with lines where this regexp is found are dropped.

There are at least 2 (moderately) common use cases for custom exclusion markers:
- You are using multiple tools for coverage analysis, each of which has its own directives, and
you don't want to complicate your source code with directives for each of them.
- You want to exclude different regions/different types of code in different contexts - for
example, to ignore or not ignore debug/trace code depending on your team.

Default is 'LCOV_EXCL_LINE'.

lcov_excl_br_line = expression

Specify the regular expression of lines to exclude from branch coverage. Branch coverpoints are
associated with lines where this regexp is found are dropped. (Line and function coverpoints are
not affected.)

Default is 'LCOV_EXCL_BR_LINE'.

lcov_excl_exception_br_line = expression

Specify the regular expression of lines to exclude from exception branch coverage. Exception-
related Branch coverpoints associated with lines where this regexp is found are dropped. (Line,
function coverpoints are not affected. Branch coverpoints which are not associated with
exceptions are also not affected.)

Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be
removed.

Note that this feature requires support from your compiler - and thus may not ignore all
exception-related coverpoints.

Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'.

lcov_excl_start = expression

Specify the regexp mark the start of an exception region All coverpoints within exeption regions
are dropped.

Default is 'LCOV_EXCL_START'.

lcov_excl_stop = expression

Specify the regexp mark the end of an exception region

Default is 'LCOV_EXCL_STOP'.

lcov_excl_br_start = expression

Specify the regexp used to mark the start of a region where branch coverpoints are excluded. Line
and function coverpoints within the region are not excluded.

Default is 'LCOV_EXCL_BR_START'.

lcov_excl_br_stop = expression

Specify 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

Specify 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, then all identified exception branches will be
removed.

Note that exception branch coverpoint identification requires support from your compiler - and
thus may not ignore all exception-related coverpoints.

Default is 'LCOV_EXCL_EXCEPTION_BR_START'.

lcov_excl_exception_br_stop = expression

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

Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'.

lcov_fail_under_lines = percentage

Specify line coverage threshold to lcov. If the line coverage is below this threshold, lcov will
generate all the normal result files and messages, but will return a non-zero exit code.

This option is equivalent to the --fail-under-lines lcov 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. The default is unset no data generated.

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

parallel = integer

Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes to use. Zero means
to use as many cores as are available on the machine. The default is 1 (one) - which means to
process sequentially (no parallelism).

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 that there
is no limit. The default is 0 (zero) - which that there is no explicit limit.

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

genhtml_date_bins = integer[,integer..]

This option is equivalent to the "genhtml --date-bins" option. See the genhtml man page for
details.

This option can be used multiple times in the lcovrc file to set multiple cutpoints. The
cutpoints specified in the lcovrc file are appended to the cutpoints (if any) specified on the
command line.

genhtml_annotate_script = path_to_executable

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.

See the genhtml man page for details.

genhtml_criteria_script = path_to_executable

This option is equivalent to the "genhtml --criteria-script" option.

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.

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.

If this option is 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.

If this option is 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.

version_script = path_to_executable

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.

filter = str[,str...]

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

This option can be used multiple times in the lcovrc file to enable multiple filters. The filters
specified in the lcovrc file are appended to the list specified on the command line.

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

exclude = glob_pattern

This option is equivalent to the --exclude option to geninfo, lcov, and genhtml. See the lcov man
page for details.;

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

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

include = glob_pattern

This option is equivalent to the --include option to geninfo, lcov, and genhtml. See the lcov man
page for details.;

This option can be used multiple times in the lcovrc file to specify multiple patterns to include.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

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

substitute = regexp

This option is equivalent to the --substitute option to geninfo, lcov, and genhtml. See the lcov
man page for details.;

This option can be used multiple times in the lcovrc file to specify multiple substitution
patterns. The patterns specified in the lcovrc file are appended to the list specified on the
command line.

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

omit_lines = regexp

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

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

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

erase_functions = regexp

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

This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude.
The patterns specified in the lcovrc file are appended to the list specified on the command line.

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

lcov_json_module = module|auto

Specify the JSON module to use, or choose best available from a set of alternatives if set to
'auto'. Note that some JSON modules are slower than others (notably JSON::PP can be very slow
compared to JSON::XS).

Default is 'auto'.

split_char = char

Specify the character (or regexp) used to split list-like parameters which have been passed as a
single string. This parameter is useful in the case that you need want to use a multi-option
string but one or more of the options contains a comma character which would otherwise be seen as
a delimiter.

Default is ',' (comma - no quotes).

case_insensitive = [0|1]

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

Note that mixed-case or lower-case pathnames may be passed to your --version-script and
--annotate-script callbacks when case-insensitive matching is used. Your callbacks must handle
potential differences in case.

Default is '0': case sensitive matching.

FILES

       /etc/lcovrc
              The system-wide lcov configuration file.

       ~/.lcovrc
              The individual per-user configuration file.

NAME

DESCRIPTION

OPTIONS

FILES

SEE ALSO