1GCOVR(1) gcovr GCOVR(1)
2
3
4
6 gcovr - gcovr Documentation
7
8 Gcovr provides a utility for managing the use of the GNU gcov utility
9 and generating summarized code coverage results. This command is
10 inspired by the Python coverage.py package, which provides a similar
11 utility for Python.
12
13 The gcovr command can produce different kinds of coverage reports:
14
15 · default: compact human-readable summaries
16
17 · --html: HTML summaries
18
19 · --html-details: HTML report with annotated source files
20
21 · --xml: machine readable XML reports in Cobertura format
22
23 · --sonarqube: machine readable XML reports in Sonarqube format
24
25 · --json: JSON report with source files structure and coverage
26
27 Thus, gcovr can be viewed as a command-line alternative to the lcov
28 utility, which runs gcov and generates an HTML-formatted report. The
29 development of gcovr was motivated by the need for text summaries and
30 XML reports.
31
32 Quick Links
33
34 · Getting Help
35
36 · Submit a ticket
37
38 · Stack Overflow
39
40 · Chat on Gitter
41
42 · Install from PyPI: pip install gcovr
43
44 · Source Code on GitHub
45
46 · changelog
47
49 Gcovr is available as a Python package that can be installed via pip.
50
51 Install newest stable gcovr release from PyPI:
52
53 pip install gcovr
54
55 Install development version from GitHub:
56
57 pip install git+https://github.com/gcovr/gcovr.git
58
59 Which environments does gcovr support?
60
61 Python:
62 2.7 and 3.5+.
63
64 The automated tests run on CPython 2.7, 3.5, and 3.7, and PyPy
65 2.7 and 3.5.
66
67 Starting in 2020, gcovr will only run on Python versions with
68 upstream support.
69
70 Last gcovr release for old Python versions:
71
72 ┌───────┬───────┐
73 │Python │ gcovr │
74 ├───────┼───────┤
75 │2.6 │ 3.4 │
76 ├───────┼───────┤
77 │3.4 │ 4.1 │
78 └───────┴───────┘
79
80 Operating System:
81 Linux, Windows, and macOS.
82
83 The automated tests run on Ubuntu 16.04 and Windows Server 2012.
84
85 Compiler:
86 GCC and Clang.
87
88 The automated tests run on GCC 5.
89
91 Gcovr provides a utility for managing the use of the GNU gcov utility
92 and generating summarized code coverage results. This command is
93 inspired by the Python coverage.py package, which provides a similar
94 utility for Python.
95
96 The gcovr command can produce different kinds of coverage reports:
97
98 · default: compact human-readable summaries
99
100 · --html: HTML summaries
101
102 · --html-details: HTML report with annotated source files
103
104 · --xml: machine readable XML reports in Cobertura format
105
106 · --sonarqube: machine readable XML reports in Sonarqube format
107
108 · --json: JSON report with source files structure and coverage
109
110 Thus, gcovr can be viewed as a command-line alternative to the lcov
111 utility, which runs gcov and generates an HTML-formatted report. The
112 development of gcovr was motivated by the need for text summaries and
113 XML reports.
114
115 The Gcovr Home Page is http://gcovr.com. Automated test results are
116 available through Travis CI and Appveyor. Gcovr is available under the
117 BSD license.
118
119 This documentation describes Gcovr 4.2.
120
121 This User Guide provides the following sections:
122
123 · Getting Started
124
125 · Tabular Output of Code Coverage
126
127 · Tabular Output of Branch Coverage
128
129 · Cobertura XML Output
130
131 · HTML Output
132
133 · Sonarqube XML Output
134
135 · JSON Output
136
137 · Multiple Output Formats
138
139 · Combining Tracefiles
140
141 · The gcovr Command
142
143 · gcovr
144
145 · Using Filters
146
147 · Speeding up coverage data search
148
149 · Filters for symlinks
150
151 · Configuration Files
152
153 · Exclusion Markers
154
155 · Acknowledgements
156
157 Related documents:
158
159 · installation
160
161 · contributing (includes instructions for bug reports)
162
163 · cookbook
164
165 · faq
166
167 · changelog
168
169 · license
170
171 Getting Started
172 The gcovr command provides a summary of the lines that have been exe‐
173 cuted in a program. Code coverage statistics help you discover
174 untested parts of a program, which is particularly important when
175 assessing code quality. Well-tested code is a characteristic of high
176 quality code, and software developers often assess code coverage sta‐
177 tistics when deciding if software is ready for a release.
178
179 The gcovr command can be used to analyze programs compiled with GCC.
180 The following sections illustrate the application of gcovr to test cov‐
181 erage of the following program:
182
183 1 // example.cpp
184 2
185 3 int foo(int param)
186 4 {
187 5 if (param)
188 6 {
189 7 return 1;
190 8 }
191 9 else
192 10 {
193 11 return 0;
194 12 }
195 13 }
196 14
197 15 int main(int argc, char* argv[])
198 16 {
199 17 foo(0);
200 18
201 19 return 0;
202 20 }
203
204 This code executes several subroutines in this program, but some lines
205 in the program are not executed.
206
207 Tabular Output of Code Coverage
208 We compile example1.cpp with the GCC compiler as follows:
209
210 g++ -fprofile-arcs -ftest-coverage -fPIC -O0 example.cpp -o program
211
212 Note that we compile this program without optimization, because opti‐
213 mization may combine lines of code and otherwise change the flow of
214 execution in the program. Additionally, we compile with the -fpro‐
215 file-arcs -ftest-coverage -fPIC compiler options, which add logic to
216 generate output files that can be processed by the gcov command.
217
218 The compiler generates the program executable. When we execute this
219 command:
220
221 ./program
222
223 the files example1.gcno and example1.gcda are generated. These files
224 are processed with by gcov to generate code coverage statistics. The
225 gcovr command calls gcov and summarizes these code coverage statistics
226 in various formats. For example:
227
228 gcovr -r .
229
230 generates a text summary of the lines executed:
231
232 ------------------------------------------------------------------------------
233 GCC Code Coverage Report
234 Directory: .
235 ------------------------------------------------------------------------------
236 File Lines Exec Cover Missing
237 ------------------------------------------------------------------------------
238 example.cpp 7 6 85% 7
239 ------------------------------------------------------------------------------
240 TOTAL 7 6 85%
241 ------------------------------------------------------------------------------
242
243
244 Each line of this output includes a summary for a given source file,
245 including the number of lines instrumented, the number of lines exe‐
246 cuted, the percentage of lines executed, and a summary of the line num‐
247 bers that were not executed. To improve clarity, gcovr uses an aggres‐
248 sive approach to grouping uncovered lines and will combine uncovered
249 lines separated by "non-code" lines (blank, freestanding braces, and
250 single-line comments) into a single region. As a result, the number of
251 lines listed in the "Missing" list may be greater than the difference
252 of the "Lines" and "Exec" columns.
253
254 The -r option specifies the root directory for the files that are being
255 analyzed. This allows gcovr to generate a simpler report (without
256 absolute path names), and it allows system header files to be excluded
257 from the analysis.
258
259 Note that gcov accumulates statistics by line. Consequently, it works
260 best with a programming style that places only one statement on each
261 line.
262
263 Tabular Output of Branch Coverage
264 The gcovr command can also summarize branch coverage using the
265 --branches option:
266
267 gcovr -r . --branches
268
269 This generates a tabular output that summarizes the number of branches,
270 the number of branches taken and the branches that were not completely
271 covered:
272
273 ------------------------------------------------------------------------------
274 GCC Code Coverage Report
275 Directory: .
276 ------------------------------------------------------------------------------
277 File Branches Taken Cover Missing
278 ------------------------------------------------------------------------------
279 example.cpp 2 1 50% 5
280 ------------------------------------------------------------------------------
281 TOTAL 2 1 50%
282 ------------------------------------------------------------------------------
283
284
285 Cobertura XML Output
286 The default output format for gcovr is to generate a tabular summary in
287 plain text. The gcovr command can also generate an XML output using
288 the --xml and --xml-pretty options:
289
290 gcovr -r . --xml-pretty
291
292 This generates an XML summary of the lines executed:
293
294 <?xml version='1.0' encoding='UTF-8'?>
295 <!DOCTYPE coverage SYSTEM 'http://cobertura.sourceforge.net/xml/coverage-04.dtd'>
296 <coverage line-rate="0.8571428571428571" branch-rate="0.5" lines-covered="6" lines-valid="7" branches-covered="1" branches-valid="2" complexity="0.0" timestamp="1573053861" version="gcovr 4.2">
297 <sources>
298 <source>.</source>
299 </sources>
300 <packages>
301 <package name="" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
302 <classes>
303 <class name="example_cpp" filename="example.cpp" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
304 <methods/>
305 <lines>
306 <line number="3" hits="1" branch="false"/>
307 <line number="5" hits="1" branch="true" condition-coverage="50% (1/2)">
308 <conditions>
309 <condition number="0" type="jump" coverage="50%"/>
310 </conditions>
311 </line>
312 <line number="7" hits="0" branch="false"/>
313 <line number="11" hits="1" branch="false"/>
314 <line number="15" hits="1" branch="false"/>
315 <line number="17" hits="1" branch="false"/>
316 <line number="19" hits="1" branch="false"/>
317 </lines>
318 </class>
319 </classes>
320 </package>
321 </packages>
322 </coverage>
323
324 This XML format is in the Cobertura XML format suitable for import and
325 display within the Jenkins and Hudson continuous integration servers
326 using the Cobertura Plugin. Gcovr also supports a Sonarqube XML Output
327
328 The --xml option generates a denser XML output, and the --xml-pretty
329 option generates an indented XML output that is easier to read. Note
330 that the XML output contains more information than the tabular summary.
331 The tabular summary shows the percentage of covered lines, while the
332 XML output includes branch statistics and the number of times that each
333 line was covered. Consequently, XML output can be used to support per‐
334 formance optimization in the same manner that gcov does.
335
336 HTML Output
337 The gcovr command can also generate a simple HTML output using the
338 --html option:
339
340 gcovr -r . --html -o example-html.html
341
342 This generates a HTML summary of the lines executed. In this example,
343 the file example1.html is generated, which has the following output:
344 [image]
345
346 The default behavior of the --html option is to generate HTML for a
347 single webpage that summarizes the coverage for all files. The HTML is
348 printed to standard output, but the -o (--output) option is used to
349 specify a file that stores the HTML output.
350
351 The --html-details option is used to create a separate web page for
352 each file. Each of these web pages includes the contents of file with
353 annotations that summarize code coverage. Consider the following com‐
354 mand:
355
356 gcovr -r . --html --html-details -o example-html-details.html
357
358 This generates the following HTML page for the file example1.cpp:
359 [image]
360
361 Note that the --html-details option can only be used with the -o
362 (--output) option. For example, if the --output option specifies the
363 output file coverage.html, then the web pages generated for each file
364 will have names of the form coverage.<filename>.html.
365
366 Sonarqube XML Output
367 If you are using Sonarqube, you can get a coverage report in a suitable
368 XML format via the gcovr --sonarqube option:
369
370 gcovr --sonarqube coverage.xml
371
372 The Sonarqube XML format is documented at
373 https://docs.sonarqube.org/latest/analysis/generic-test/.
374
375 JSON Output
376 The gcovr command can also generate a JSON output using the --json and
377 --json-pretty options:
378
379 gcovr --json coverage.json
380
381 The --json-pretty option generates an indented JSON output that is eas‐
382 ier to read.
383
384 Structure of file is based on gcov JSON intermediate format with addi‐
385 tional key names specific to gcovr.
386
387 Structure of the JSON is following:
388
389 {
390 "gcovr/format_version": gcovr_json_version
391 "files": [file]
392 }
393
394 gcovr_json_version: version of gcovr JSON format
395
396 Each file has the following form:
397
398 {
399 "file": file
400 "lines": [line]
401 }
402
403 file: path to source code file, relative to gcovr root directory.
404
405 Each line has the following form:
406
407 {
408 "branches": [branch]
409 "count": count
410 "line_number": line_number
411 "gcovr/noncode": gcovr_noncode
412 }
413
414 gcovr_noncode: if True coverage info on this line should be ignored
415
416 Each branch has the following form:
417
418 {
419 "count": count
420 "fallthrough": fallthrough
421 "throw": throw
422 }
423
424 file, line and branch have the structure defined in gcov intermediate
425 format. This format is documented at
426 https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov.
427
428 Multiple JSON files can be merged into the coverage data with sum of
429 lines and branches execution
430
431 Multiple Output Formats
432 You can write multiple report formats with one gcovr invocation by
433 passing the output filename directly to the report format flag. If no
434 filename is specified for the format, the value from -o/--output is
435 used by default, which itself defaults to stdout.
436
437 The following report format flags can take an optional output file
438 name:
439
440 · gcovr --xml
441
442 · gcovr --html
443
444 · gcovr --html-details
445
446 · gcovr --sonarqube
447
448 · gcovr --json
449
450 Note that --html-details overrides any value of --html if it is
451 present.
452
453 Combining Tracefiles
454 You can merge coverage data from multiple runs with gcovr --add-trace‐
455 file.
456
457 For each run, generate JSON output:
458
459 ... # compile and run first test case
460 gcovr ... --json run-1.json
461 ... # compile and run second test case
462 gcovr ... --json run-2.json
463
464 Next, merge the json files and generate the desired report:
465
466 gcovr --add-tracefile run-1.json --add-tracefile run-2.json --html-details coverage.html
467
468 The gcovr Command
469 The gcovr command recursively searches a directory tree to find gcov
470 coverage files, and generates a text summary of the code coverage. The
471 --help option generates the following summary of the gcovr command line
472 options:
473
474 gcovr
475 A utility to run gcov and summarize the coverage in simple reports.
476
477 usage: gcovr [options] [search_paths...]
478
479 See <http://gcovr.com/> for the full manual.
480
481 Options
482 search_paths
483 Search these directories for coverage files. Defaults to --root
484 and --object-directory. Config key: search-path.
485
486 -h, --help
487 Show this help message, then exit.
488
489 --version
490 Print the version number, then exit.
491
492 -v, --verbose
493 Print progress messages. Please include this output in bug
494 reports.
495
496 -r <root>, --root <root>
497 The root directory of your source files. Defaults to '.', the
498 current directory. File names are reported relative to this
499 root. The --root is the default --filter.
500
501 -a <add_tracefile>, --add-tracefile <add_tracefile>
502 Combine the coverage data from JSON files. Coverage files con‐
503 tains source files structure relative to root directory. Those
504 structures are combined in the output relative to the current
505 root directory. Option can be specified multiple times. When
506 option is used gcov is not run to collect the new coverage data.
507
508 --config <config>
509 Load that configuration file. Defaults to gcovr.cfg in the
510 --root directory.
511
512 --fail-under-line <min>
513 Exit with a status of 2 if the total line coverage is less than
514 MIN. Can be ORed with exit status of '--fail-under-branch'
515 option.
516
517 --fail-under-branch <min>
518 Exit with a status of 4 if the total branch coverage is less
519 than MIN. Can be ORed with exit status of '--fail-under-line'
520 option.
521
522 --source-encoding <source_encoding>
523 Select the source file encoding. Defaults to the system default
524 encoding (UTF-8).
525
526 Output Options
527 Gcovr prints a text report by default, but can switch to XML or HTML.
528
529 -o <output>, --output <output>
530 Print output to this filename. Defaults to stdout. Individual
531 output formats can override this.
532
533 -b, --branches
534 Report the branch coverage instead of the line coverage. For
535 text report only. Config key: txt-branch.
536
537 -u, --sort-uncovered
538 Sort entries by increasing number of uncovered lines. For text
539 and HTML report.
540
541 -p, --sort-percentage
542 Sort entries by increasing percentage of uncovered lines. For
543 text and HTML report.
544
545 -x <output>, --xml <output>
546 Generate a Cobertura XML report. OUTPUT is optional and defaults
547 to --output.
548
549 --xml-pretty
550 Pretty-print the XML report. Implies --xml. Default: False.
551
552 --html <output>
553 Generate a HTML report. OUTPUT is optional and defaults to
554 --output.
555
556 --html-details <output>
557 Add annotated source code reports to the HTML report. Implies
558 --html. OUTPUT is optional and defaults to --output.
559
560 --html-title <title>
561 Use TITLE as title for the HTML report. Default is Head.
562
563 --html-medium-threshold <medium>
564 If the coverage is below MEDIUM, the value is marked as low cov‐
565 erage in the HTML report. MEDIUM has to be lower than or equal
566 to value of --html-high-threshold. If MEDIUM is equal to value
567 of --html-high-threshold the report has only high and low cover‐
568 age. Default is 75.0.
569
570 --html-high-threshold <high>
571 If the coverage is below HIGH, the value is marked as medium
572 coverage in the HTML report. HIGH has to be greater than or
573 equal to value of --html-medium-threshold. If HIGH is equal to
574 value of --html-medium-threshold the report has only high and
575 low coverage. Default is 90.0.
576
577 --html-absolute-paths
578 Use absolute paths to link the --html-details reports. Defaults
579 to relative links.
580
581 --html-encoding <html_encoding>
582 Override the declared HTML report encoding. Defaults to UTF-8.
583 See also --source-encoding.
584
585 -s, --print-summary
586 Print a small report to stdout with line & branch percentage
587 coverage. This is in addition to other reports. Default: False.
588
589 --sonarqube <output>
590 Generate sonarqube generic coverage report in this file name.
591 OUTPUT is optional and defaults to --output.
592
593 --json <output>
594 Generate a JSON report. OUTPUT is optional and defaults to
595 --output.
596
597 --json-pretty
598 Pretty-print the JSON report. Implies --json. Default: False.
599
600 Filter Options
601 Filters decide which files are included in the report. Any filter must
602 match, and no exclude filter must match. A filter is a regular expres‐
603 sion that matches a path. Filter paths use forward slashes, even on
604 Windows.
605
606 -f <filter>, --filter <filter>
607 Keep only source files that match this filter. Can be specified
608 multiple times. If no filters are provided, defaults to --root.
609
610 -e <exclude>, --exclude <exclude>
611 Exclude source files that match this filter. Can be specified
612 multiple times.
613
614 --gcov-filter <gcov_filter>
615 Keep only gcov data files that match this filter. Can be speci‐
616 fied multiple times.
617
618 --gcov-exclude <gcov_exclude>
619 Exclude gcov data files that match this filter. Can be specified
620 multiple times.
621
622 --exclude-directories <exclude_dirs>
623 Exclude directories that match this regex while searching raw
624 coverage files. Can be specified multiple times.
625
626 GCOV Options
627 The 'gcov' tool turns raw coverage files (.gcda and .gcno) into .gcov
628 files that are then processed by gcovr. The gcno files are generated by
629 the compiler. The gcda files are generated when the instrumented pro‐
630 gram is executed.
631
632 --gcov-executable <gcov_cmd>
633 Use a particular gcov executable. Must match the compiler you
634 are using, e.g. 'llvm-cov gcov' for Clang. Can include addi‐
635 tional arguments. Defaults to the GCOV environment variable, or
636 'gcov': 'gcov'.
637
638 --exclude-unreachable-branches
639 Exclude branch coverage from lines without useful source code
640 (often, compiler-generated "dead" code). Default: False.
641
642 --exclude-throw-branches
643 For branch coverage, exclude branches that the compiler gener‐
644 ates for exception handling. This often leads to more "sensible"
645 coverage reports. Default: False.
646
647 -g, --use-gcov-files
648 Use existing gcov files for analysis. Default: False.
649
650 --gcov-ignore-parse-errors
651 Skip lines with parse errors in GCOV files instead of exiting
652 with an error. A report will be shown on stderr. Default: False.
653
654 --object-directory <objdir>
655 Override normal working directory detection. Gcovr needs to
656 identify the path between gcda files and the directory where the
657 compiler was originally run. Normally, gcovr can guess cor‐
658 rectly. This option specifies either the path from gcc to the
659 gcda file (i.e. gcc's '-o' option), or the path from the gcda
660 file to gcc's working directory.
661
662 -k, --keep
663 Keep gcov files after processing. This applies both to files
664 that were generated by gcovr, or were supplied via the
665 --use-gcov-files option. Default: False. Config key:
666 keep-gcov-files.
667
668 -d, --delete
669 Delete gcda files after processing. Default: False. Config key:
670 delete-gcov-files.
671
672 -j <gcov_parallel>
673 Set the number of threads to use in parallel. Config key:
674 gcov-parallel.
675
676 The above Getting Started guide illustrates the use of some command
677 line options. Using Filters is discussed below.
678
679 Using Filters
680 Gcovr tries to only report coverage for files within your project, not
681 for your libraries. This is influenced by the following options:
682
683 · -r, --root
684
685 · -f, --filter
686
687 · -e, --exclude
688
689 · --gcov-filter
690
691 · --gcov-exclude
692
693 · --exclude-directories
694
695 · (the current working directory where gcovr is invoked)
696
697 These options take filters. A filter is a regular expression that
698 matches a file path. Because filters are regexes, you will have to
699 escape “special” characters with a backslash \.
700
701 Always use forward slashes / as path separators, even on Windows:
702
703 · wrong: --filter C:\project\src\
704
705 · correct: --filter C:/project/src/
706
707 If the filter looks like an absolute path, it is matched against an
708 absolute path. Otherwise, the filter is matched against a relative
709 path, where that path is relative to the current directory. Examples
710 of relative filters:
711
712 · --filter subdir/ matches only that subdirectory
713
714 · --filter '\.\./src/' matches a sibling directory ../src. But because
715 a dot . matches any character in a regex, we have to escape it. You
716 have to use additional shell escaping. This example uses single
717 quotes for Bash or POSIX shell.
718
719 · --filter '(.+/)?foo\.c$' matches only files called foo.c. The regex
720 must match from the start of the relative path, so we ignore any
721 leading directory parts with (.+/)?. The $ at the end ensures that
722 the path ends here.
723
724 If no --filter is provided, the --root is turned into a default filter.
725 Therefore, files outside of the --root directory are excluded.
726
727 To be included in a report, the source file must match any --filter,
728 and must not match any --exclude filter.
729
730 The --gcov-filter and --gcov-exclude filters apply to the .gcov files
731 created by gcov. This is useful mostly when running gcov yourself, and
732 then invoking gcovr with -g/--use-gcov-files. But these filters also
733 apply when gcov is launched by gcovr.
734
735 Speeding up coverage data search
736 The --exclude-directories filter is used while searching for raw cover‐
737 age data (or for existing .gcov files when --use-gcov-files is active).
738 This filter is matched against directory paths, not file paths. If a
739 directory matches, all its contents (files and subdirectories) will be
740 excluded from the search. For example, consider this build directory:
741
742 build/
743 ├─ main.o
744 ├─ main.gcda
745 ├─ main.gcno
746 ├─ a/
747 │ ├─ awesome_code.o
748 │ ├─ awesome_code.gcda
749 │ └─ awesome_code.gcno
750 └─ b/
751 ├─ better_code.o
752 ├─ better_code.gcda
753 └─ better_code.gcno
754
755 If we run gcovr --exclude-directories 'build/a$', this will exclude
756 anything in the build/a directory but will use the coverage data for
757 better_code.o and main.o.
758
759 This can speed up gcovr when you have a complicated build directory
760 structure. Consider also using the search_paths or --object-directory
761 arguments to specify where gcovr starts searching. If you are unsure
762 which directories are being searched, run gcovr in --verbose mode.
763
764 For each found coverage data file gcovr will invoke the gcov tool.
765 This is typically the slowest part, and other filters can only be
766 applied after this step. In some cases, parallel execution with the -j
767 option might be helpful to speed up processing.
768
769 Filters for symlinks
770 Gcovr matches filters against real paths that have all their symlinks
771 resolved. E.g. consider this project layout:
772
773 /home/you/
774 ├─ project/ (pwd)
775 │ ├─ src/
776 │ ├─ relevant-library/ -> ../external-library/
777 │ └─ ignore-this/
778 └─ external-library/
779 └─ src/
780
781 Here, the relevant-library has the real path /home/you/exter‐
782 nal-library.
783
784 To write a filter that includes both src/ and relevant-library/src/, we
785 cannot use --filter relevant-library/src/ because that contains a sym‐
786 link. Instead, we have to use an absolute path to the real name:
787
788 gcovr --filter src/ --filter /home/you/external-library/src/
789
790 or a relative path to the real path:
791
792 gcovr --filter src/ --filter '\.\./external-library/src/'
793
794 NOTE:
795 This section discusses symlinks on Unix systems. The behavior under
796 Windows is unclear. If you have more insight, please update this
797 section by submitting a pull request (see our contributing guide).
798
799 Configuration Files
800 WARNING:
801 Config files are an experimental feature and may be subject to
802 change without prior notice.
803
804 Defaults for the command line options can be set in a configuration
805 file. Example:
806
807 filter = src/
808 html-details = yes # info about each source file
809 output = build/coverage.html
810
811 How the configuration file is found: If a --config option is provided,
812 that file is used. Otherwise, a gcovr.cfg file in the --root directory
813 is used, if that file exists.
814
815 Each line contains a key = value pair. Space around the = is optional.
816 The value may be empty. Comments start with a hash # and ignore the
817 rest of the line, but cannot start within a word. Empty lines are also
818 ignored.
819
820 The available config keys correspond closely to the command line
821 options, and are parsed similarly. In most cases, the name of a long
822 command line option can be used as a config key. If not, this is docu‐
823 mented in the option's help message. For example, --gcov-executable
824 can be set via the gcov-executable config key. But --branches is set
825 via txt-branch.
826
827 Just like command line options, the config keys can be specified multi‐
828 ple times. Depending on the option the last one wins or a list will be
829 built. For example, --filter can be provided multiple times:
830
831 # Only show coverage for files in src/, lib/foo, or for main.cpp files.
832 filter = src/
833 filter = lib/foo/
834 filter = *./main\.cpp
835
836 Note that relative filters specified in config files will be inter‐
837 preted relative to the location of the config file itself.
838
839 Option arguments are parsed with the following precedence:
840
841 · First the config file is parsed, if any.
842
843 · Then, all command line arguments are added.
844
845 · Finally, if an option was specified neither in a config file nor on
846 the command line, its documented default value is used.
847
848 Therefore, it doesn't matter whether a value is provided in the config
849 file or the command line.
850
851 Boolean flags are treated specially. When their config value is “yes”
852 they are enabled, as if the flag had been provided on the command line.
853 When their value is “no”, they are explicitly disabled by assigning
854 their default value. The -j flag is special as it takes an optional
855 argument. In the config file, gcov-parallel = yes would refer to the
856 no-argument form, whereas gcov-parallel = 4 would provide an explicit
857 argument.
858
859 Some config file syntax is explicitly reserved for future extensions:
860 Semicolon comments, INI-style sections, multi-line values, quoted val‐
861 ues, variable substitutions, alternative key–value separators, …
862
863 Exclusion Markers
864 You can exclude parts of your code from coverage metrics.
865
866 · If GCOVR_EXCL_LINE appears within a line, that line is ignored.
867
868 · If GCOVR_EXCL_START appears within a line, all following lines
869 (including the current line) are ignored until a GCOVR_EXCL_STOP
870 marker is encountered.
871
872 Instead of GCOVR_*, the markers may also start with GCOV_* or LCOV_*.
873 However, start and stop markers must use the same style. The markers
874 are not configurable.
875
876 In the excluded regions, any coverage is excluded. It is not currently
877 possible to exclude only branch coverage in that region. In particu‐
878 lar, lcov's EXCL_BR markers are not supported (see issue #121).
879
880 Acknowledgements
881 Gcovr is maintained by:
882 William Hart, John Siirola, and Lukas Atkinson.
883
884 The following developers contributed to gcovr (ordered alphabetically):
885 alex43dm, Andrew Stone, Arvin Schnell, Attie Grande, Bernhard Brein‐
886 bauer, Carlos Jenkins, Cezary Gapiński Christian Taedcke, Dave
887 George, Dom Postorivo, goriy, ja11sop, James Reynolds, Jeremy Fixe‐
888 mer, Jessica Levine, Joel Klinghed, John Siirola, Jörg Kreuzberger,
889 Kai Blaschke, Kevin Cai, libPhipp, Lukas Atkinson, Luke Woydziak,
890 Leon Ma, Marek Kurdej, Martin Mraz, Matsumoto Taichi, Matthew
891 Stadelman, Matthias Schmieder, Matthieu Darbois, Michael Förderer,
892 Michał Pszona, Mikael Salson, Mikk Leini, Nikolaj Schumacher, Piotr
893 Dziwinski, Phil Clapham, Richard Kjerstadius, Reto Schneider, Robert
894 Rosengren, Songmin Li, Steven Myint, Sylvestre Ledru, Tilo Wiedera,
895 trapzero, Will Thompson, William Hart, and possibly others.
896
897 The development of Gcovr has been partially supported by Sandia
898 National Laboratories. Sandia National Laboratories is a multi-program
899 laboratory managed and operated by Sandia Corporation, a wholly owned
900 subsidiary of Lockheed Martin Corporation, for the U.S. Department of
901 Energy's National Nuclear Security Administration under contract
902 DE-AC04-94AL85000.
903
905 How to collect coverage for C extensions in Python
906 Collecting code coverage data on the C code that makes up a Python
907 extension module is not quite as straightforward as with a regular C
908 program.
909
910 As with a normal C project, we have to compile our code with coverage
911 instrumentation. Here, we export CFLAGS="--coverage" and then run
912 python3 setup.py build_ext.
913
914 Unfortunately, build_ext can rebuild a source file even if the current
915 object file is up to date. If multiple extension modules share the
916 same source code file, gcov will get confused by the different time‐
917 stamps and report inaccurate coverage. It is nontrivial to adapt the
918 build_ext process to avoid this.
919
920 Instead, we can use the ccache utility to make the compilation lazy
921 (works best on Unix systems). Before we invoke the build_ext step, we
922 first export CC="ccache gcc". Ccache works well but isn't absolutely
923 perfect, see the ccache manual for caveats.
924
925 A shell session might look like this:
926
927 # Set required env vars
928 export CFLAGS="--coverage"
929 export CC="ccache gcc"
930
931 # clear out build files so we get a fresh compile
932 rm -rf build/temp.* # contains old .gcda, .gcno files
933 rm -rf build/lib.*
934
935 # rebuild extensions
936 python3 setup.py build_ext --inplace # possibly --force
937
938 # run test command i.e. pytest
939
940 # run gcovr
941 rm -rf coverage; mkdir coverage
942 gcovr --filter src/ --print-summary --html-details -o coverage/index.html
943
945 What is the difference between lcov and gcovr?
946 Both lcov and gcovr are tools to create coverage reports.
947
948 Gcovr was originally created as a simple script to provide a convenient
949 command line interface to gcov that produced more easily digestible
950 output similar to Python's coverage utilities.
951
952 Later, we added XML output that could be used with the Cobertura plugin
953 of the Jenkins continuous integration server. This gave us nice cover‐
954 age reports for C/C++ code in Jenkins.
955
956 HTML output was added much later. If all you need is HTML, pick which‐
957 ever one produces the output you like better or integrates easier with
958 your existing workflow.
959
960 Lcov is a far older project that is part of the Linux Test Project. It
961 provides some features that gcovr does not have: For example, lcov has
962 explicit support for capturing Linux kernel coverage. Lcov also sup‐
963 ports various trace file manipulation functions such as merging trace
964 files from different test runs. You can learn more at the lcov website
965 or the lcov GitHub repository.
966
967 Why does C++ code have so many uncovered branches?
968 Gcovr's branch coverage reports are based on GCC's -profile-arcs fea‐
969 ture, which uses the compiler's control flow graph (CFG) of each func‐
970 tion to determine branches. This is a very low-level view: to under‐
971 stand the branches in a given function, it can help to view the func‐
972 tion's assembly, e.g. via the Godbolt Compiler Explorer.
973
974 What gcovr calls a branch is in fact an arc between basic blocks in the
975 CFG. This means gcovr's reports have many branches that are not caused
976 by if statements! For example:
977
978 · Arcs are caused by C/C++ branching operators: for, if, while,
979 switch/case, &&, ||, ? :. Note that switches are often compiled as a
980 decision tree which introduces extra arcs, not just one per case.
981
982 · (Arcs into another function are not shown.)
983
984 · Arcs are caused when a function that may throw returns: one arc to
985 the next block or statement for normal returns, and one arc to an
986 exception handler for exceptions, if this function contains an excep‐
987 tion handler. Every local variable with a destructor is an exception
988 handler as well.
989
990 · Compiler-generated code that deals with exceptions often needs extra
991 branches: throw statements, catch clauses, and destructors.
992
993 · Extra arcs are created for static initialization and destruction.
994
995 · Arcs may be added or removed by compiler optimizations. If you com‐
996 pile without optimizations, some arcs may even be unreachable!
997
998 Gcovr is not able to remove any “unwanted” branches because GCC's gcov
999 tool does not make the necessary information available, and because
1000 different projects are interested in different kinds of branches. How‐
1001 ever, gcovr has the following options to reduce unwanted branches:
1002
1003 With the gcovr --exclude-unreachable-branches option, gcovr parses the
1004 source code to see whether that line even contains any code. If the
1005 line is empty or only contains curly braces, this could be an indica‐
1006 tion of compiler-generated code that was mis-attributed to that line
1007 (such as that for static destruction) and branch coverage will be
1008 ignored on that line.
1009
1010 With the gcovr --exclude-throw-branches option, exception-only branches
1011 will be ignored. These are typically arcs from a function call into an
1012 exception handler.
1013
1014 Compiling with optimizations will typically remove unreachable branches
1015 and remove superfluous branches, but makes the coverage report less
1016 exact. For example, branching operators might be optimized away. See
1017 also: Gcov and Optimization in the GCC documentation.
1018
1019 Despite these approaches, 100% branch coverage will be impossible for
1020 most programs.
1021
1022 Why are uncovered files not reported?
1023 Gcovr does report files that have zero coverage, even when no .gcda
1024 file is available for that compilation unit.
1025
1026 However, the gcov tool in some versions of GCC refuses to generate out‐
1027 put for uncovered files.
1028
1029 To fix this, upgrade GCC to:
1030
1031 · version 5.5 or later,
1032
1033 · version 6.2 or later, or
1034
1035 · any version since 7.
1036
1037 Note that the compiler may ignore inline functions that are never used.
1038
1040 This document contains:
1041
1042 · our guidelines for bug reports
1043
1044 · general contribution guidelines
1045
1046 · a checklist for pull requests
1047
1048 · a developer guide that explains the development environment, project
1049 structure, and test suite
1050
1051 How to report bugs
1052 When reporting a bug, first search our issues to avoid duplicates. In
1053 your bug report, please describe what you expected gcovr to do, and
1054 what it actually did. Also try to include the following details:
1055
1056 · how you invoked gcovr, i.e. the exact flags and from which directory
1057
1058 · your project layout
1059
1060 · your gcovr version
1061
1062 · your compiler version
1063
1064 · your operating system
1065
1066 · and any other relevant details.
1067
1068 Ideally, you can provide a short script and the smallest possible
1069 source file to reproduce the problem.
1070
1071 How to help
1072 If you would like to help out, please take a look at our open issues
1073 and pull requests. The issues labeled help wanted and needs review
1074 would have the greatest impact.
1075
1076 There are many ways how you can help:
1077
1078 · assist other users with their problems
1079
1080 · share your perspective as a gcovr user in discussions
1081
1082 · test proposed changes in your real-world projects
1083
1084 · improve our documentation
1085
1086 · submit pull requests with bug fixes and enhancements
1087
1088 How to submit a Pull Request
1089 Thank you for helping with gcovr development! Please follow this
1090 checklist for your pull request:
1091
1092 · Is this a good approach? Fixing open issues is always welcome! If
1093 you want to implement an enhancement, please discuss it first as a
1094 GitHub issue.
1095
1096 · Does it work? Please run the tests locally:
1097
1098 python -m pytest
1099
1100 In any case, the tests will run automatically when you open the pull
1101 request. But please prevent unnecessary build failures and run the
1102 tests yourself first. If you cannot run the tests locally, you can
1103 activate Travis CI or Appveyor for your fork.
1104
1105 If you add new features, please try to add a test case.
1106
1107 · Does it conform to the style guide? The source code should conform
1108 to the PEP 8 standard. Please check your code:
1109
1110 python -m flake8 doc gcovr --ignore E501,W503
1111
1112 · Add yourself as an author. If this is your first contribution to
1113 gcovr, please add yourself to the AUTHORS.txt file.
1114
1115 · One change at a time. Please keep your commits and your whole pull
1116 request fairly small, so that the changes are easy to review. Each
1117 commit should only contain one kind of change, e.g. refactoring or
1118 new functionality.
1119
1120 · Why is this change necessary? When you open the PR, please explain
1121 why we need this change and what your PR does. If this PR fixes an
1122 open issue, reference that issue in the pull request description.
1123
1124 Once you submit the PR, it will be automatically tested on Windows and
1125 Linux, and code coverage will be collected. Your code will be
1126 reviewed. This can take a week. Please fix any issues that are dis‐
1127 covered during this process. Feel free to force-push your updates to
1128 the pull request branch.
1129
1130 If you need assistance for your pull request, you can
1131
1132 · chat in our Gitter room
1133
1134 · discuss your problem in an issue
1135
1136 · open an unfinished pull request as a work in progress (WIP), and
1137 explain what you've like to get reviewed
1138
1139 How to set up a development environment
1140 · (Optional) Fork the project on GitHub.
1141
1142 · Clone the git repository.
1143
1144 · (Optional) Set up a virtualenv.
1145
1146 · Install gcovr in development mode, and install the test requirements:
1147
1148 pip install -e .
1149 pip install -r requirements.txt
1150
1151 You can then run gcovr as gcovr or python -m gcovr.
1152
1153 Run the tests to verify that everything works (see below).
1154
1155 · (Optional) Install documentation requirements:
1156
1157 pip install -r doc/requirements.txt
1158
1159 See doc/README.txt for details on working with the documentation.
1160
1161 · (Optional) Activate Travis and Appveyor for your forked GitHub repos‐
1162 itory, so that the cross-platform compatibility tests get run when‐
1163 ever you push your work to your repository. These tests will also be
1164 run when you open a pull request to the main gcovr repository.
1165
1166 Tip: If you have problems getting everything set up, consider looking
1167 at the .travis.yml (Linux) and appveyor.yml (Windows) files.
1168
1169 On Windows, you will need to install a GCC toolchain as the tests
1170 expect a Unix-like environment. You can use MinGW-W64 or MinGW. To
1171 run the tests, please make sure that the make and cmake from your MinGW
1172 distribution are in the system PATH.
1173
1174 Project Structure
1175 ┌───────────────────┬────────────────────────────┐
1176 │Path │ Description │
1177 ├───────────────────┼────────────────────────────┤
1178 │/ │ project root │
1179 ├───────────────────┼────────────────────────────┤
1180 │/gcovr/ │ the gcovr source code │
1181 │ │ (Python module) │
1182 ├───────────────────┼────────────────────────────┤
1183 │/gcovr/__main__.py │ command line interface + │
1184 │ │ top-level behaviour │
1185 ├───────────────────┼────────────────────────────┤
1186 │/gcovr/templates/ │ HTML report templates │
1187 ├───────────────────┼────────────────────────────┤
1188 │/gcovr/tests/ │ unit tests + integration │
1189 │ │ test corpus │
1190 ├───────────────────┼────────────────────────────┤
1191 │/setup.py │ Python package configura‐ │
1192 │ │ tion │
1193 ├───────────────────┼────────────────────────────┤
1194 │/doc/ │ documentation │
1195 ├───────────────────┼────────────────────────────┤
1196 │/doc/sources/ │ user guide + website │
1197 ├───────────────────┼────────────────────────────┤
1198 │/doc/examples/ │ runnable examples for the │
1199 │ │ user guide │
1200 └───────────────────┴────────────────────────────┘
1201
1202 The program entrypoint and command line interface is in
1203 gcovr/__main__.py. The coverage data is parsed in the gcovr.gcov mod‐
1204 ule. The HTML, XML, text, and summary reports are in gcovr.html_gener‐
1205 ator and respective modules.
1206
1207 Test suite
1208 The tests are in the gcovr/tests directory. You can run the tests with
1209 python -m pytest.
1210
1211 There are unit tests for some parts of gcovr, and a comprehensive cor‐
1212 pus of example projects that are executed as the test_gcovr.py test.
1213 Each gcovr/tests/* directory is one such example project.
1214
1215 Each project in the corpus contains a Makefile and a reference direc‐
1216 tory. The Makefile controls how the project is built, and how gcovr
1217 should be invoked. The reference directory contains baseline files
1218 against which the gcovr output is compared. Each project is tested
1219 three times to cover txt, html, and xml output.
1220
1221 Because the tests are a bit slow, you can limit the tests to a specific
1222 test file, example project, or output format. For example:
1223
1224 # run only XML tests
1225 python -m pytest -k xml
1226
1227 # run the simple1 tests
1228 python -m pytest -k simple1
1229
1230 # run the simple1 tests only for XML
1231 python -m pytest -k 'xml and simple1'
1232
1233 To see all tests, run pytest in -v verbose mode. To see which tests
1234 would be run, add the --collect-only option.
1235
1236 The tests currently assume that you are using GCC 5.
1237
1238 Become a gcovr developer
1239 After you've contributed a bit (whether with discussions, documenta‐
1240 tion, or code), consider becoming a gcovr developer. As a developer,
1241 you can:
1242
1243 · manage issues and pull requests (label and close them)
1244
1245 · review pull requests (a developer must approve each PR before it can
1246 be merged)
1247
1248 · participate in votes
1249
1250 Just open an issue that you're interested, and we'll have a quick vote.
1251
1253 gcovr Release History and Change Log
1254
1255 Future Directions
1256 WARNING:
1257 Python 2.7 will reach its end of life on Jan 1, 2020. With its
1258 first release on or after that date, gcovr will drop support for
1259 that version. Subsequently, gcovr will only support Python versions
1260 that enjoy upstream support.
1261
1262 Please note that gcovr does not use a strict SemVer version number.
1263 When support for a Python version is dropped, gcovr will not neces‐
1264 sarily increment its major version.
1265
1266 4.2 (6 November 2019)
1267 Breaking changes:
1268
1269 · Dropped support for Python 3.4.
1270
1271 · Format flag parameters like --xml or --html now take an optional
1272 output file name. This potentially changes the interpretation of
1273 search paths. In gcovr --xml foo, previous gcovr versions would
1274 search the foo directory for coverage data. Now, gcovr will try
1275 to write the Cobertura report to the foo file. To keep the old
1276 meaning, separate positional arguments like gcovr --xml -- foo.
1277
1278 Improvements and new features:
1279
1280 · Configuration file support (experimental). (#167, #229, #279,
1281 #281, #293, #300, #304)
1282
1283 · JSON output. (#301, #321, #326)
1284
1285 · Combining tracefiles with gcovr --add-tracefile. (#10, #326)
1286
1287 · SonarQube XML Output. (#308)
1288
1289 · Handle cyclic symlinks correctly during coverage data search. (‐
1290 #284)
1291
1292 · Simplification of --object-directory heuristics. (#18, #273,
1293 #280)
1294
1295 · Exception-only code like a catch clause is now shown as uncovered.
1296 (#283)
1297
1298 · New --exclude-throw-branches option to exclude exception handler
1299 branches. (#283)
1300
1301 · Support --root .. style invocation, which might fix some
1302 CMake-related problems. (#294)
1303
1304 · Fix wrong names in report when source and build directories have
1305 similar names. (#299)
1306
1307 · Stricter argument handling. (#267)
1308
1309 · Reduce XML memory usage by moving to lxml. (#1, #118, #307)
1310
1311 · Can write multiple reports at the same time by giving the output
1312 file name to the report format parameter. Now, gcovr --html -o
1313 cov.html and gcovr --html cov.html are equivalent. (#291)
1314
1315 · Override gcov locale properly. (#334)
1316
1317 · Make gcov parser more robust when used with GCC 8. (#315)
1318
1319 Known issues:
1320
1321 · The --keep option only works when using existing gcov files with
1322 -g/--use-gcov-files. (#285, #286)
1323
1324 · Gcovr may get confused when header files in different directories
1325 have the same name. (#271)
1326
1327 · Gcovr may not work when no en_US locale is available. (#166)
1328
1329 Documentation:
1330
1331 · Exclusion marker documentation.
1332
1333 · FAQ: exception branches (#283)
1334
1335 · FAQ: uncovered files not shown (#33, #100, #154, #290, #298)
1336
1337 Internal changes:
1338
1339 · More tests. (#269, #268, #269)
1340
1341 · Refactoring and removal of dead code. (#280)
1342
1343 · New internal data model.
1344
1345 4.1 (2 July 2018)
1346 · Fixed/improved --exclude-directories option. (#266)
1347
1348 · New "Cookbook" section in the documentation. (#265)
1349
1350 4.0 (17 June 2018)
1351 Breaking changes:
1352
1353 · This release drops support for Python 2.6. (#250)
1354
1355 · PIP is the only supported installation method.
1356
1357 · No longer encoding-agnostic under Python 2.7. If your source
1358 files do not use the system encoding (probably UTF-8), you will
1359 have to specify a --source-encoding. (#148, #156, #256)
1360
1361 · Filters now use forward slashes as path separators, even on Win‐
1362 dows. (#191, #257)
1363
1364 · Filters are no longer normalized into pseudo-paths. This could
1365 change the interpretation of filters in some edge cases.
1366
1367 Improvements and new features:
1368
1369 · Improved --help output. (#236)
1370
1371 · Parse the GCC 8 gcov format. (#226, #228)
1372
1373 · New --source-encoding option, which fixes decoding under Python 3.
1374 (#256)
1375
1376 · New --gcov-ignore-parse-errors flag. By default, gcovr will now
1377 abort upon parse errors. (#228)
1378
1379 · Detect the error when gcov cannot create its output files (#243,
1380 #244)
1381
1382 · Add -j flag to run gcov processes in parallel. (#3, #36, #239)
1383
1384 · The --html-details flag now implies --html. (#93, #211)
1385
1386 · The --html output can now be used without an --output filename (‐
1387 #223)
1388
1389 · The docs are now managed with Sphinx. (#235, #248, #249, #252,
1390 #253)
1391
1392 · New --html-title option to change the title of the HTML report.
1393 (#261, #263)
1394
1395 · New options --html-medium-threshold and --html-high-threshold to
1396 customize the color legend. (#261, #264)
1397
1398 Internal changes:
1399
1400 · Huge refactoring. (#214, #215, #221 #225, #228, #237, #246)
1401
1402 · Various testing improvements. (#213, #214, #216, #217, #218, #222,
1403 #223, #224, #227, #240, #241, #245)
1404
1405 · HTML reports are now rendered with Jinja2 templates. (#234)
1406
1407 · New contributing guide. (#253)
1408
1409 3.4 (12 February 2018)
1410 · Added --html-encoding command line option (#139).
1411
1412 · Added --fail-under-line and --fail-under-branch options, which
1413 will error under a given minimum coverage. (#173, #116)
1414
1415 · Better pathname resolution heuristics for --use-gcov-file. (#146)
1416
1417 · The --root option defaults to current directory '.'.
1418
1419 · Improved reports for "(", ")", ";" lines.
1420
1421 · HTML reports show full timestamp, not just date. (#165)
1422
1423 · HTML reports treat 0/0 coverage as NaN, not 100% or 0%. (#105,
1424 #149, #196)
1425
1426 · Add support for coverage-04.dtd Cobertura XML format (#164, #186)
1427
1428 · Only Python 2.6+ is supported, with 2.7+ or 3.4+ recommended. (‐
1429 #195)
1430
1431 · Added CI testing for Windows using Appveyor. (#189, #200)
1432
1433 · Reports use forward slashes in paths, even on Windows. (#200)
1434
1435 · Fix to support filtering with absolute paths.
1436
1437 · Fix HTML generation with Python 3. (#168, #182, #163)
1438
1439 · Fix --html-details under Windows. (#157)
1440
1441 · Fix filters under Windows. (#158)
1442
1443 · Fix verbose output when using existing gcov files (#143, #144)
1444
1445 3.3 (6 August 2016)
1446 · Added CI testing using TravisCI
1447
1448 · Added more tests for out of source builds and other nested builds
1449
1450 · Avoid common file prefixes in HTML output (#103)
1451
1452 · Added the --execlude-directories argument to exclude directories
1453 from the search for symlinks (#87)
1454
1455 · Added branches taken/not taken to HTML (#75)
1456
1457 · Use --object-directory to scan for gcov data files (#72)
1458
1459 · Improved logic for nested makefiles (#135)
1460
1461 · Fixed unexpected semantics with --root argument (#108)
1462
1463 · More careful checks for covered lines (#109)
1464
1465 3.2 (5 July 2014)
1466 · Adding a test for out of source builds
1467
1468 · Using the starting directory when processing gcov filenames. (‐
1469 #42)
1470
1471 · Making relative paths the default in html output.
1472
1473 · Simplify html bar with coverage is zero.
1474
1475 · Add option for using existing gcov files (#35)
1476
1477 · Fixing --root argument processing (#27)
1478
1479 · Adding logic to cover branches that are ignored (#28)
1480
1481 3.1 (6 December 2013)
1482 · Change to make the -r/--root options define the root directory for
1483 source files.
1484
1485 · Fix to apply the -p option when the --html option is used.
1486
1487 · Adding new option, '--exclude-unreachable-branches' that will
1488 exclude branches in certain lines from coverage report.
1489
1490 · Simplifying and standardizing the processing of linked files.
1491
1492 · Adding tests for deeply nested code, and symbolic links.
1493
1494 · Add support for multiple —filter options in same manner as
1495 —exclude option.
1496
1497 3.0 (10 August 2013)
1498 · Adding the '--gcov-executable' option to specify the name/location
1499 of the gcov executable. The command line option overrides the
1500 environment variable, which overrides the default 'gcov'.
1501
1502 · Adding an empty "<methods/>" block to <classes/> in the XML out‐
1503 put: this makes out XML complient with the Cobertura DTD. (#3951)
1504
1505 · Allow the GCOV environment variable to override the default 'gcov'
1506 executable. The default is to search the PATH for 'gcov' if the
1507 GCOV environment variable is not set. (#3950)
1508
1509 · Adding support for LCOV-style flags for excluding certain lines
1510 from coverage analysis. (#3942)
1511
1512 · Setup additional logic to test with Python 2.5.
1513
1514 · Added the --html and --html-details options to generate HTML.
1515
1516 · Sort output for XML to facilitate baseline tests.
1517
1518 · Added error when the --object-directory option specifies a bad
1519 directory.
1520
1521 · Added more flexible XML testing, which can ignore XML elements
1522 that frequently change (e.g. timestamps).
1523
1524 · Added the '—xml-pretty' option, which is used to generate pretty
1525 XML output for the user manual.
1526
1527 · Many documentation updates
1528
1529 2.4 (13 April 2012)
1530 · New approach to walking the directory tree that is more robust to
1531 symbolic links (#3908)
1532
1533 · Normalize all reported path names
1534
1535 · Normalize using the full absolute path (#3921)
1536
1537 · Attempt to resolve files referenced through symlinks to a common
1538 project-relative path
1539
1540 · Process gcno files when there is no corresponding gcda file to
1541 provide coverage information for unexecuted modules (#3887)
1542
1543 · Windows compatibility fixes
1544
1545 · Fix for how we parse source: file names (#3913)
1546
1547 · Better handling od EOL indicators (#3920)
1548
1549 · Fix so that gcovr cleans up all .gcov files, even those filtered
1550 by command line arguments
1551
1552 · Added compatibility with GCC 4.8 (#3918)
1553
1554 · Added a check to warn users who specify an empty --root option
1555 (see #3917)
1556
1557 · Force gcov to run with en_US localization, so the gcovr parser
1558 runs correctly on systems with non-English locales (#3898, #3902).
1559
1560 · Segregate warning/error information onto the stderr stream (#3924)
1561
1562 · Miscellaneous (Python 3.x) portability fixes
1563
1564 · Added the master svn revision number as part of the verson identi‐
1565 fier
1566
1567 2.3.1 (6 January 2012)
1568 · Adding support for Python 3.x
1569
1570 2.3 (11 December 2011)
1571 · Adding the --gcov-filter and --gcov-exclude options.
1572
1573 2.2 (10 December 2011)
1574 · Added a test driver for gcovr.
1575
1576 · Improved estimation of the <sources> element when using gcovr with
1577 filters.
1578
1579 · Added revision and date keywords to gcovr so it is easier to iden‐
1580 tify what version of the script users are using (especially when
1581 they are running a snapshot from trunk).
1582
1583 · Addressed special case mentioned in [comment:ticket:3884:1]: do
1584 not truncate the reported file name if the filter does not start
1585 matching at the beginning of the string.
1586
1587 · Overhaul of the --root / --filter logic. This should resolve the
1588 issue raised in #3884, along with the more general filter issue
1589 raised in [comment:ticket:3884:1]
1590
1591 · Overhaul of gcovr's logic for determining gcc/g++'s original work‐
1592 ing directory. This resolves issues introduced in the original
1593 implementation of --object-directory (#3872, #3883).
1594
1595 · Bugfix: gcovr was only including a <sources> element in the XML
1596 report if the user specified -r (#3869)
1597
1598 · Adding timestamp and version attributes to the gcovr XML report
1599 (see #3877). It looks like the standard Cobertura output reports
1600 number of seconds since the epoch for the timestamp and a doted
1601 decimal version string. Now, gcovr reports seconds since the
1602 epoch and "gcovr ``"+``__version__ (e.g. "gcovr 2.2") to differen‐
1603 tiate it from a pure Cobertura report.
1604
1605 2.1 (26 November 2010)
1606 · Added the --object-directory option, which allows for a flexible
1607 specification of the directory that contains the objects generated
1608 by gcov.
1609
1610 · Adding fix to compare the absolute path of a filename to an exclu‐
1611 sion pattern.
1612
1613 · Adding error checking when no coverage results are found. The line
1614 and branch counts can be zero.
1615
1616 · Adding logic to process the -o/--output option (#3870).
1617
1618 · Adding patch to scan for lines that look like:
1619
1620 creating `foo'
1621
1622 as well as
1623
1624 creating 'foo'
1625
1626 · Changing the semantics for EOL to be portable for MS Windows.
1627
1628 · Add attributes to xml format so that it could be used by hud‐
1629 son/bamboo with cobertura plug-in.
1630
1631 2.0 (22 August 2010)
1632 · Initial release as a separate package. Earlier versions of gcovr
1633 were managed within the 'fast' Python package.
1634
1636 Copyright 2013-2018 the gcovr authors
1637
1638 Copyright 2013 Sandia Corporation. Under the terms of Contract
1639 DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
1640 certain rights in this software.
1641
1642 Gcovr is available under the 3-clause BSD License. See LICENSE.txt for
1643 full details. See AUTHORS.txt for the full list of contributors.
1644
1645 Gcovr development moved to this repository in September, 2013 from San‐
1646 dia National Laboratories.
1647
1649 the gcovr authors
1650
1652 2020, the gcovr authors
1653
1654
1655
1656
16574.2 Jul 27, 2020 GCOVR(1)