genhtml.1

.TH genhtml 1 "LCOV 1.10" 2012\-10\-10 "User Manuals"
.SH NAME
genhtml \- Generate HTML view from LCOV coverage data files
.SH SYNOPSIS
.B genhtml
.RB [ \-h | \-\-help ]
.RB [ \-v | \-\-version ]
.RS 8
.br
.RB [ \-q | \-\-quiet ]
.RB [ \-s | \-\-show\-details ]
.RB [ \-f | \-\-frames ]
.br
.RB [ \-b | \-\-baseline\-file  ]
.IR baseline\-file
.br
.RB [ \-o | \-\-output\-directory
.IR output\-directory ]
.br
.RB [ \-t | \-\-title
.IR title ]
.br
.RB [ \-d | \-\-description\-file
.IR description\-file ]
.br
.RB [ \-k | \-\-keep\-descriptions ]
.RB [ \-c | \-\-css\-file
.IR css\-file ]
.br
.RB [ \-p | \-\-prefix
.IR prefix ]
.RB [ \-\-no\-prefix ]
.br
.RB [ \-\-no\-source ]
.RB [ \-\-num\-spaces
.IR num ]
.RB [ \-\-highlight ]
.br
.RB [ \-\-legend ]
.RB [ \-\-html\-prolog
.IR prolog\-file ]
.br
.RB [ \-\-html\-epilog
.IR epilog\-file ]
.RB [ \-\-html\-extension
.IR extension ]
.br
.RB [ \-\-html\-gzip ]
.RB [ \-\-sort ]
.RB [ \-\-no\-sort ]
.br
.RB [ \-\-function\-coverage ]
.RB [ \-\-no\-function\-coverage ]
.br
.RB [ \-\-branch\-coverage ]
.RB [ \-\-no\-branch\-coverage ]
.br
.RB [ \-\-demangle\-cpp ]
.RB [ \-\-ignore\-errors
.IR errors  ]
.br
.RB [ \-\-config\-file
.IR config\-file ]
.RB [ \-\-rc
.IR keyword = value ]
.br
.IR tracefile(s)
.RE
.SH DESCRIPTION
Create an HTML view of coverage data found in
.IR tracefile .
Note that
.I 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 
.I 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
.I \--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
.IR 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
.BR gcov (1)
tool.

.SH OPTIONS
.B \-h
.br
.B \-\-help
.RS
Print a short help text, then exit.

.RE
.B \-v
.br
.B \-\-version
.RS
Print version number, then exit.

.RE
.B \-q
.br
.B \-\-quiet
.RS
Do not print progress messages.

Suppresses all informational progress output. When this switch is enabled,
only error or warning messages are printed.

.RE
.B \-f
.br
.B \-\-frames
.RS
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).

.RE
.B \-s
.br
.B \-\-show\-details
.RS
Generate detailed directory view.

When this option is enabled,
.B 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.

.RE
.BI "\-b " baseline\-file
.br
.BI "\-\-baseline\-file " baseline\-file
.RS
Use data in
.I baseline\-file
as coverage baseline.

The tracefile specified by
.I baseline\-file
is read and all counts found in the original
.I tracefile
are decremented by the corresponding counts in 
.I baseline\-file
before creating any output.

Note that when a count for a particular line in
.I baseline\-file
is greater than the count in the
.IR tracefile ,
the result is zero.

.RE
.BI "\-o " output\-directory
.br
.BI "\-\-output\-directory " output\-directory
.RS
Create files in 
.I output\-directory.

Use this option to tell 
.B genhtml
to write the resulting files to a directory other than
the current one. If 
.I 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.

.RE
.BI "\-t " title
.br
.BI "\-\-title " title
.RS
Display 
.I title
in header of all pages.

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

.RE
.BI "\-d " description\-file
.br
.BI "\-\-description\-file " description\-file
.RS
Read test case descriptions from 
.IR description\-file .

All test case descriptions found in
.I 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
.IR "description\-file " is:

for each test case:
.RS
TN:<testname>
.br
TD:<test description>

.RE

Valid test case names can consist of letters, numbers and the underscore
character ('_').
.RE
.B \-k
.br
.B \-\-keep\-descriptions
.RS
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 configuration file
option
.IR genhtml_keep_descriptions .

.RE
.BI "\-c " css\-file
.br
.BI "\-\-css\-file " css\-file
.RS
Use external style sheet file
.IR 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
.IR genhtml_css_file .

.RE
.BI "\-p " prefix
.br
.BI "\-\-prefix " prefix
.RS
Remove 
.I 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 minimize the resulting sum of characters of all directory
names.

Use this option to specify the prefix to be removed by yourself.

.RE
.B \-\-no\-prefix
.RS
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 configuration file
option
.IR genhtml_no_prefix .

.RE
.B \-\-no\-source
.RS
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 configuration file
option
.IR genhtml_no_source .

.RE
.BI "\-\-num\-spaces " spaces
.RS
Replace tabs in source view with
.I num
spaces.

Default value is 8.

This option can also be configured permanently using the configuration file
option
.IR genhtml_num_spaces .

.RE
.B \-\-highlight
.RS
Highlight lines with converted\-only coverage data.

Use this option in conjunction with the \-\-diff option of
.B 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
.IR genhtml_highlight .

.RE
.B \-\-legend
.RS
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 configuration file
option
.IR genhtml_legend .

.RE
.BI "\-\-html\-prolog " prolog\-file
.RS
Read customized HTML prolog from 
.IR 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
.IR prolog\-file .
Within the prolog text, the following words will be replaced when a page is generated:

.B "@pagetitle@"
.br
The title of the page.

.B "@basedir@"
.br
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
.IR genhtml_html_prolog .

.RE
.BI "\-\-html\-epilog " epilog\-file
.RS
Read customized HTML epilog from 
.IR epilog\-file .

Use this option to replace the default HTML epilog (the final part of the HTML
source including </body>) with the contents of
.IR epilog\-file .

Within the epilog text, the following words will be replaced when a page is generated:

.B "@basedir@"
.br
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
.IR genhtml_html_epilog .

.RE
.BI "\-\-html\-extension " extension
.RS
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 filename and the extension specified by
this option.

This option can also be configured permanently using the configuration file
option
.IR genhtml_html_extension .
.RE

.B \-\-html\-gzip
.RS
Compress all generated html files with gzip and add a .htaccess file specifying
gzip\-encoding in the root output directory.

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

.RE
.B \-\-sort
.br
.B \-\-no\-sort
.RS
Specify whether to include sorted views of file and directory overviews.

Use \-\-sort to include sorted views or \-\-no\-sort to not include them.
Sorted views are
.B 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
.IR genhtml_sort .

.RE
.B \-\-function\-coverage
.br
.B \-\-no\-function\-coverage
.RS
Specify whether to display function coverage summaries in HTML output.

Use \-\-function\-coverage to enable function coverage summaries or
\-\-no\-function\-coverage to disable it. Function coverage summaries are
.B 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
.IR genhtml_function_coverage .

.RE
.B \-\-branch\-coverage
.br
.B \-\-no\-branch\-coverage
.RS
Specify whether to display branch coverage data in HTML output.

Use \-\-branch\-coverage to enable branch coverage display or
\-\-no\-branch\-coverage to disable it. Branch coverage data display is
.B 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
.br
 ' - ': Branch was not taken
.br
 ' # ': The basic block containing the branch was never executed
.br

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

.RE
.B \-\-demangle\-cpp
.RS
Specify whether to demangle C++ function names.

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
.BR c++filt (1)).

.RE
.B \-\-ignore\-errors
.I errors
.br
.RS
Specify a list of errors after which to continue processing.

Use this option to specify a list of one or more classes of errors after which
geninfo should continue processing instead of aborting.

.I errors
can be a comma\-separated list of the following keywords:

.B source:
the source code file for a data set could not be found.
.RE

.B \-\-config\-file
.I config\-file
.br
.RS
Specify a configuration file to use.

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
.B genhtml
with different configuration file options in parallel.
.RE

.B \-\-rc
.IR keyword = value
.br
.RS
Override a configuration directive.

Use this option to specify a
.IR 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
.BR lcovrc (5)
for a list of available keywords and their meaning.
.RE

.SH FILES

.I /etc/lcovrc
.RS
The system\-wide configuration file.
.RE

.I ~/.lcovrc
.RS
The per\-user configuration file.
.RE

.SH AUTHOR
Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>

.SH SEE ALSO
.BR lcov (1),
.BR lcovrc (5),
.BR geninfo (1),
.BR genpng (1),
.BR gendesc (1),
.BR gcov (1)