1genhtml(1) User Manuals genhtml(1)
2
3
4
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
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
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
400 /etc/lcovrc
401 The system-wide configuration file.
402
403 ~/.lcovrc
404 The per-user configuration file.
405
406
408 Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>
409
410
412 lcov(1), lcovrc(5), geninfo(1), genpng(1), gendesc(1), gcov(1)
413
414
415
4162020-07-28 LCOV 1.14 genhtml(1)