genhtml(1) | User Manuals | genhtml(1) |
NAME¶
genhtml - Generate HTML view from LCOV coverage data files
SYNOPSIS¶
genhtml [-h|--help] [-v|--version]
[-q|--quiet] [-s|--show-details] [-f|--frames]
[-b|--baseline-file] baseline-file
[-o|--output-directory output-directory]
[--header-title banner]
[--footer string]
[-t|--title title]
[-d|--description-file description-file]
[-k|--keep-descriptions] [-c|--css-file css-file]
[-p|--prefix prefix] [--no-prefix]
[--no-source] [--num-spaces num] [--highlight]
[--legend] [--html-prolog prolog-file]
[--html-epilog epilog-file] [--html-extension extension]
[--html-gzip] [--sort] [--no-sort]
[--function-coverage] [--no-function-coverage]
[--branch-coverage] [--no-branch-coverage]
[--demangle-cpp] [--ignore-errors errors]
[--config-file config-file] [--rc keyword=value]
[--precision num] [--missed]
[--dark-mode]
tracefile(s)
DESCRIPTION¶
Create an HTML view of coverage data found in tracefile. Note that tracefile may also be a list of filenames.
HTML output files are created in the current working directory unless the --output-directory option is used. If tracefile ends with ".gz", it is assumed to be GZIP-compressed and the gunzip tool will be used to decompress it transparently.
Note that all source code files have to be present and readable at the exact file system location they were compiled.
Use option --css-file to modify layout and colors of the generated HTML output. Files are marked in different colors depending on the associated coverage rate. By default, the coverage limits for low, medium and high coverage are set to 0-75%, 75-90% and 90-100% percent respectively. To change these values, use configuration file options genhtml_hi_limit and genhtml_med_limit.
Also note that when displaying percentages, 0% and 100% are only printed when the values are exactly 0% and 100% respectively. Other values which would conventionally be rounded to 0% or 100% are instead printed as nearest non-boundary value. This behavior is in accordance with that of the gcov(1) tool.
OPTIONS¶
-h
--help
--version
--quiet
Suppresses all informational progress output. When this switch is enabled, only error or warning messages are printed.
--frames
If enabled, a frameset is created for each source code file, providing an overview of the source code as a "clickable" image. Note that this option will slow down output creation noticeably because each source code character has to be inspected once. Note also that the GD.pm Perl module has to be installed for this option to work (it may be obtained from http://www.cpan.org).
--show-details
When this option is enabled, genhtml generates two versions of each file view. One containing the standard information plus a link to a "detailed" version. The latter additionally contains information about which test case covered how many lines of each source file.
--baseline-file baseline-file
The tracefile specified by baseline-file is read and all counts found in the original tracefile are decremented by the corresponding counts in baseline-file before creating any output.
Note that when a count for a particular line in baseline-file is greater than the count in the tracefile, the result is zero.
--output-directory output-directory
Use this option to tell genhtml to write the resulting files to a directory other than the current one. If output-directory does not exist, it will be created.
It is advisable to use this option since depending on the project size, a lot of files and subdirectories may be created.
--title title
title is written to the "Test:"-field in the header table at the top of each generated HTML page to identify the context in which a particular output was created. By default this is the name of the tracefile.
A potential use is to specify a test run name, or a version control system identifier that indicates the code level that was tested.
BANNER is written to the header portion of each generated HTML page. By default this simply identifies this as an LCOV coverage report.
A potential use is to specify the name of the project or project branch and build ID.
FOOTER is written to the footer portion of each generated HTML page. The default simply identifies the LCOV tool version used to generate the report.
--description-file description-file
All test case descriptions found in description-file and referenced in the input data file are read and written to an extra page which is then incorporated into the HTML output.
The file format of description-file is:
for each test case:
TD:<test description>
Valid test case names can consist of letters, numbers and the underscore character ('_').
--keep-descriptions
Keep descriptions found in the description file even if the coverage data indicates that the associated test case did not cover any lines of code.
This option can also be configured permanently using the configuration file option genhtml_keep_descriptions.
--css-file css-file
Using this option, an extra .css file may be specified which will replace the default one. This may be helpful if the default colors make your eyes want to jump out of their sockets :)
This option can also be configured permanently using the configuration file option genhtml_css_file.
--prefix prefix
Because lists containing long filenames are difficult to read, there is a mechanism implemented that will automatically try to shorten all directory names on the overview page beginning with a common prefix. By default, this is done using an algorithm that tries to find the prefix which, when applied, will minimize the resulting sum of characters of all directory names.
Use this option to specify the prefix to be removed by yourself.
This switch will completely disable the prefix mechanism described in the previous section.
This option can also be configured permanently using the configuration file option genhtml_no_prefix.
Use this switch if you don't want to get a source code view for each file.
This option can also be configured permanently using the configuration file option genhtml_no_source.
Default value is 8.
This option can also be configured permanently using the configuration file option genhtml_num_spaces.
Use this option in conjunction with the --diff option of lcov to highlight those lines which were only covered in data sets which were converted from previous source code versions.
This option can also be configured permanently using the configuration file option genhtml_highlight.
Use this option to include a legend explaining the meaning of color coding in the resulting HTML output.
This option can also be configured permanently using the configuration file option genhtml_legend.
Use this option to replace the default HTML prolog (the initial part of the HTML source code leading up to and including the <body> tag) with the contents of prolog-file. Within the prolog text, the following words will be replaced when a page is generated:
@pagetitle@
The title of the page.
@basedir@
A relative path leading to the base directory (e.g. for locating
css-files).
This option can also be configured permanently using the configuration file option genhtml_html_prolog.
Use this option to replace the default HTML epilog (the final part of the HTML source including </body>) with the contents of epilog-file.
Within the epilog text, the following words will be replaced when a page is generated:
@basedir@
A relative path leading to the base directory (e.g. for locating
css-files).
This option can also be configured permanently using the configuration file option genhtml_html_epilog.
This option is useful in situations where different filename extensions are required to render the resulting pages correctly (e.g. php). Note that a '.' will be inserted between the filename and the extension specified by this option.
This option can also be configured permanently using the configuration file option genhtml_html_extension.
--html-gzip
Use this option if you want to save space on your webserver. Requires a webserver with .htaccess support and a browser with support for gzip compressed html.
This option can also be configured permanently using the configuration file option genhtml_html_gzip.
--no-sort
Use --sort to include sorted views or --no-sort to not include them. Sorted views are enabled by default.
When sorted views are enabled, each overview page will contain links to views of that page sorted by coverage rate.
This option can also be configured permanently using the configuration file option genhtml_sort.
--no-function-coverage
Use --function-coverage to enable function coverage summaries or --no-function-coverage to disable it. Function coverage summaries are enabled by default
When function coverage summaries are enabled, each overview page will contain the number of functions found and hit per file or directory, together with the resulting coverage rate. In addition, each source code view will contain a link to a page which lists all functions found in that file plus the respective call count for those functions.
This option can also be configured permanently using the configuration file option genhtml_function_coverage.
--no-branch-coverage
Use --branch-coverage to enable branch coverage display or --no-branch-coverage to disable it. Branch coverage data display is enabled by default
When branch coverage display is enabled, each overview page will contain the number of branches found and hit per file or directory, together with the resulting coverage rate. In addition, each source code view will contain an extra column which lists all branches of a line with indications of whether the branch was taken or not. Branches are shown in the following format:
' + ': Branch was taken at least once
' - ': Branch was not taken
' # ': The basic block containing the branch was never executed
Note that it might not always be possible to relate branches to the corresponding source code statements: during compilation, GCC might shuffle branches around or eliminate some of them to generate better code.
This option can also be configured permanently using the configuration file option genhtml_branch_coverage.
Use this option if you want to convert C++ internal function names to human readable format for display on the HTML function overview page. This option requires that the c++filt tool is installed (see c++filt(1)).
Use this option to specify a list of one or more classes of errors after which geninfo should continue processing instead of aborting.
errors can be a comma-separated list of the following keywords:
source: the source code file for a data set could not be found.
--config-file config-file
When this option is specified, neither the system-wide configuration file /etc/lcovrc, nor the per-user configuration file ~/.lcovrc is read.
This option may be useful when there is a need to run several instances of genhtml with different configuration file options in parallel.
--rc keyword=value
Use this option to specify a keyword=value statement which overrides the corresponding configuration statement in the lcovrc configuration file. You can specify this option more than once to override multiple configuration statements. See lcovrc(5) for a list of available keywords and their meaning.
--precision num
Default value is 1.
This option can also be configured permanently using the configuration file option genhtml_precision.
--missed
Use this option to change overview pages to show the count of lines, functions, or branches that were not hit. These counts are represented by negative numbers.
When specified together with --sort, file and directory views will be sorted by missed counts.
This option can also be configured permanently using the configuration file option genhtml_missed.
--dark-mode
The idea is to reduce eye strain due to viewing dark text on a bright screen - particularly at night.
FILES¶
/etc/lcovrc
~/.lcovrc
AUTHOR¶
Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
SEE ALSO¶
lcov(1), lcovrc(5), geninfo(1), genpng(1), gendesc(1), gcov(1)
LCOV 1.16 | 2022-06-06 |