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]
[-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]
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-15%, 15-50% and 50-100% percent
respectively. To change these values, use configuration file options
genhtml_hi_limit and genhtml_med_limit.
OPTIONS
-h
--help
Print a short help text, then exit.
-v
--version
Print version number, then exit.
-q
--quiet
Do not print progress messages.
Suppresses all informational progress output. When this switch
is enabled, only error or warning messages are printed.
-f
--frames
Use HTML frames for source code view.
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).
-s
--show-details
Generate detailed directory view.
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.
-b baseline-file
--baseline-file baseline-file
Use data in baseline-file as coverage baseline.
The tracefile specified by baseline-file is read and all counts
found in the original tracefile are decremented by the corre-
sponding 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.
-o output-directory
--output-directory output-directory
Create files in 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.
-t title
--title title
Display title in header of all pages.
title is written to the header portion 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.
-d description-file
--description-file description-file
Read test case descriptions from description-file.
All test case descriptions found in description-file and refer-
enced 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:
TN:<testname>
TD:<test description>
Valid test case names can consist of letters, numbers and the
underscore character ('_').
-k
--keep-descriptions
Do not remove unused test 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 con-
figuration file option genhtml_keep_descriptions.
-c css-file
--css-file css-file
Use external style sheet 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 con-
figuration file option genhtml_css_file.
-p prefix
--prefix prefix
Remove prefix from all directory names.
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 mini-
mize the resulting sum of characters of all directory names.
Use this option to specify the prefix to be removed by your-
self.
--no-prefix
Do not remove prefix from directory names.
This switch will completely disable the prefix mechanism
described in the previous section.
This option can also be configured permanently using the con-
figuration file option genhtml_no_prefix.
--no-source
Do not create source code view.
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 con-
figuration file option genhtml_no_source.
--num-spaces spaces
Replace tabs in source view with num spaces.
Default value is 8.
This option can also be configured permanently using the con-
figuration file option genhtml_num_spaces.
--highlight
Highlight lines with converted-only coverage data.
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 con-
figuration file option genhtml_highlight.
--legend
Include color legend in HTML output.
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 con-
figuration file option genhtml_legend.
--html-prolog prolog-file
Read customized HTML prolog from prolog-file.
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 pro-
log 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 locat-
ing css-files).
This option can also be configured permanently using the con-
figuration file option genhtml_html_prolog.
--html-epilog epilog-file
Read customized HTML epilog from epilog-file.
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 locat-
ing css-files).
This option can also be configured permanently using the con-
figuration file option genhtml_html_epilog.
--html-extension extension
Use customized filename extension for generated HTML pages.
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 file-
name and the extension specified by this option.
This option can also be configured permanently using the con-
figuration file option genhtml_html_extension.
FILES
/etc/lcovrc
The system-wide configuration file.
~/.lcovrc
The per-user configuration file.
AUTHOR
Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
SEE ALSO
lcov(1), geninfo(1), genpng(1), gendesc(1), gcov(1)
2007-08-20 lcov 1.6 genhtml(1)
