1genhtml(1)                       User Manuals                       genhtml(1)
2
3
4

NAME

6       genhtml - Generate HTML view from LCOV coverage data files
7

SYNOPSIS

9       genhtml [-h|--help] [-v|--version]
10               [-q|--quiet] [-s|--show-details] [-f|--frames]
11               [-b|--baseline-file] baseline-file
12               [-o|--output-directory output-directory]
13               [-t|--title title]
14               [-d|--description-file description-file]
15               [-k|--keep-descriptions] [-c|--css-file css-file]
16               [-p|--prefix prefix] [--no-prefix]
17               [--no-source] [--num-spaces num] [--highlight]
18               [--legend] [--html-prolog prolog-file]
19               [--html-epilog epilog-file] [--html-extension extension]
20               [--html-gzip] [--sort] [--no-sort]
21               [--function-coverage] [--no-function-coverage]
22               [--branch-coverage] [--no-branch-coverage]
23               [--demangle-cpp] [--ignore-errors errors]
24               [--config-file config-file] [--rc keyword=value]
25               [--precision [--missed]
26               tracefile(s)
27

DESCRIPTION

29       Create  an  HTML  view  of coverage data found in tracefile.  Note that
30       tracefile may also be a list of filenames.
31
32       HTML output files are created in the current working  directory  unless
33       the --output-directory option is used. If tracefile ends with ".gz", it
34       is assumed to be GZIP-compressed and the gunzip tool will  be  used  to
35       decompress it transparently.
36
37       Note  that all source code files have to be present and readable at the
38       exact file system location they were compiled.
39
40       Use option --css-file to modify layout and colors of the generated HTML
41       output.  Files  are marked in different colors depending on the associ‐
42       ated coverage rate. By default, the coverage limits for low, medium and
43       high  coverage  are  set  to  0-75%, 75-90% and 90-100% percent respec‐
44       tively. To change these values, use  configuration  file  options  gen‐
45       html_hi_limit and genhtml_med_limit.
46
47       Also  note  that  when  displaying  percentages,  0%  and 100% are only
48       printed when the values are exactly 0%  and  100%  respectively.  Other
49       values  which would conventionally be rounded to 0% or 100% are instead
50       printed as nearest non-boundary value. This behavior is  in  accordance
51       with that of the gcov(1) tool.
52
53

OPTIONS

55       -h
56       --help
57              Print a short help text, then exit.
58
59       -v
60       --version
61              Print version number, then exit.
62
63       -q
64       --quiet
65              Do not print progress messages.
66
67              Suppresses  all  informational progress output. When this switch
68              is enabled, only error or warning messages are printed.
69
70       -f
71       --frames
72              Use HTML frames for source code view.
73
74              If enabled, a frameset is created for  each  source  code  file,
75              providing an overview of the source code as a "clickable" image.
76              Note that this option will slow down output creation  noticeably
77              because  each  source  code  character has to be inspected once.
78              Note also that the GD.pm Perl module has  to  be  installed  for
79              this    option    to    work    (it   may   be   obtained   from
80              http://www.cpan.org).
81
82       -s
83       --show-details
84              Generate detailed directory view.
85
86              When this option is enabled, genhtml generates two  versions  of
87              each  file  view. One containing the standard information plus a
88              link to a "detailed" version. The latter  additionally  contains
89              information about which test case covered how many lines of each
90              source file.
91
92       -b baseline-file
93       --baseline-file baseline-file
94              Use data in baseline-file as coverage baseline.
95
96              The tracefile specified by baseline-file is read and all  counts
97              found  in  the  original tracefile are decremented by the corre‐
98              sponding counts in baseline-file before creating any output.
99
100              Note that when a count for a particular line in baseline-file is
101              greater than the count in the tracefile, the result is zero.
102
103       -o output-directory
104       --output-directory output-directory
105              Create files in output-directory.
106
107              Use  this option to tell genhtml to write the resulting files to
108              a directory other than the current one. If output-directory does
109              not exist, it will be created.
110
111              It  is  advisable  to  use  this  option  since depending on the
112              project size, a lot of files and subdirectories may be created.
113
114       -t title
115       --title title
116              Display title in header of all pages.
117
118              title is written to the header portion of  each  generated  HTML
119              page  to  identify  the context in which a particular output was
120              created. By default this is the name of the tracefile.
121
122       -d description-file
123       --description-file description-file
124              Read test case descriptions from description-file.
125
126              All test case descriptions found in description-file and  refer‐
127              enced  in  the  input data file are read and written to an extra
128              page which is then incorporated into the HTML output.
129
130              The file format of description-file is:
131
132              for each test case:
133                     TN:<testname>
134                     TD:<test description>
135
136
137              Valid test case names can consist of letters,  numbers  and  the
138              underscore character ('_').
139       -k
140       --keep-descriptions
141              Do not remove unused test descriptions.
142
143              Keep descriptions found in the description file even if the cov‐
144              erage data indicates that the associated test case did not cover
145              any lines of code.
146
147              This option can also be configured permanently using the config‐
148              uration file option genhtml_keep_descriptions.
149
150       -c css-file
151       --css-file css-file
152              Use external style sheet file css-file.
153
154              Using this option, an extra .css file  may  be  specified  which
155              will replace the default one. This may be helpful if the default
156              colors make your eyes want to jump out of their sockets :)
157
158              This option can also be configured permanently using the config‐
159              uration file option genhtml_css_file.
160
161       -p prefix
162       --prefix prefix
163              Remove prefix from all directory names.
164
165              Because  lists  containing long filenames are difficult to read,
166              there is a mechanism implemented that will automatically try  to
167              shorten  all directory names on the overview page beginning with
168              a common prefix. By default, this is  done  using  an  algorithm
169              that tries to find the prefix which, when applied, will minimize
170              the resulting sum of characters of all directory names.
171
172              Use this option to specify the prefix to be removed by yourself.
173
174       --no-prefix
175              Do not remove prefix from directory names.
176
177              This  switch  will  completely  disable  the  prefix   mechanism
178              described in the previous section.
179
180              This option can also be configured permanently using the config‐
181              uration file option genhtml_no_prefix.
182
183       --no-source
184              Do not create source code view.
185
186              Use this switch if you don't want to get a source code view  for
187              each file.
188
189              This option can also be configured permanently using the config‐
190              uration file option genhtml_no_source.
191
192       --num-spaces spaces
193              Replace tabs in source view with num spaces.
194
195              Default value is 8.
196
197              This option can also be configured permanently using the config‐
198              uration file option genhtml_num_spaces.
199
200       --highlight
201              Highlight lines with converted-only coverage data.
202
203              Use this option in conjunction with the --diff option of lcov to
204              highlight those lines which were only covered in data sets which
205              were converted from previous source code versions.
206
207              This option can also be configured permanently using the config‐
208              uration file option genhtml_highlight.
209
210       --legend
211              Include color legend in HTML output.
212
213              Use this option to include a legend explaining  the  meaning  of
214              color coding in the resulting HTML output.
215
216              This option can also be configured permanently using the config‐
217              uration file option genhtml_legend.
218
219       --html-prolog prolog-file
220              Read customized HTML prolog from prolog-file.
221
222              Use this option to replace the default HTML prolog (the  initial
223              part  of  the  HTML  source code leading up to and including the
224              <body> tag) with the contents of prolog-file.  Within the prolog
225              text, the following words will be replaced when a page is gener‐
226              ated:
227
228              @pagetitle@
229              The title of the page.
230
231              @basedir@
232              A relative path leading to the base directory (e.g. for locating
233              css-files).
234
235              This option can also be configured permanently using the config‐
236              uration file option genhtml_html_prolog.
237
238       --html-epilog epilog-file
239              Read customized HTML epilog from epilog-file.
240
241              Use this option to replace the default HTML  epilog  (the  final
242              part  of the HTML source including </body>) with the contents of
243              epilog-file.
244
245              Within the epilog text, the following  words  will  be  replaced
246              when a page is generated:
247
248              @basedir@
249              A relative path leading to the base directory (e.g. for locating
250              css-files).
251
252              This option can also be configured permanently using the config‐
253              uration file option genhtml_html_epilog.
254
255       --html-extension extension
256              Use customized filename extension for generated HTML pages.
257
258              This  option  is  useful  in situations where different filename
259              extensions are required to render the resulting pages  correctly
260              (e.g.  php).  Note that a '.' will be inserted between the file‐
261              name and the extension specified by this option.
262
263              This option can also be configured permanently using the config‐
264              uration file option genhtml_html_extension.
265
266       --html-gzip
267              Compress  all generated html files with gzip and add a .htaccess
268              file specifying gzip-encoding in the root output directory.
269
270              Use this option if you want to save  space  on  your  webserver.
271              Requires  a  webserver with .htaccess support and a browser with
272              support for gzip compressed html.
273
274              This option can also be configured permanently using the config‐
275              uration file option genhtml_html_gzip.
276
277       --sort
278       --no-sort
279              Specify  whether  to  include sorted views of file and directory
280              overviews.
281
282              Use --sort to include sorted views or --no-sort to  not  include
283              them.  Sorted views are enabled by default.
284
285              When  sorted  views are enabled, each overview page will contain
286              links to views of that page sorted by coverage rate.
287
288              This option can also be configured permanently using the config‐
289              uration file option genhtml_sort.
290
291       --function-coverage
292       --no-function-coverage
293              Specify  whether  to display function coverage summaries in HTML
294              output.
295
296              Use --function-coverage to enable function coverage summaries or
297              --no-function-coverage  to  disable  it.  Function coverage sum‐
298              maries are enabled by default
299
300              When function coverage summaries are enabled, each overview page
301              will  contain  the number of functions found and hit per file or
302              directory, together with the resulting coverage rate.  In  addi‐
303              tion,  each source code view will contain a link to a page which
304              lists all functions found in that file plus the respective  call
305              count for those functions.
306
307              This option can also be configured permanently using the config‐
308              uration file option genhtml_function_coverage.
309
310       --branch-coverage
311       --no-branch-coverage
312              Specify whether to display branch coverage data in HTML output.
313
314              Use --branch-coverage  to  enable  branch  coverage  display  or
315              --no-branch-coverage to disable it. Branch coverage data display
316              is enabled by default
317
318              When branch coverage display is enabled, each overview page will
319              contain  the number of branches found and hit per file or direc‐
320              tory, together with the resulting coverage  rate.  In  addition,
321              each  source  code view will contain an extra column which lists
322              all branches of a line with indications of  whether  the  branch
323              was taken or not. Branches are shown in the following format:
324
325               ' + ': Branch was taken at least once
326               ' - ': Branch was not taken
327               ' # ': The basic block containing the branch was never executed
328
329              Note  that it might not always be possible to relate branches to
330              the corresponding source code  statements:  during  compilation,
331              GCC  might  shuffle branches around or eliminate some of them to
332              generate better code.
333
334              This option can also be configured permanently using the config‐
335              uration file option genhtml_branch_coverage.
336
337       --demangle-cpp
338              Specify whether to demangle C++ function names.
339
340              Use  this  option  if  you want to convert C++ internal function
341              names to human readable format for display on the HTML  function
342              overview  page.   This  option requires that the c++filt tool is
343              installed (see c++filt(1)).
344
345       --ignore-errors errors
346              Specify a list of errors after which to continue processing.
347
348              Use this option to specify a list of  one  or  more  classes  of
349              errors after which geninfo should continue processing instead of
350              aborting.
351
352              errors can be a comma-separated list of the following keywords:
353
354              source: the source code file for a data set could not be found.
355
356       --config-file config-file
357              Specify a configuration file to use.
358
359              When this option is specified, neither the system-wide  configu‐
360              ration  file  /etc/lcovrc,  nor  the per-user configuration file
361              ~/.lcovrc is read.
362
363              This option may be useful when there is a need  to  run  several
364              instances  of  genhtml with different configuration file options
365              in parallel.
366
367       --rc keyword=value
368              Override a configuration directive.
369
370              Use this option to specify a keyword=value statement which over‐
371              rides  the  corresponding  configuration statement in the lcovrc
372              configuration file. You can specify this option more  than  once
373              to  override  multiple  configuration statements.  See lcovrc(5)
374              for a list of available keywords and their meaning.
375
376       --precision num
377              Show coverage rates with num number of digits after the decimal-
378              point.
379
380              Default value is 1.
381
382              This option can also be configured permanently using the config‐
383              uration file option genhtml_precision.
384
385       --missed
386              Show counts of missed lines, functions, or branches
387
388              Use this option to change overview pages to show  the  count  of
389              lines,  functions,  or  branches that were not hit. These counts
390              are represented by negative numbers.
391
392              When specified together with --sort, file  and  directory  views
393              will be sorted by missed counts.
394
395              This option can also be configured permanently using the config‐
396              uration file option genhtml_missed.
397
398

FILES

400       /etc/lcovrc
401              The system-wide configuration file.
402
403       ~/.lcovrc
404              The per-user configuration file.
405
406

AUTHOR

408       Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
409
410

SEE ALSO

412       lcov(1), lcovrc(5), geninfo(1), genpng(1), gendesc(1), gcov(1)
413
414
415
4162019-07-25                         LCOV 1.14                        genhtml(1)
Impressum