1genhtml(1) User Manuals genhtml(1)
2
6 genhtml - Generate HTML view from LCOV coverage data files
7
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
29 Create an HTML view of coverage data found in tracefile. Note that
30 tracefile may also be a list of filenames.
31 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 Note that all source code files have to be present and readable at the
38 exact file system location they were compiled.
39 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 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
55 -h
56 --help
57 Print a short help text, then exit.
58 -v
60 --version
61 Print version number, then exit.
62 -q
64 --quiet
65 Do not print progress messages.
66 Suppresses all informational progress output. When this switch
68 is enabled, only error or warning messages are printed.
69 -f
71 --frames
72 Use HTML frames for source code view.
73 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 -s
83 --show-details
84 Generate detailed directory view.
85 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 -b baseline-file
93 --baseline-file baseline-file
94 Use data in baseline-file as coverage baseline.
95 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 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 -o output-directory
104 --output-directory output-directory
105 Create files in output-directory.
106 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 It is advisable to use this option since depending on the
112 project size, a lot of files and subdirectories may be created.
113 -t title
115 --title title
116 Display title in header of all pages.
117 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 -d description-file
123 --description-file description-file
124 Read test case descriptions from description-file.
125 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 The file format of description-file is:
131 for each test case:
133 TN:<testname>
134 TD:<test description>
135 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 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 This option can also be configured permanently using the config‐
148 uration file option genhtml_keep_descriptions.
149 -c css-file
151 --css-file css-file
152 Use external style sheet file css-file.
153 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 This option can also be configured permanently using the config‐
159 uration file option genhtml_css_file.
160 -p prefix
162 --prefix prefix
163 Remove prefix from all directory names.
164 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 Use this option to specify the prefix to be removed by yourself.
173 --no-prefix
175 Do not remove prefix from directory names.
176 This switch will completely disable the prefix mechanism de‐
178 scribed in the previous section.
179 This option can also be configured permanently using the config‐
181 uration file option genhtml_no_prefix.
182 --no-source
184 Do not create source code view.
185 Use this switch if you don't want to get a source code view for
187 each file.
188 This option can also be configured permanently using the config‐
190 uration file option genhtml_no_source.
191 --num-spaces spaces
193 Replace tabs in source view with num spaces.
194 Default value is 8.
196 This option can also be configured permanently using the config‐
198 uration file option genhtml_num_spaces.
199 --highlight
201 Highlight lines with converted-only coverage data.
202 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 This option can also be configured permanently using the config‐
208 uration file option genhtml_highlight.
209 --legend
211 Include color legend in HTML output.
212 Use this option to include a legend explaining the meaning of
214 color coding in the resulting HTML output.
215 This option can also be configured permanently using the config‐
217 uration file option genhtml_legend.
218 --html-prolog prolog-file
220 Read customized HTML prolog from prolog-file.
221 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 @pagetitle@
229 The title of the page.
230 @basedir@
232 A relative path leading to the base directory (e.g. for locating
233 css-files).
234 This option can also be configured permanently using the config‐
236 uration file option genhtml_html_prolog.
237 --html-epilog epilog-file
239 Read customized HTML epilog from epilog-file.
240 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 Within the epilog text, the following words will be replaced
246 when a page is generated:
247 @basedir@
249 A relative path leading to the base directory (e.g. for locating
250 css-files).
251 This option can also be configured permanently using the config‐
253 uration file option genhtml_html_epilog.
254 --html-extension extension
256 Use customized filename extension for generated HTML pages.
257 This option is useful in situations where different filename ex‐
259 tensions 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 This option can also be configured permanently using the config‐
264 uration file option genhtml_html_extension.
265 --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 Use this option if you want to save space on your webserver. Re‐
271 quires a webserver with .htaccess support and a browser with
272 support for gzip compressed html.
273 This option can also be configured permanently using the config‐
275 uration file option genhtml_html_gzip.
276 --sort
278 --no-sort
279 Specify whether to include sorted views of file and directory
280 overviews.
281 Use --sort to include sorted views or --no-sort to not include
283 them. Sorted views are enabled by default.
284 When sorted views are enabled, each overview page will contain
286 links to views of that page sorted by coverage rate.
287 This option can also be configured permanently using the config‐
289 uration file option genhtml_sort.
290 --function-coverage
292 --no-function-coverage
293 Specify whether to display function coverage summaries in HTML
294 output.
295 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 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 This option can also be configured permanently using the config‐
308 uration file option genhtml_function_coverage.
309 --branch-coverage
311 --no-branch-coverage
312 Specify whether to display branch coverage data in HTML output.
313 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 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 ' + ': Branch was taken at least once
326 ' - ': Branch was not taken
327 ' # ': The basic block containing the branch was never executed
328 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 This option can also be configured permanently using the config‐
335 uration file option genhtml_branch_coverage.
336 --demangle-cpp
338 Specify whether to demangle C++ function names.
339 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 --ignore-errors errors
346 Specify a list of errors after which to continue processing.
347 Use this option to specify a list of one or more classes of er‐
349 rors after which geninfo should continue processing instead of
350 aborting.
351 errors can be a comma-separated list of the following keywords:
353 source: the source code file for a data set could not be found.
355 --config-file config-file
357 Specify a configuration file to use.
358 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 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 --rc keyword=value
368 Override a configuration directive.
369 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 --precision num
377 Show coverage rates with num number of digits after the decimal-
378 point.
379 Default value is 1.
381 This option can also be configured permanently using the config‐
383 uration file option genhtml_precision.
384 --missed
386 Show counts of missed lines, functions, or branches
387 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 When specified together with --sort, file and directory views
393 will be sorted by missed counts.
394 This option can also be configured permanently using the config‐
396 uration file option genhtml_missed.
397
400 /etc/lcovrc
401 The system-wide configuration file.
402 ~/.lcovrc
404 The per-user configuration file.
405
408 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
409
412 lcov(1), lcovrc(5), geninfo(1), genpng(1), gendesc(1), gcov(1)
4132021-07-22 LCOV 1.14 genhtml(1)