1GCOVR(1) gcovr GCOVR(1)
2
6 gcovr - gcovr Documentation
7 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 The gcovr command can produce different kinds of coverage reports:
14 · default: compact human-readable summaries
16 · --html: HTML summaries
18 · --html-details: HTML report with annotated source files
20 · --xml: machine readable XML reports in Cobertura format
22 · --sonarqube: machine readable XML reports in Sonarqube format
24 · --json: JSON report with source files structure and coverage
26 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 Quick Links
33 · Getting Help
35 · Submit a ticket
37 · Stack Overflow
39 · Chat on Gitter
41 · Install from PyPI: pip install gcovr
43 · Source Code on GitHub
45 · changelog
47
49 Gcovr is available as a Python package that can be installed via pip.
50 Install newest stable gcovr release from PyPI:
52 pip install gcovr
54 Install development version from GitHub:
56 pip install git+https://github.com/gcovr/gcovr.git
58 Which environments does gcovr support?
60 Python:
62 2.7 and 3.5+.
63 The automated tests run on CPython 2.7, 3.5, and 3.7, and PyPy
65 2.7 and 3.5.
66 Starting in 2020, gcovr will only run on Python versions with
68 upstream support.
69 Last gcovr release for old Python versions:
71 ┌───────┬───────┐
73 │Python │ gcovr │
74 ├───────┼───────┤
75 │2.6 │ 3.4 │
76 ├───────┼───────┤
77 │3.4 │ 4.1 │
78 └───────┴───────┘
79 Operating System:
81 Linux, Windows, and macOS.
82 The automated tests run on Ubuntu 16.04 and Windows Server 2012.
84 Compiler:
86 GCC and Clang.
87 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 The gcovr command can produce different kinds of coverage reports:
97 · default: compact human-readable summaries
99 · --html: HTML summaries
101 · --html-details: HTML report with annotated source files
103 · --xml: machine readable XML reports in Cobertura format
105 · --sonarqube: machine readable XML reports in Sonarqube format
107 · --json: JSON report with source files structure and coverage
109 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 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 This documentation describes Gcovr 4.2.
120 This User Guide provides the following sections:
122 · Getting Started
124 · Tabular Output of Code Coverage
126 · Tabular Output of Branch Coverage
128 · Cobertura XML Output
130 · HTML Output
132 · Sonarqube XML Output
134 · JSON Output
136 · Multiple Output Formats
138 · Combining Tracefiles
140 · The gcovr Command
142 · gcovr
144 · Using Filters
146 · Speeding up coverage data search
148 · Filters for symlinks
150 · Configuration Files
152 · Exclusion Markers
154 · Acknowledgements
156 Related documents:
158 · installation
160 · contributing (includes instructions for bug reports)
162 · cookbook
164 · faq
166 · changelog
168 · license
170 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 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 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 This code executes several subroutines in this program, but some lines
205 in the program are not executed.
206 Tabular Output of Code Coverage
208 We compile example1.cpp with the GCC compiler as follows:
209 g++ -fprofile-arcs -ftest-coverage -fPIC -O0 example.cpp -o program
211 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 The compiler generates the program executable. When we execute this
219 command:
220 ./program
222 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 gcovr -r .
229 generates a text summary of the lines executed:
231 ------------------------------------------------------------------------------
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 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 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 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 Tabular Output of Branch Coverage
264 The gcovr command can also summarize branch coverage using the
265 --branches option:
266 gcovr -r . --branches
268 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 ------------------------------------------------------------------------------
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 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 gcovr -r . --xml-pretty
291 This generates an XML summary of the lines executed:
293 <?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 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 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 HTML Output
337 The gcovr command can also generate a simple HTML output using the
338 --html option:
339 gcovr -r . --html -o example-html.html
341 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 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 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 gcovr -r . --html --html-details -o example-html-details.html
357 This generates the following HTML page for the file example1.cpp:
359 [image]
360 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 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 gcovr --sonarqube coverage.xml
371 The Sonarqube XML format is documented at
373 https://docs.sonarqube.org/latest/analysis/generic-test/.
374 JSON Output
376 The gcovr command can also generate a JSON output using the --json and
377 --json-pretty options:
378 gcovr --json coverage.json
380 The --json-pretty option generates an indented JSON output that is eas‐
382 ier to read.
383 Structure of file is based on gcov JSON intermediate format with addi‐
385 tional key names specific to gcovr.
386 Structure of the JSON is following:
388 {
390 "gcovr/format_version": gcovr_json_version
391 "files": [file]
392 }
393 gcovr_json_version: version of gcovr JSON format
395 Each file has the following form:
397 {
399 "file": file
400 "lines": [line]
401 }
402 file: path to source code file, relative to gcovr root directory.
404 Each line has the following form:
406 {
408 "branches": [branch]
409 "count": count
410 "line_number": line_number
411 "gcovr/noncode": gcovr_noncode
412 }
413 gcovr_noncode: if True coverage info on this line should be ignored
415 Each branch has the following form:
417 {
419 "count": count
420 "fallthrough": fallthrough
421 "throw": throw
422 }
423 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 Multiple JSON files can be merged into the coverage data with sum of
429 lines and branches execution
430 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 The following report format flags can take an optional output file
438 name:
439 · gcovr --xml
441 · gcovr --html
443 · gcovr --html-details
445 · gcovr --sonarqube
447 · gcovr --json
449 Note that --html-details overrides any value of --html if it is
451 present.
452 Combining Tracefiles
454 You can merge coverage data from multiple runs with gcovr --add-trace‐
455 file.
456 For each run, generate JSON output:
458 ... # 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 Next, merge the json files and generate the desired report:
465 gcovr --add-tracefile run-1.json --add-tracefile run-2.json --html-details coverage.html
467 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 gcovr
475 A utility to run gcov and summarize the coverage in simple reports.
476 usage: gcovr [options] [search_paths...]
478 See <http://gcovr.com/> for the full manual.
480 Options
482 search_paths
483 Search these directories for coverage files. Defaults to --root
484 and --object-directory. Config key: search-path.
485 -h, --help
487 Show this help message, then exit.
488 --version
490 Print the version number, then exit.
491 -v, --verbose
493 Print progress messages. Please include this output in bug
494 reports.
495 -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 -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 --config <config>
509 Load that configuration file. Defaults to gcovr.cfg in the
510 --root directory.
511 --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 --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 --source-encoding <source_encoding>
523 Select the source file encoding. Defaults to the system default
524 encoding (UTF-8).
525 Output Options
527 Gcovr prints a text report by default, but can switch to XML or HTML.
528 -o <output>, --output <output>
530 Print output to this filename. Defaults to stdout. Individual
531 output formats can override this.
532 -b, --branches
534 Report the branch coverage instead of the line coverage. For
535 text report only. Config key: txt-branch.
536 -u, --sort-uncovered
538 Sort entries by increasing number of uncovered lines. For text
539 and HTML report.
540 -p, --sort-percentage
542 Sort entries by increasing percentage of uncovered lines. For
543 text and HTML report.
544 -x <output>, --xml <output>
546 Generate a Cobertura XML report. OUTPUT is optional and defaults
547 to --output.
548 --xml-pretty
550 Pretty-print the XML report. Implies --xml. Default: False.
551 --html <output>
553 Generate a HTML report. OUTPUT is optional and defaults to
554 --output.
555 --html-details <output>
557 Add annotated source code reports to the HTML report. Implies
558 --html. OUTPUT is optional and defaults to --output.
559 --html-title <title>
561 Use TITLE as title for the HTML report. Default is Head.
562 --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 --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 --html-absolute-paths
578 Use absolute paths to link the --html-details reports. Defaults
579 to relative links.
580 --html-encoding <html_encoding>
582 Override the declared HTML report encoding. Defaults to UTF-8.
583 See also --source-encoding.
584 -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 --sonarqube <output>
590 Generate sonarqube generic coverage report in this file name.
591 OUTPUT is optional and defaults to --output.
592 --json <output>
594 Generate a JSON report. OUTPUT is optional and defaults to
595 --output.
596 --json-pretty
598 Pretty-print the JSON report. Implies --json. Default: False.
599 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 -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 -e <exclude>, --exclude <exclude>
611 Exclude source files that match this filter. Can be specified
612 multiple times.
613 --gcov-filter <gcov_filter>
615 Keep only gcov data files that match this filter. Can be speci‐
616 fied multiple times.
617 --gcov-exclude <gcov_exclude>
619 Exclude gcov data files that match this filter. Can be specified
620 multiple times.
621 --exclude-directories <exclude_dirs>
623 Exclude directories that match this regex while searching raw
624 coverage files. Can be specified multiple times.
625 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 --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 --exclude-unreachable-branches
639 Exclude branch coverage from lines without useful source code
640 (often, compiler-generated "dead" code). Default: False.
641 --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 -g, --use-gcov-files
648 Use existing gcov files for analysis. Default: False.
649 --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 --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 -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 -d, --delete
669 Delete gcda files after processing. Default: False. Config key:
670 delete-gcov-files.
671 -j <gcov_parallel>
673 Set the number of threads to use in parallel. Config key:
674 gcov-parallel.
675 The above Getting Started guide illustrates the use of some command
677 line options. Using Filters is discussed below.
678 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 · -r, --root
684 · -f, --filter
686 · -e, --exclude
688 · --gcov-filter
690 · --gcov-exclude
692 · --exclude-directories
694 · (the current working directory where gcovr is invoked)
696 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 Always use forward slashes / as path separators, even on Windows:
702 · wrong: --filter C:\project\src\
704 · correct: --filter C:/project/src/
706 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 · --filter subdir/ matches only that subdirectory
713 · --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 · --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 If no --filter is provided, the --root is turned into a default filter.
725 Therefore, files outside of the --root directory are excluded.
726 To be included in a report, the source file must match any --filter,
728 and must not match any --exclude filter.
729 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 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 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 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 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 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 Filters for symlinks
770 Gcovr matches filters against real paths that have all their symlinks
771 resolved. E.g. consider this project layout:
772 /home/you/
774 ├─ project/ (pwd)
775 │ ├─ src/
776 │ ├─ relevant-library/ -> ../external-library/
777 │ └─ ignore-this/
778 └─ external-library/
779 └─ src/
780 Here, the relevant-library has the real path /home/you/exter‐
782 nal-library.
783 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 gcovr --filter src/ --filter /home/you/external-library/src/
789 or a relative path to the real path:
791 gcovr --filter src/ --filter '\.\./external-library/src/'
793 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 Configuration Files
800 WARNING:
801 Config files are an experimental feature and may be subject to
802 change without prior notice.
803 Defaults for the command line options can be set in a configuration
805 file. Example:
806 filter = src/
808 html-details = yes # info about each source file
809 output = build/coverage.html
810 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 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 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 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 # 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 Note that relative filters specified in config files will be inter‐
837 preted relative to the location of the config file itself.
838 Option arguments are parsed with the following precedence:
840 · First the config file is parsed, if any.
842 · Then, all command line arguments are added.
844 · Finally, if an option was specified neither in a config file nor on
846 the command line, its documented default value is used.
847 Therefore, it doesn't matter whether a value is provided in the config
849 file or the command line.
850 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 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 Exclusion Markers
864 You can exclude parts of your code from coverage metrics.
865 · If GCOVR_EXCL_LINE appears within a line, that line is ignored.
867 · 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 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 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 Acknowledgements
881 Gcovr is maintained by:
882 William Hart, John Siirola, and Lukas Atkinson.
883 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 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 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 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 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 A shell session might look like this:
926 # Set required env vars
928 export CFLAGS="--coverage"
929 export CC="ccache gcc"
930 # 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 # rebuild extensions
936 python3 setup.py build_ext --inplace # possibly --force
937 # run test command i.e. pytest
939 # 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 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 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 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 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 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 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 · 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 · (Arcs into another function are not shown.)
983 · 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 · Compiler-generated code that deals with exceptions often needs extra
991 branches: throw statements, catch clauses, and destructors.
992 · Extra arcs are created for static initialization and destruction.
994 · Arcs may be added or removed by compiler optimizations. If you com‐
996 pile without optimizations, some arcs may even be unreachable!
997 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 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 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 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 Despite these approaches, 100% branch coverage will be impossible for
1020 most programs.
1021 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 However, the gcov tool in some versions of GCC refuses to generate out‐
1027 put for uncovered files.
1028 To fix this, upgrade GCC to:
1030 · version 5.5 or later,
1032 · version 6.2 or later, or
1034 · any version since 7.
1036 Note that the compiler may ignore inline functions that are never used.
1038
1040 This document contains:
1041 · our guidelines for bug reports
1043 · general contribution guidelines
1045 · a checklist for pull requests
1047 · a developer guide that explains the development environment, project
1049 structure, and test suite
1050 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 · how you invoked gcovr, i.e. the exact flags and from which directory
1057 · your project layout
1059 · your gcovr version
1061 · your compiler version
1063 · your operating system
1065 · and any other relevant details.
1067 Ideally, you can provide a short script and the smallest possible
1069 source file to reproduce the problem.
1070 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 There are many ways how you can help:
1077 · assist other users with their problems
1079 · share your perspective as a gcovr user in discussions
1081 · test proposed changes in your real-world projects
1083 · improve our documentation
1085 · submit pull requests with bug fixes and enhancements
1087 How to submit a Pull Request
1089 Thank you for helping with gcovr development! Please follow this
1090 checklist for your pull request:
1091 · 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 · Does it work? Please run the tests locally:
1097 python -m pytest
1099 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 If you add new features, please try to add a test case.
1106 · Does it conform to the style guide? The source code should conform
1108 to the PEP 8 standard. Please check your code:
1109 python -m flake8 doc gcovr --ignore E501,W503
1111 · Add yourself as an author. If this is your first contribution to
1113 gcovr, please add yourself to the AUTHORS.txt file.
1114 · 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 · 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 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 If you need assistance for your pull request, you can
1131 · chat in our Gitter room
1133 · discuss your problem in an issue
1135 · open an unfinished pull request as a work in progress (WIP), and
1137 explain what you've like to get reviewed
1138 How to set up a development environment
1140 · (Optional) Fork the project on GitHub.
1141 · Clone the git repository.
1143 · (Optional) Set up a virtualenv.
1145 · Install gcovr in development mode, and install the test requirements:
1147 pip install -e .
1149 pip install -r requirements.txt
1150 You can then run gcovr as gcovr or python -m gcovr.
1152 Run the tests to verify that everything works (see below).
1154 · (Optional) Install documentation requirements:
1156 pip install -r doc/requirements.txt
1158 See doc/README.txt for details on working with the documentation.
1160 · (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 Tip: If you have problems getting everything set up, consider looking
1167 at the .travis.yml (Linux) and appveyor.yml (Windows) files.
1168 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 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 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 Test suite
1208 The tests are in the gcovr/tests directory. You can run the tests with
1209 python -m pytest.
1210 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 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 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 # run only XML tests
1225 python -m pytest -k xml
1226 # run the simple1 tests
1228 python -m pytest -k simple1
1229 # run the simple1 tests only for XML
1231 python -m pytest -k 'xml and simple1'
1232 To see all tests, run pytest in -v verbose mode. To see which tests
1234 would be run, add the --collect-only option.
1235 The tests currently assume that you are using GCC 5.
1237 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 · manage issues and pull requests (label and close them)
1244 · review pull requests (a developer must approve each PR before it can
1246 be merged)
1247 · participate in votes
1249 Just open an issue that you're interested, and we'll have a quick vote.
1251
1253 gcovr Release History and Change Log
1254 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 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 4.2 (6 November 2019)
1267 Breaking changes:
1268 · Dropped support for Python 3.4.
1270 · 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 Improvements and new features:
1279 · Configuration file support (experimental). (#167, #229, #279,
1281 #281, #293, #300, #304)
1282 · JSON output. (#301, #321, #326)
1284 · Combining tracefiles with gcovr --add-tracefile. (#10, #326)
1286 · SonarQube XML Output. (#308)
1288 · Handle cyclic symlinks correctly during coverage data search. (‐
1290 #284)
1291 · Simplification of --object-directory heuristics. (#18, #273,
1293 #280)
1294 · Exception-only code like a catch clause is now shown as uncovered.
1296 (#283)
1297 · New --exclude-throw-branches option to exclude exception handler
1299 branches. (#283)
1300 · Support --root .. style invocation, which might fix some
1302 CMake-related problems. (#294)
1303 · Fix wrong names in report when source and build directories have
1305 similar names. (#299)
1306 · Stricter argument handling. (#267)
1308 · Reduce XML memory usage by moving to lxml. (#1, #118, #307)
1310 · 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 · Override gcov locale properly. (#334)
1316 · Make gcov parser more robust when used with GCC 8. (#315)
1318 Known issues:
1320 · The --keep option only works when using existing gcov files with
1322 -g/--use-gcov-files. (#285, #286)
1323 · Gcovr may get confused when header files in different directories
1325 have the same name. (#271)
1326 · Gcovr may not work when no en_US locale is available. (#166)
1328 Documentation:
1330 · Exclusion marker documentation.
1332 · FAQ: exception branches (#283)
1334 · FAQ: uncovered files not shown (#33, #100, #154, #290, #298)
1336 Internal changes:
1338 · More tests. (#269, #268, #269)
1340 · Refactoring and removal of dead code. (#280)
1342 · New internal data model.
1344 4.1 (2 July 2018)
1346 · Fixed/improved --exclude-directories option. (#266)
1347 · New "Cookbook" section in the documentation. (#265)
1349 4.0 (17 June 2018)
1351 Breaking changes:
1352 · This release drops support for Python 2.6. (#250)
1354 · PIP is the only supported installation method.
1356 · 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 · Filters now use forward slashes as path separators, even on Win‐
1362 dows. (#191, #257)
1363 · Filters are no longer normalized into pseudo-paths. This could
1365 change the interpretation of filters in some edge cases.
1366 Improvements and new features:
1368 · Improved --help output. (#236)
1370 · Parse the GCC 8 gcov format. (#226, #228)
1372 · New --source-encoding option, which fixes decoding under Python 3.
1374 (#256)
1375 · New --gcov-ignore-parse-errors flag. By default, gcovr will now
1377 abort upon parse errors. (#228)
1378 · Detect the error when gcov cannot create its output files (#243,
1380 #244)
1381 · Add -j flag to run gcov processes in parallel. (#3, #36, #239)
1383 · The --html-details flag now implies --html. (#93, #211)
1385 · The --html output can now be used without an --output filename (‐
1387 #223)
1388 · The docs are now managed with Sphinx. (#235, #248, #249, #252,
1390 #253)
1391 · New --html-title option to change the title of the HTML report.
1393 (#261, #263)
1394 · New options --html-medium-threshold and --html-high-threshold to
1396 customize the color legend. (#261, #264)
1397 Internal changes:
1399 · Huge refactoring. (#214, #215, #221 #225, #228, #237, #246)
1401 · Various testing improvements. (#213, #214, #216, #217, #218, #222,
1403 #223, #224, #227, #240, #241, #245)
1404 · HTML reports are now rendered with Jinja2 templates. (#234)
1406 · New contributing guide. (#253)
1408 3.4 (12 February 2018)
1410 · Added --html-encoding command line option (#139).
1411 · Added --fail-under-line and --fail-under-branch options, which
1413 will error under a given minimum coverage. (#173, #116)
1414 · Better pathname resolution heuristics for --use-gcov-file. (#146)
1416 · The --root option defaults to current directory '.'.
1418 · Improved reports for "(", ")", ";" lines.
1420 · HTML reports show full timestamp, not just date. (#165)
1422 · HTML reports treat 0/0 coverage as NaN, not 100% or 0%. (#105,
1424 #149, #196)
1425 · Add support for coverage-04.dtd Cobertura XML format (#164, #186)
1427 · Only Python 2.6+ is supported, with 2.7+ or 3.4+ recommended. (‐
1429 #195)
1430 · Added CI testing for Windows using Appveyor. (#189, #200)
1432 · Reports use forward slashes in paths, even on Windows. (#200)
1434 · Fix to support filtering with absolute paths.
1436 · Fix HTML generation with Python 3. (#168, #182, #163)
1438 · Fix --html-details under Windows. (#157)
1440 · Fix filters under Windows. (#158)
1442 · Fix verbose output when using existing gcov files (#143, #144)
1444 3.3 (6 August 2016)
1446 · Added CI testing using TravisCI
1447 · Added more tests for out of source builds and other nested builds
1449 · Avoid common file prefixes in HTML output (#103)
1451 · Added the --execlude-directories argument to exclude directories
1453 from the search for symlinks (#87)
1454 · Added branches taken/not taken to HTML (#75)
1456 · Use --object-directory to scan for gcov data files (#72)
1458 · Improved logic for nested makefiles (#135)
1460 · Fixed unexpected semantics with --root argument (#108)
1462 · More careful checks for covered lines (#109)
1464 3.2 (5 July 2014)
1466 · Adding a test for out of source builds
1467 · Using the starting directory when processing gcov filenames. (‐
1469 #42)
1470 · Making relative paths the default in html output.
1472 · Simplify html bar with coverage is zero.
1474 · Add option for using existing gcov files (#35)
1476 · Fixing --root argument processing (#27)
1478 · Adding logic to cover branches that are ignored (#28)
1480 3.1 (6 December 2013)
1482 · Change to make the -r/--root options define the root directory for
1483 source files.
1484 · Fix to apply the -p option when the --html option is used.
1486 · Adding new option, '--exclude-unreachable-branches' that will
1488 exclude branches in certain lines from coverage report.
1489 · Simplifying and standardizing the processing of linked files.
1491 · Adding tests for deeply nested code, and symbolic links.
1493 · Add support for multiple —filter options in same manner as
1495 —exclude option.
1496 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 · Adding an empty "<methods/>" block to <classes/> in the XML out‐
1503 put: this makes out XML complient with the Cobertura DTD. (#3951)
1504 · 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 · Adding support for LCOV-style flags for excluding certain lines
1510 from coverage analysis. (#3942)
1511 · Setup additional logic to test with Python 2.5.
1513 · Added the --html and --html-details options to generate HTML.
1515 · Sort output for XML to facilitate baseline tests.
1517 · Added error when the --object-directory option specifies a bad
1519 directory.
1520 · Added more flexible XML testing, which can ignore XML elements
1522 that frequently change (e.g. timestamps).
1523 · Added the '—xml-pretty' option, which is used to generate pretty
1525 XML output for the user manual.
1526 · Many documentation updates
1528 2.4 (13 April 2012)
1530 · New approach to walking the directory tree that is more robust to
1531 symbolic links (#3908)
1532 · Normalize all reported path names
1534 · Normalize using the full absolute path (#3921)
1536 · Attempt to resolve files referenced through symlinks to a common
1538 project-relative path
1539 · Process gcno files when there is no corresponding gcda file to
1541 provide coverage information for unexecuted modules (#3887)
1542 · Windows compatibility fixes
1544 · Fix for how we parse source: file names (#3913)
1546 · Better handling od EOL indicators (#3920)
1548 · Fix so that gcovr cleans up all .gcov files, even those filtered
1550 by command line arguments
1551 · Added compatibility with GCC 4.8 (#3918)
1553 · Added a check to warn users who specify an empty --root option
1555 (see #3917)
1556 · Force gcov to run with en_US localization, so the gcovr parser
1558 runs correctly on systems with non-English locales (#3898, #3902).
1559 · Segregate warning/error information onto the stderr stream (#3924)
1561 · Miscellaneous (Python 3.x) portability fixes
1563 · Added the master svn revision number as part of the verson identi‐
1565 fier
1566 2.3.1 (6 January 2012)
1568 · Adding support for Python 3.x
1569 2.3 (11 December 2011)
1571 · Adding the --gcov-filter and --gcov-exclude options.
1572 2.2 (10 December 2011)
1574 · Added a test driver for gcovr.
1575 · Improved estimation of the <sources> element when using gcovr with
1577 filters.
1578 · 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 · 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 · 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 · 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 · Bugfix: gcovr was only including a <sources> element in the XML
1596 report if the user specified -r (#3869)
1597 · 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 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 · Adding fix to compare the absolute path of a filename to an exclu‐
1611 sion pattern.
1612 · Adding error checking when no coverage results are found. The line
1614 and branch counts can be zero.
1615 · Adding logic to process the -o/--output option (#3870).
1617 · Adding patch to scan for lines that look like:
1619 creating `foo'
1621 as well as
1623 creating 'foo'
1625 · Changing the semantics for EOL to be portable for MS Windows.
1627 · Add attributes to xml format so that it could be used by hud‐
1629 son/bamboo with cobertura plug-in.
1630 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 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 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 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
16534.2 Feb 04, 2020 GCOVR(1)