Provided by: lcov_1.12-2_all bug

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

       -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 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:
                     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 configuration 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 configuration 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  minimize  the
              resulting sum of characters of all directory names.

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

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

       --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 locating css-files).

              This option can also be configured permanently using the configuration 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 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
              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
              genhtml_html_gzip.

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

       --function-coverage
       --no-function-coverage
              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 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.

       --branch-coverage
       --no-branch-coverage
              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 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.

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

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

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

       --rc keyword=value
              Override a configuration directive.

              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
              Show coverage rates with num number of digits after the decimal-point.

              Default value is 1.

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

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), lcovrc(5), geninfo(1), genpng(1), gendesc(1), gcov(1)