path: root/third_party/lcov/man/lcovrc.5

.TH lcovrc 5 "LCOV 1.7" 2008\-11\-17 "User Manuals"

.SH NAME
lcovrc \- lcov configuration file

.SH DESCRIPTION
The
.I lcovrc
file contains configuration information for the
.B lcov
code coverage tool (see
.BR lcov (1)).
.br

The system\-wide configuration file is located at
.IR /etc/lcovrc .
To change settings for a single user, place a customized copy of this file at
location
.IR ~/.lcovrc .
Where available, command\-line options override configuration file settings.

Lines in a configuration file can either be:
.IP "     *"
empty lines or lines consisting only of white space characters. These lines are
ignored.
.IP "     *"
comment lines which start with a hash sign ('#'). These are treated like empty
lines and will be ignored.
.IP "     *"
statements in the form
.RI ' key " = " value '.
A list of valid statements and their description can be found in
section 'OPTIONS' below.
.PP

.B Example configuration:
.IP
#
.br
# Example LCOV configuration file
.br
#
.br

# External style sheet file
.br
#genhtml_css_file = gcov.css
.br

# Coverage rate limits for line coverage
.br
genhtml_hi_limit = 50
.br
genhtml_med_limit = 15
.br

# Coverage rate limits for function coverage
.br
genhtml_function_hi_limit = 90
.br
genhtml_function_med_limit = 75
.br

# Width of overview image
.br
genhtml_overview_width = 80
.br

# Resolution of overview navigation
.br
genhtml_nav_resolution = 4
.br

# Offset for source code navigation
.br
genhtml_nav_offset = 10
.br

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

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

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

# Specify size of tabs
.br
genhtml_num_spaces = 8
.br

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

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

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

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

# Use custom HTML file extension
.br
#genhtml_html_extension = html
.br

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

# Include sorted overview pages
.br
genhtml_sort = 1
.br

# Include function coverage data display
.br
genhtml_function_coverage = 1
.br

# Location of the gcov tool
.br
#geninfo_gcov_tool = gcov
.br

# Adjust test names if non\-zero
.br
#geninfo_adjust_testname = 0
.br

# Calculate a checksum for each line if non\-zero
.br
geninfo_checksum = 0
.br

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

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

# Location of the insmod tool
.br
lcov_insmod_tool = /sbin/insmod
.br

# Location of the modprobe tool
.br
lcov_modprobe_tool = /sbin/modprobe
.br

# Location of the rmmod tool
.br
lcov_rmmod_tool = /sbin/rmmod
.br

# Location for temporary directories
.br
lcov_tmp_dir = /tmp
.br
.PP

.SH OPTIONS

.BR genhtml_css_file " ="
.I filename
.IP
Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by
.BR genhtml .
During output generation, a copy of this file will be placed in the output
directory.
.br

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

By default, a standard CSS file is generated.
.PP

.BR genhtml_hi_limit "  ="
.I hi_limit
.br
.BR genhtml_med_limit " ="
.I med_limit
.br
.BR genhtml_function_med_limit " ="
.I hi_limit
.br
.BR genhtml_function_med_limit " ="
.I med_limit
.IP
Specify coverage rate limits for classifying file entries. Use this option to
modify the coverage rates (in percent) for line or function 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:
.br

High:   hi_limit  <= rate <= 100        default color: green
.br
Medium: med_limit <= rate < hi_limit    default color: orange
.br
Low:    0         <= rate < med_limit   default color: red
.br

Defaults are 50 and 15 percent for line coverage and 90 and 75 percent for
function coverage.
.PP

.BR genhtml_overview_width " ="
.I pixel_size
.IP
Specify the width (in pixel) of the overview image created when generating HTML
output using the \-\-frames option of
.BR genhtml .
.br

Default is 80.
.PP

.BR genhtml_nav_resolution " ="
.I lines
.IP
Specify the resolution of overview navigation when generating HTML output using
the \-\-frames option of
.BR 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.
.br

Default is 4.
.PP


.BR genhtml_nav_offset " ="
.I lines
.IP
Specify the overview navigation line offset as applied when generating HTML
output using the \-\-frames option of
.BR genhtml.
.br

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

Default is 10.
.PP


.BR genhtml_keep_descriptions " ="
.IR 0 | 1
.IP
If non\-zero, keep unused test descriptions when generating HTML output using
.BR genhtml .
.br

This option corresponds to the \-\-keep\-descriptions option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_no_prefix " ="
.IR 0 | 1
.IP
If non\-zero, do not try to find and remove a common prefix from directory names.
.br

This option corresponds to the \-\-no\-prefix option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_no_source " ="
.IR 0 | 1
.IP
If non\-zero, do not create a source code view when generating HTML output using
.BR genhtml .
.br

This option corresponds to the \-\-no\-source option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_num_spaces " ="
.I num
.IP
Specify the number of spaces to use as replacement for tab characters in the
HTML source code view as generated by
.BR genhtml .
.br

This option corresponds to the \-\-num\-spaces option of
.BR genthml .
.br

Default is 8.

.PP

.BR genhtml_highlight " ="
.IR 0 | 1
.IP
If non\-zero, highlight lines with converted\-only data in
HTML output as generated by
.BR genhtml .
.br

This option corresponds to the \-\-highlight option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_legend " ="
.IR 0 | 1
.IP
If non\-zero, include a legend explaining the meaning of color coding in the HTML
output as generated by
.BR genhtml .
.br

This option corresponds to the \-\-legend option of
.BR genhtml .
.br

Default is 0.
.PP

.BR genhtml_html_prolog " ="
.I filename
.IP
If set, include the contents of the specified file at the beginning of HTML
output.

This option corresponds to the \-\-html\-prolog option of
.BR genhtml .
.br

Default is to use no extra prolog.
.PP

.BR genhtml_html_epilog " ="
.I filename
.IP
If set, include the contents of the specified file at the end of HTML output.

This option corresponds to the \-\-html\-epilog option of
.BR genhtml .
.br

Default is to use no extra epilog.
.PP

.BR genhtml_html_extension " ="
.I extension
.IP
If set, use the specified string as filename extension for generated HTML files.

This option corresponds to the \-\-html\-extension option of
.BR genhtml .
.br

Default extension is "html".
.PP

.BR genhtml_html_gzip " ="
.IR 0 | 1
.IP
If set, compress all html files using gzip.

This option corresponds to the \-\-html\-gzip option of
.BR genhtml .
.br

Default extension is 0.
.PP

.BR genhtml_sort " ="
.IR 0 | 1
.IP
If non\-zero, create overview pages sorted by coverage rates when generating
HTML output using
.BR genhtml .
.br

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

Default is 1.
.PP

.BR genhtml_function_coverage " ="
.IR 0 | 1
.IP
If non\-zero, include function coverage data when generating HTML output using
.BR genhtml .
.br

This option can be set to 0 by using the \-\-no\-function\-coverage option of
.BR genhtml .
.br

Default is 1.
.PP

.BR geninfo_gcov_tool " ="
.I path_to_gcov
.IP
Specify the location of the gcov tool (see
.BR gcov (1))
which is used to generate coverage information from data files. 
.br

Default is 'gcov'.
.PP

.BR geninfo_adjust_testname " ="
.IR 0 | 1
.IP
If non\-zero,  adjust test names to include operating system information
when capturing coverage data.
.br

Default is 0.
.PP

.BR geninfo_checksum " ="
.IR 0 | 1
.IP
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.
.br

This option corresponds to the \-\-checksum and \-\-no\-checksum command line
option of
.BR geninfo .
.br

Default is 0.
.PP

.BR geninfo_compat_libtool " ="
.IR 0 | 1
.IP
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.
.br

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

Default is 1.
.PP

.BR lcov_gcov_dir " ="
.I path_to_kernel_coverage_data
.IP
Specify the path to the directory where kernel coverage data can be found.
.br

Default is '/proc/gcov'.
.PP

.BR lcov_insmod_tool " ="
.I path_to_insmod
.IP
Specify the location of the insmod tool used to load kernel modules.
.br

Default is '/sbin/insmod'.
.PP

.BR lcov_modprobe_tool " ="
.I path_to_modprobe
.IP
Specify the location of the modprobe tool used to load kernel modules.
.br

Default is '/sbin/modprobe'.
.PP

.BR lcov_rmmod_tool " ="
.I path_to_rmmod
.IP
Specify the location of the rmmod tool used to unload kernel modules.
.br

Default is '/sbin/rmmod'.
.PP

.BR lcov_tmp_dir " ="
.I temp
.IP
Specify the location of a directory used for temporary files.
.br

Default is '/tmp'.
.PP

.SH FILES

.TP
.I /etc/lcovrc
The system\-wide
.B lcov
configuration file.

.TP
.I ~/.lcovrc
The individual per\-user configuration file.
.PP

.SH SEE ALSO
.BR lcov (1),
.BR genhtml (1),
.BR geninfo (1),
.BR gcov (1)