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