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 in‐
10 spired 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 ┌───────────────┬─────────────────────┬─────────────────────┐
16 │CLI Option │ User Guide │ Description │
17 ├───────────────┼─────────────────────┼─────────────────────┤
18 │default, --txt │ Text Output │ compact human-read‐ │
19 │ │ │ able summaries │
20 ├───────────────┼─────────────────────┼─────────────────────┤
21 │--html │ HTML Output │ overview of all │
22 │ │ │ files │
23 ├───────────────┼─────────────────────┼─────────────────────┤
24 │--html-details │ HTML Output │ annotated source │
25 │ │ │ files │
26 ├───────────────┼─────────────────────┼─────────────────────┤
27 │--cobertura │ Cobertura XML Out‐ │ machine readable │
28 │ │ put │ XML reports in │
29 │ │ │ Cobertura format │
30 ├───────────────┼─────────────────────┼─────────────────────┤
31 │--sonarqube │ Sonarqube XML Out‐ │ machine readable │
32 │ │ put │ XML reports in │
33 │ │ │ Sonarqube format │
34 ├───────────────┼─────────────────────┼─────────────────────┤
35 │--json │ JSON Output │ JSON report with │
36 │ │ │ source file struc‐ │
37 │ │ │ ture and coverage │
38 ├───────────────┼─────────────────────┼─────────────────────┤
39 │--json-summary │ JSON Output │ JSON summary cover‐ │
40 │ │ │ age report │
41 ├───────────────┼─────────────────────┼─────────────────────┤
42 │--csv │ CSV Output │ CSV report summa‐ │
43 │ │ │ rizing the coverage │
44 │ │ │ of each file │
45 ├───────────────┼─────────────────────┼─────────────────────┤
46 │--coveralls │ Coveralls JSON Out‐ │ machine readable │
47 │ │ put │ JSON report in │
48 │ │ │ Coveralls format │
49 └───────────────┴─────────────────────┴─────────────────────┘
50 Thus, gcovr can be viewed as a command-line alternative to the lcov
52 utility, which runs gcov and generates an HTML-formatted report. The
53 development of gcovr was motivated by the need for text summaries and
54 XML reports.
55 Quick Links
57 • Getting Help
59 • Submit a ticket
61 • Stack Overflow
63 • Chat on Gitter
65 • Install from PyPI: pip install gcovr
67 • Source Code on GitHub
69 • Change Log
71 This documentation (https://gcovr.com/) describes gcovr 6.0.
73
75 Gcovr is available as a Python package that can be installed via pip.
76 Install newest stable gcovr release from PyPI:
78 pip install gcovr
80 Install development version from GitHub:
82 pip install git+https://github.com/gcovr/gcovr.git
84 Which environments does gcovr support?
86 Python:
88 3.7+.
89 The automated tests run on CPython (versions 3.7, 3.8, 3.9,
91 3.10) and a compatible PyPy3. Gcovr will only run on Python
92 versions with upstream support.
93 Last gcovr release for old Python versions:
95 ┌───────┬───────┐
97 │Python │ gcovr │
98 ├───────┼───────┤
99 │2.6 │ 3.4 │
100 ├───────┼───────┤
101 │2.7 │ 4.2 │
102 ├───────┼───────┤
103 │3.4 │ 4.1 │
104 ├───────┼───────┤
105 │3.5 │ 4.2 │
106 ├───────┼───────┤
107 │3.6 │ 5.0 │
108 └───────┴───────┘
109 Operating System:
111 Linux, Windows, and macOS.
112 The automated tests run on Ubuntu 20.04, 22.04 and Windows
114 Server 2019.
115 Compiler:
117 GCC and Clang.
118 The automated tests run on GCC 5, 6, 8, 9, 10, 11 and clang 10
120 and 13.
121
123 The gcovr command provides a summary of the lines that have been exe‐
124 cuted in a program. Code coverage statistics help you discover
125 untested parts of a program, which is particularly important when as‐
126 sessing code quality. Well-tested code is a characteristic of high
127 quality code, and software developers often assess code coverage sta‐
128 tistics when deciding if software is ready for a release.
129 GCC can instrument the executables to emit coverage data. You need to
131 recompile your code with the following flags:
132 --coverage -g -O0
134 Next, run your test suite. This will generate raw coverage files.
136 Finally, invoke gcovr. This will print a tabular report on the con‐
138 sole.
139 gcovr
141 You can also generate detailed or nested HTML reports:
143 gcovr --html-details coverage.html
145 gcovr --html-nested coverage.html
146 Gcovr will create one HTML report per source file and for --html-nested
148 also per directory next to the coverage.html summary.
149 You should run gcovr from the build directory. The -r option should
151 point to the root of your project. This only matters if you have a
152 separate build directory. For example:
153 cd build; gcovr -r ..
155 What to read next
157 The User Guide explains how to use the features of gcovr. In particu‐
158 lar:
159 • Compiling for Coverage
161 • Output Formats
163 • Using Filters
165 The Command Line Reference provides an overview of all options.
167 Specific problems might be addressed in the Cookbook or the Frequently
169 Asked Questions.
170
172 The user guide describes the various features of gcovr. It assumes you
173 have read the Getting Started guide.
174 This User Guide provides the following sections:
176 Compiling for Coverage
178 In order to collect coverage data, your software must be “instrumented”
179 by the compiler. That means, you must re-compile your software with
180 special compiler options.
181 The general workflow is:
183 1. compile your software to enable coverage profiling
185 2. execute your software to collect coverage profiles
187 3. run gcovr to create reports from the collected coverage profiling
189 data
190 This document explains how you can use GCC or Clang to compile with
192 coverage instrumentation.
193 If you cannot compile your software with coverage flags, you cannot use
195 gcovr. However, other tools like kcov might help.
196 Example Code
198 The following example.cpp program is used to illustrate the compilation
199 process:
200 1 // example.cpp
202 2
203 3 int foo(int param)
204 4 {
205 5 if (param)
206 6 {
207 7 return 1;
208 8 }
209 9 else
210 10 {
211 11 return 0;
212 12 }
213 13 }
214 14
215 15 int main(int argc, char* argv[])
216 16 {
217 17 foo(0);
218 18
219 19 return 0;
220 20 }
221 This code executes several subroutines in this program, but some lines
223 in the program are not executed.
224 Compiler Options
226 We compile example.cpp with the GCC compiler as follows:
227 g++ -fprofile-arcs -ftest-coverage -fPIC -O0 example.cpp -o program
229 What do these compiler flags mean?
231 • We compile without optimization (-O0), because optimizations may
233 merge lines of code or otherwise change the flow of execution in the
234 program. This can change the measured coverage.
235 On the other hand, enabling basic optimizations with -O1 can some‐
237 times produce “better” coverage reports, especially for C++. This is
238 a matter of personal preference, just make sure to avoid comparing
239 coverage metrics across optimization levels.
240 If you are having problems with lots of uncovered branches, see: Why
242 does C++ code have so many uncovered branches?
243 • Either --coverage or -fprofile-arcs -ftest-coverage are needed so
245 that the compiler produces the information necessary to gather cover‐
246 age data.
247 With these options, the compiler adds logic to the output program
249 that counts how often which part of the code was executed. The com‐
250 piler will also create a example.gcno file with metadata. The name
251 of the gcno file matches the compilation unit (see below).
252 Optional compiler flags:
254 • You can use other flags like -g or -fPIC as required by your tests.
256 These don't affect the coverage results.
257 • Using -fprofile-abs-path (available since GCC 8) can avoid some prob‐
259 lems with interpreting the coverage data correctly. By default, the
260 additional coverage files generated by GCC contain relative paths
261 from the working directory to the source files. If there are multi‐
262 ple potential working directories from which you might have run the
263 compiler, gcovr can get confused. Adding this option is more robust.
264 This examples uses the g++ compiler for C++ code, but any GCC or
266 Clang-based compiler should work.
267 If you are using CMake, see Out-of-Source Builds with CMake for infor‐
269 mation on configuring that build system to compile your software with
270 coverage enabled.
271 Running the Program
273 The above compiler invocation generated a program executable. Now, we
274 have to execute this command:
275 ./program
277 This will run whatever you designed this program to do. Often, such a
279 program would contain unit tests to exercise your code.
280 As a side effect, this will create an example.gcda file with the cover‐
282 age data for our compilation unit. This is a binary file so it needs
283 to be processed first. Together, the .gcda and .gcno files can be used
284 to create coverage reports.
285 Processing Coverage
287 Your compiler ships with tools to analyze the coverage data files. For
288 GCC, this is gcov. For Clang, this is llvm-cov. You don't have to
289 call these programs yourself – gcovr will do that for you.
290 So let's invoke gcovr:
292 gcovr
294 This will search for all your .gcno and .gcda files, run the compiler's
296 gcov tool, and summarize the code coverage statistics into a report.
297 By default, we get a text summary on the command line that shows aggre‐
298 gate statistics for each line:
299 ------------------------------------------------------------------------------
301 GCC Code Coverage Report
302 Directory: .
303 ------------------------------------------------------------------------------
304 File Lines Exec Cover Missing
305 ------------------------------------------------------------------------------
306 example.cpp 7 6 85% 7
307 ------------------------------------------------------------------------------
308 TOTAL 7 6 85%
309 ------------------------------------------------------------------------------
310 Gcovr supports many different Output Formats that you can generate in‐
313 stead.
314 Choosing the Right Gcov Executable
316 If you have multiple compilers installed or if you are using Clang, you
317 will likely need to tell gcovr which gcov executable to use. By de‐
318 fault, gcovr just uses the program named gcov. This is fine for the
319 default GCC compiler, e.g. gcc or g++. Otherwise, you must use the
320 --gcov-executable to tell gcovr what to use.
321 If you have used a specific GCC version (e.g. gcc-8 or g++-8), then you
323 must name the gcov tool with the corresponding version. For example:
324 gcovr --gcov-executable gcov-8
326 If you have used Clang, then you can use its gcov emulation mode. For
328 example:
329 gcovr --gcov-executable "llvm-cov gcov"
331 Again, the llvm-cov name may have to include your compiler version.
333 Working with Multiple Object Files
335 Code coverage instrumentation works on a per object file basis, which
336 means you have to re-compile your entire project to collect coverage
337 data.
338 The C/C++ model has a concept of “compilation units”. A large project
340 is typically not compiled in one go, but in separate steps. The result
341 of compiling a compilation unit is a .o object file with the machine
342 code. The object code from multiple compilation units is later linked
343 into the final executable or library. The previous example only had a
344 single compilation unit, so no explicit linking step was necessary.
345 Because each compilation unit is compiled independently, every one has
347 to be instrumented with coverage counters separately. A common mistake
348 is to add the compiler flags for coverage (e.g. in the CFLAGS or
349 CXXFLAGS variables) but then forgetting to force a re-compile. Depend‐
350 ing on the build system, it may be necessary to clear out the old ob‐
351 ject files that weren't compiled with coverage, e.g. with a make clean
352 command. Other build systems use a separate build directory when com‐
353 piling with coverage so that incremental compilation works as expected.
354 Each object file will have an associated .gcno and .gcda file in the
356 same directory as the .o object file. For example, consider the fol‐
357 lowing compilation process:
358 # (1) compile to object code
360 g++ --coverage -c -o a.o a.cpp
361 g++ --coverage -c -o b.o b.cpp
362 # (2) link the object files in the program
364 g++ --coverage -o the-program a.o b.o
365 # (3) run the program
367 ./the-program
368 1. Compiling the object code creates the a.o and b.o object files, but
370 also corresponding a.gcno and b.gcno notes files, one for each com‐
371 pilation unit. The -c option is used to only compile but to not
372 link the code.
373 2. Linking the object code produces the final program. This has no ef‐
375 fect on coverage processing, except that the --coverage flag makes
376 sure that a compiler-internal gcov support library is linked.
377 3. Running the program will increment the in-memory coverage counters
379 for all executed lines. At the end, the counters are written into
380 gcov data files, one for each compilation unit. Here, we would get
381 a.gcda and b.gcda files.
382 If you only want coverage data for certain source files, it is suffi‐
384 cient to only compile those compilation units with coverage enabled
385 that contain these source files. But this can be tricky to do cor‐
386 rectly. For example, header files are often part of multiple compila‐
387 tion units.
388 GCOV parser
390 The behavior of this parser was informed by the following sources:
391 • the old GcovParser class <‐
393 https://github.com/gcovr/gcovr/blob/e0b7afef00123b7b6ce4f487a1c4cc9fc60528bc/gcovr/gcov.py#L239>
394 • the Invoking Gcov section in the GCC manual (version 11) <‐
396 https://gcc.gnu.org/onlinedocs/gcc-11.1.0/gcc/Invoking-Gcov.html>
397 • the gcov.c source code in GCC (especially for understanding the exact
399 number format) <‐
400 https://github.com/gcc-mirror/gcc/blob/re‐
401 leases/gcc-11.1.0/gcc/gcov.c>
402 Error handling
404 By default the parser raises an exception on unrecognized gcov output.
405 There are several known issues with the files generated by gcov which
407 can be handled by --gcov-ignore-parse-errors which are descriped here.
408 If no value is given to the option the value all is used the whole gcov
409 file is ignored if the output is not recognized.
410 Negative hit counts
412 A bug in gcov can produce negative hit values (see gcov comment) which
413 are not accepted by default. This behavior can be changed by using the
414 value --gcov-ignore-parse-errors=negative_hits.warn or --gcov-ig‐
415 nore-parse-errors=negative_hits.warn_once_per_file. The first form
416 warns on every line with a negative value the second one only once per
417 processed file and adds a summary with the overall issues in the file.
418 Output Formats
420 Gcovr supports a variety of output formats that are documented on the
421 following pages.
422 Text Output
424 The text output format summarizes coverage in a plain-text table. This
425 is the default output format if no other format is selected. This out‐
426 put format can also be explicitly selected with the gcovr --txt option.
427 New in version 5.0: Added explicit --txt option.
429 Example output:
432 ------------------------------------------------------------------------------
434 GCC Code Coverage Report
435 Directory: .
436 ------------------------------------------------------------------------------
437 File Lines Exec Cover Missing
438 ------------------------------------------------------------------------------
439 example.cpp 7 6 85% 7
440 ------------------------------------------------------------------------------
441 TOTAL 7 6 85%
442 ------------------------------------------------------------------------------
443 Line Coverage
446 Running gcovr without any explicit output formats …
447 gcovr
449 generates a text summary of the lines executed:
451 ------------------------------------------------------------------------------
453 GCC Code Coverage Report
454 Directory: .
455 ------------------------------------------------------------------------------
456 File Lines Exec Cover Missing
457 ------------------------------------------------------------------------------
458 example.cpp 7 6 85% 7
459 ------------------------------------------------------------------------------
460 TOTAL 7 6 85%
461 ------------------------------------------------------------------------------
462 The same result can be achieved when explicit --txt option is set. For
465 example:
466 gcovr --txt
468 generates the same text summary.
470 Each line of this output includes a summary for a given source file,
472 including the number of lines instrumented, the number of lines exe‐
473 cuted, the percentage of lines executed, and a summary of the line num‐
474 bers that were not executed. To improve clarity, gcovr uses an aggres‐
475 sive approach to grouping uncovered lines and will combine uncovered
476 lines separated by "non-code" lines (blank, freestanding braces, and
477 single-line comments) into a single region. As a result, the number of
478 lines listed in the "Missing" list may be greater than the difference
479 of the "Lines" and "Exec" columns.
480 Note that gcov accumulates statistics by line. Consequently, it works
482 best with a programming style that places only one statement on each
483 line.
484 Branch Coverage
486 The gcovr command can also summarize branch coverage using the
487 -b/--branches option:
488 gcovr --branches
490 This generates a tabular output that summarizes the number of branches,
492 the number of branches taken and the branches that were not completely
493 covered:
494 ------------------------------------------------------------------------------
496 GCC Code Coverage Report
497 Directory: .
498 ------------------------------------------------------------------------------
499 File Branches Taken Cover Missing
500 ------------------------------------------------------------------------------
501 example.cpp 2 1 50% 5
502 ------------------------------------------------------------------------------
503 TOTAL 2 1 50%
504 ------------------------------------------------------------------------------
505 The same result can be achieved when explicit --txt option is set. For
508 example:
509 gcovr --branches --txt
511 prints the same tabular output.
513 HTML Output
515 The gcovr command can also generate a simple HTML output using the
516 --html option:
517 gcovr --html
519 This generates a HTML summary of the lines executed. In this example,
521 the file example1.html is generated, which has the following output:
522 [image]
523 The default behavior of the --html option is to generate HTML for a
525 single webpage that summarizes the coverage for all files. The HTML is
526 printed to standard output, but the -o/--output option is used to spec‐
527 ify a file that stores the HTML output.
528 The --html-details option is used to create a separate web page for
530 each file. Each of these web pages includes the contents of file with
531 annotations that summarize code coverage. Consider the following com‐
532 mand:
533 gcovr --html-details example_html.details.html
535 This generates the following HTML page for the file example1.cpp: [im‐
537 age]
538 The --html-nested option is used to create a separate web page for each
540 file and directory. Each of these web pages includes the contents of
541 file with annotations that summarize code coverage. Consider the fol‐
542 lowing command:
543 Note that the --html-details and --html-details options need a named
545 output, e.g. via the the -o/--output option. For example, if the out‐
546 put is named coverage.html, then the web pages generated for each file
547 will have names of the form coverage.<filename>.html.
548 The --html-self-contained option controls whether assets like CSS
550 styles are bundled into the HTML file. The --html report defaults to
551 self-contained mode. but --html-details and --html-nested default to
552 --no-html-self-contained in order to avoid problems with the Content
553 Security Policy of some servers, especially Jenkins.
554 New in version 6.0: Added --html-nested and --html-syntax-highlighting.
556 New in version 5.0: Added --html-self-contained and
559 --no-html-self-contained.
560 Changed in version 5.0: Default to external CSS file for
563 --html-details.
564 Cobertura XML Output
567 The default output format for gcovr is to generate a tabular summary in
568 plain text. The gcovr command can also generate a Cobertura XML output
569 using the --cobertura and --cobertura-pretty options:
570 gcovr --cobertura-pretty
572 This generates an XML summary of the lines executed:
574 <?xml version='1.0' encoding='UTF-8'?>
576 <!DOCTYPE coverage SYSTEM 'http://cobertura.sourceforge.net/xml/coverage-04.dtd'>
577 <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="1678315055" version="gcovr 6.0">
578 <sources>
579 <source>.</source>
580 </sources>
581 <packages>
582 <package name="" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
583 <classes>
584 <class name="example_cpp" filename="example.cpp" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
585 <methods/>
586 <lines>
587 <line number="3" hits="1" branch="false"/>
588 <line number="5" hits="1" branch="true" condition-coverage="50% (1/2)">
589 <conditions>
590 <condition number="0" type="jump" coverage="50%"/>
591 </conditions>
592 </line>
593 <line number="7" hits="0" branch="false"/>
594 <line number="11" hits="1" branch="false"/>
595 <line number="15" hits="1" branch="false"/>
596 <line number="17" hits="1" branch="false"/>
597 <line number="19" hits="1" branch="false"/>
598 </lines>
599 </class>
600 </classes>
601 </package>
602 </packages>
603 </coverage>
604 This XML format is in the Cobertura XML format suitable for import and
606 display within the Jenkins and Hudson continuous integration servers
607 using the Cobertura Plugin. Gcovr also supports a Sonarqube XML Out‐
608 put.
609 The --cobertura option generates a denser XML output, and the
611 --cobertura-pretty option generates an indented XML output that is eas‐
612 ier to read. Note that the XML output contains more information than
613 the tabular summary. The tabular summary shows the percentage of cov‐
614 ered lines, while the XML output includes branch statistics and the
615 number of times that each line was covered. Consequently, XML output
616 can be used to support performance optimization in the same manner that
617 gcov does.
618 New in version 5.1: The --cobertura and --cobertura-pretty options were
620 added as an alias for -x/--xml and --xml-pretty, respectively. This
621 avoids confusion with other XML output formats like Sonarqube XML Out‐
622 put. The old options remain available for backwards compatibility.
623 Sonarqube XML Output
626 If you are using Sonarqube, you can get a coverage report in a suitable
627 XML format via the --sonarqube option:
628 gcovr --sonarqube coverage.xml
630 The Sonarqube XML format is documented at
632 https://docs.sonarqube.org/latest/analysis/generic-test/.
633 JSON Output
635 The gcovr command can also generate a JSON output using the --json and
636 --json-pretty options:
637 gcovr --json coverage.json
639 The --json-pretty option generates an indented JSON output that is eas‐
641 ier to read.
642 If you just need a summary of the coverage information, similar to the
644 tabulated text based output, you can use --json-summary instead (see
645 JSON Summary Output).
646 Multiple JSON files can be merged into the coverage data with sum of
648 lines and branches execution, see Merging Coverage Data.
649 See the JSON Format Reference for a description of the file format.
651 JSON Format Reference
653 The structure of the JSON input/output files is based on the GCC gcov
654 JSON intermediate format, but with additional keys specific to gcovr.
655 Field names use snake_case. Gcovr-specific fields are prefixed with
656 gcovr/....
657 The GCC gcov JSON format is documented at
659 https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov.
660 The top level of the file looks like the following:
662 {
664 "gcovr/format_version": version,
665 "files": [file]
666 }
667 gcovr/format_version: string
669 A version number string for the gcovr JSON format. This is ver‐
670 sioned independently from gcovr itself. Consumers of gcovr JSON
671 reports should check that they are SemVer-compatible with the
672 declared version. Gcovr itself will only consume input files
673 that match the exact version.
674 files: list
676 An unordered list of file entries.
677 File entries
679 Each file entry contains coverage data for one source file:
680 {
682 "file": filename,
683 "lines": [line],
684 "functions": [function]
685 }
686 file: string
688 Path to the source code file. If the source file is within the
689 gcovr root directory, the path will be relative.
690 lines: list
692 An unordered list of line coverage entries.
693 functions: list
695 An unordered list of function entries.
696 Line entries
698 Each line entry contains coverage data for one line:
699 {
701 "branches": [branch],
702 "count": count,
703 "line_number": line_number,
704 "gcovr/excluded": excluded,
705 "gcovr/decision": decision
706 }
707 branches: list
709 A list of branch coverage entries.
710 count: int
712 How often this line was executed.
713 line_number: int
715 The 1-based line number to which this entry relates.
716 gcovr/excluded: boolean
718 True if coverage data for this line was explicitly excluded, in
719 particular with Exclusion Markers. May be absent if false.
720 gcovr/decision: object
722 The decision entry for this line, if any. Absent if there is no
723 decision to report. Requires that --decisions coverage analysis
724 was enabled.
725 If there is no line entry for a source code line, it either means that
727 the compiler did not generate any code for that line, or that gcovr ig‐
728 nored this coverage data due to heuristics.
729 The line entry should be interpreted as follows:
731 • if gcovr/excluded is true, the line should not be included in cover‐
733 age reports.
734 • if count is 0, the line is uncovered
736 • if count is nonzero, the line is covered
738 Changed in version 6.0: The gcovr/excluded field can be absent if
740 false.
741 Changed in version 6.0: The gcovr/noncode field was removed. Instead
744 of generating noncode entries, the entire line is skipped.
745 Branch entries
748 Each branch provides information about a branch on that line:
749 {
751 "count": count,
752 "fallthrough": fallthrough,
753 "throw": throw
754 }
755 This exactly matches the GCC gcov format.
757 count: int
759 How often this branch was taken.
760 fallthrough: boolean
762 Whether this is the “fallthrough” branch.
763 throw: boolean
765 Whether this is an exception-only branch.
766 Decision entries
768 Each decision summarizes the line's branch coverage data:
769 {
771 "type": "uncheckable"
772 }
773 {
775 "type": "conditional",
776 "count_true": count_true,
777 "count_false": count_false
778 }
779 {
781 "type": "switch",
782 "count": count
783 }
784 type: string
786 A tag/discriminator for the type of the decision.
787 type: "uncheckable"
789 Control flow was recognized on this line, but cannot be inter‐
790 preted unambiguously.
791 No further fields.
793 type: "conditional"
795 This line represents simple control flow like an if or while.
796 count_true: int
798 How often the decision evaluated to “true”.
799 count_false: int
801 How often the decision evaluated to “false”.
802 Note that the true/false are heuristic guesses, and might also
804 be inverted.
805 type: "switch"
807 This line is a switch-case.
808 count: int
810 How often this case was taken.
811 Function entries
813 Each function entry describes a line in the source file:
814 {
816 "name": name,
817 "lineno": lineno,
818 "execution_count": count,
819 "gcovr/excluded": excluded
820 }
821 name: string
823 The name of the function, mangled or demangled depending on com‐
824 piler version. May be incompatible with upstream GCC gcov JSON.
825 lineno: int
827 The line number (1-based) where this function was defined. In‐
828 compatible with GCC gcov JSON.
829 execution_count: int
831 How often this function was called.
832 gcovr/excluded: boolean
834 True if coverage data for this function was explicitly excluded,
835 in particular with Exclusion Markers. May be absent if false.
836 • if gcovr/excluded is true, the line should not be included in cover‐
838 age reports.
839 New in version 6.0: New gcovr/excluded field.
841 JSON Summary Output
844 The --json-summary option output coverage summary in a machine-readable
845 format for additional post processing. The format corresponds to the
846 normal JSON output --json option, but without line-level details and
847 with added aggregated statistics. The --json-summary-pretty option
848 generates an indented JSON summary output that is easier to read. Con‐
849 sider the following command:
850 gcovr --json-summary-pretty --json-summary
852 This generates an indented JSON summary:
854 {
856 "branch_covered": 1,
857 "branch_percent": 50.0,
858 "branch_total": 2,
859 "files": [
860 {
861 "branch_covered": 1,
862 "branch_percent": 50.0,
863 "branch_total": 2,
864 "filename": "example.cpp",
865 "function_covered": 2,
866 "function_percent": 100.0,
867 "function_total": 2,
868 "line_covered": 6,
869 "line_percent": 85.7,
870 "line_total": 7
871 }
872 ],
873 "function_covered": 2,
874 "function_percent": 100.0,
875 "function_total": 2,
876 "gcovr/summary_format_version": "0.5",
877 "line_covered": 6,
878 "line_percent": 85.7,
879 "line_total": 7,
880 "root": "."
881 }
882 New in version 5.0: Added --json-summary and --json-summary-pretty.
884 JSON Summary Format Reference
887 The summary format follows the general structure of the JSON Format
888 Reference, but removes line-level information and adds aggregated sta‐
889 tistics.
890 The top-level looks like:
892 {
894 "gcovr/summary_format_version": version,
895 "files: [file],
896 "root": path,
897 ...statistics
898 }
899 gcovr/summary_format_version: string
901 A version number string for the summary format. This is ver‐
902 sioned independently from gcovr and the full JSON format. Con‐
903 sumers of gcovr JSON Summary reports should check that they are
904 SemVer-compatible with the declared version.
905 files: list
907 Unordered list of file summary entries.
908 root: string
910 Path to the gcovr root directory, useful for reconstructing the
911 absolute path of source files. This root path is relative to
912 the output file, or to the current working directory if the re‐
913 port is printed to stdout.
914 ...statistics
916 Project-level aggregated statistics. A NaN percentage (0/0) is
917 reported as zero (0.0).
918 File summary entries
920 The file summary looks like:
921 {
923 "filename": path,
924 ...statistics
925 }
926 filename: string
928 Path to the source file, relative to the gcovr root directory.
929 ...statistics
931 File-level aggregated statistics. A NaN percentage (0/0) is re‐
932 ported as null.
933 Summary statistics
935 The root and file summaries contain the following additional fields:
936 ...
938 "branch_covered": ...,
939 "branch_total": ...,
940 "branch_percent": ...,
941 "line_covered": ...,
943 "line_total": ...,
944 "line_percent": ...,
945 "function_covered": ...,
947 "function_total": ...,
948 "function_percent": ...,
949 ...
950 These fields can be described by the glob expression {branch,line,func‐
952 tion}_{covered,total,percent}.
953 ELEMENT_covered: int
955 How many elements were covered or executed.
956 ELEMENT_total: int
958 How many elements there are in total.
959 ELEMENT_percent: float
961 Percentage of covered elements (covered/total) in the range 0 to
962 100. Note that the different contexts differ in their treatment
963 of NaN values.
964 CSV Output
966 The --csv option output comma-separated values summarizing the coverage
967 of each file. Consider the following command:
968 gcovr --csv
970 This generates an CSV:
972 filename,line_total,line_covered,line_percent,branch_total,branch_covered,branch_percent,function_total,function_covered,function_percent
974 example.cpp,7,6,0.857,2,1,0.5,2,2,1.0
975 New in version 5.0: Added --csv.
978 Coveralls JSON Output
981 If you are using Coveralls, you can get a coverage report in a suitable
982 JSON format via the --coveralls option:
983 gcovr --coveralls coverage.json
985 The --coveralls-pretty option generates an indented JSON output that is
987 easier to read.
988 Keep in mind that the output contains the checksums of the source
990 files. If you are using different OSes, the line endings shall be the
991 same.
992 If available, environment variable COVERALLS_REPO_TOKEN will be con‐
994 sumed and baked into the JSON output.
995 If running in a CI additional variables are used:
997 • In Travis CI:
999 • TRAVIS_JOB_ID
1001 • TRAVIS_BUILD_NUMBER
1003 • TRAVIS_PULL_REQUEST
1005 • TRAVIS_COMMIT
1007 • TRAVIS_BRANCH
1009 • In Appveyor:
1011 • APPVEYOR_JOB_ID
1013 • APPVEYOR_JOB_NUMBER
1015 • APPVEYOR_PULL_REQUEST_NUMBER
1017 • APPVEYOR_REPO_COMMIT
1019 • APPVEYOR_REPO_BRANCH
1021 • In Jenkins CI:
1023 • JOB_NAME
1025 • BUILD_ID
1027 • CHANGE_ID
1029 • GIT_COMMIT (if available)
1031 • BRANCH_NAME
1033 • In GitHub Actions:
1035 • GITHUB_WORKFLOW
1037 • GITHUB_RUN_ID
1039 • GITHUB_SHA
1041 • GITHUB_HEAD_REF (if available)
1043 • GITHUB_REF
1045 The Coveralls JSON format is documented at
1047 https://docs.coveralls.io/api-introduction.
1048 New in version 5.0: Added --coveralls and --coveralls-pretty.
1050 You can use Multiple Output Formats at the same time.
1053 Multiple Output Formats
1055 You can write multiple report formats with one gcovr invocation by
1056 passing the output filename directly to the report format flag. If no
1057 filename is specified for the format, the value from -o/--output is
1058 used by default, which itself defaults to stdout.
1059 The following report format flags can take an optional output file
1061 name:
1062 • gcovr --csv
1064 • gcovr --txt
1066 • gcovr --cobertura
1068 • gcovr --html
1070 • gcovr --html-details
1072 • gcovr --html-nested
1074 • gcovr --sonarqube
1076 • gcovr --json
1078 • gcovr --json-summary
1080 • gcovr --coveralls
1082 If the value given to the output option ends with a path seperator (/
1084 or \) it is used a directory which is created first and a default file‐
1085 name depending on the format is used.
1086 Note that --html-details and --html-nested override any value of --html
1088 if it is present.
1089 Merging Coverage Data
1091 You can merge coverage data from multiple runs with -a/--add-tracefile.
1092 For each run, generate JSON output:
1094 ... # compile and run first test case
1096 gcovr ... --json run-1.json
1097 ... # compile and run second test case
1098 gcovr ... --json run-2.json
1099 Next, merge the json files and generate the desired report:
1101 gcovr --add-tracefile run-1.json --add-tracefile run-2.json --html-details coverage.html
1103 You can also use unix style wildcards to merge the json files without
1105 duplicating -a/--add-tracefile. With this option you have to place your
1106 pathnames with wildcards in double quotation marks:
1107 gcovr --add-tracefile "run-*.json" --html-details coverage.html
1109 If you want to merge coverage reports generated in different --root di‐
1111 rectories you can use the --json-base to get the same root directory
1112 for all reports.
1113 If you have same function names defined on different line the default
1115 behaviour is to abort. With the --merge-mode-functions you can change
1116 this:
1117 • strict: Abort if same function is defined on a different line (old
1119 behaviour).
1120 • merge-use-line-0: Allow same function on different lines, in this
1122 case use line 0.
1123 • merge-use-line-min: Allow same function on different lines, in this
1125 case the minimum line.
1126 • merge-use-line-max: Allow same function on different lines, in this
1128 case use maximum line.
1129 • separate: Allow same function on different lines. Instead of merging
1131 keep the functions separate.
1132 New in version 6.0: The gcovr --json-base option. The gcovr
1134 --merge-mode-functions option.
1135 Using Filters
1138 Gcovr tries to only report coverage for files within your project, not
1139 for your libraries. This is influenced by the following options:
1140 • -r, --root
1142 • -f, --filter
1144 • -e, --exclude
1146 • --gcov-filter
1148 • --gcov-exclude
1150 • --exclude-directories
1152 • (the current working directory where gcovr is invoked)
1154 NOTE: Filters can also be specified in the gcovr configuration file:
1156 Configuration Files
1157 These options take filters. A filter is a regular expression that
1159 matches a file path. Because filters are regexes, you will have to es‐
1160 cape “special” characters with a backslash \.
1161 Always use forward slashes / as path separators, even on Windows:
1163 • wrong: --filter C:\project\src\
1165 • correct: --filter C:/project/src/
1167 If the filter looks like an absolute path, it is matched against an ab‐
1169 solute path. Otherwise, the filter is matched against a relative path,
1170 where that path is relative to the current directory or if defined in a
1171 configuration file to the directory of the file.
1172 Examples of relative filters:
1174 • --filter subdir/ matches only that subdirectory
1176 • --filter '\.\./src/' matches a sibling directory ../src. But because
1178 a dot . matches any character in a regex, we have to escape it. You
1179 have to use additional shell escaping. This example uses single
1180 quotes for Bash or POSIX shell.
1181 • --filter '(.+/)?foo\.c$' matches only files called foo.c. The regex
1183 must match from the start of the relative path, so we ignore any
1184 leading directory parts with (.+/)?. The $ at the end ensures that
1185 the path ends here.
1186 If no -f/--filter is provided, the -r/--root is turned into a default
1188 filter. Therefore, files outside of the -r/--root directory are ex‐
1189 cluded.
1190 To be included in a report, the source file must match any -f/--filter,
1192 and must not match any -e/--exclude filter.
1193 The --gcov-filter and --gcov-exclude filters apply to the .gcov files
1195 created by gcov. This is useful mostly when running gcov yourself, and
1196 then invoking gcovr with -g/--use-gcov-files. But these filters also
1197 apply when gcov is launched by gcovr.
1198 Speeding up coverage data search
1200 The --exclude-directories filter is used while searching for raw cover‐
1201 age data (or for existing .gcov files when -g/--use-gcov-files is ac‐
1202 tive). This filter is matched against directory paths, not file paths.
1203 If a directory matches, all its contents (files and subdirectories)
1204 will be excluded from the search. For example, consider this build di‐
1205 rectory:
1206 build/
1208 ├─ main.o
1209 ├─ main.gcda
1210 ├─ main.gcno
1211 ├─ a/
1212 │ ├─ awesome_code.o
1213 │ ├─ awesome_code.gcda
1214 │ └─ awesome_code.gcno
1215 └─ b/
1216 ├─ better_code.o
1217 ├─ better_code.gcda
1218 └─ better_code.gcno
1219 If we run gcovr --exclude-directories 'build/a$', this will exclude
1221 anything in the build/a directory but will use the coverage data for
1222 better_code.o and main.o.
1223 This can speed up gcovr when you have a complicated build directory
1225 structure. Consider also using the search_paths or --object-directory
1226 arguments to specify where gcovr starts searching. If you are unsure
1227 which directories are being searched, run gcovr in -v/--verbose mode.
1228 For each found coverage data file gcovr will invoke the gcov tool.
1230 This is typically the slowest part, and other filters can only be ap‐
1231 plied after this step. In some cases, parallel execution with the -j
1232 option might be helpful to speed up processing.
1233 Filters for symlinks
1235 Gcovr matches filters against real paths that have all their symlinks
1236 resolved. E.g. consider this project layout:
1237 /home/you/
1239 ├─ project/ (pwd)
1240 │ ├─ src/
1241 │ ├─ relevant-library/ -> ../external-library/
1242 │ └─ ignore-this/
1243 └─ external-library/
1244 └─ src/
1245 Here, the relevant-library has the real path /home/you/external-li‐
1247 brary.
1248 To write a filter that includes both src/ and relevant-library/src/, we
1250 cannot use --filter relevant-library/src/ because that contains a sym‐
1251 link. Instead, we have to use an absolute path to the real name:
1252 gcovr --filter src/ --filter /home/you/external-library/src/
1254 or a relative path to the real path:
1256 gcovr --filter src/ --filter '\.\./external-library/src/'
1258 New in version 5.1: gcovr also supports symlinks/junctions/drive sub‐
1260 stitutions on Windows.
1261 More examples for filters
1264 Excluding files inside build directory via --exclude with absolute path
1265 (Unix only):
1266 -e '/.*/build/'
1268 Excluding files inside build directory via --filter with relative path:
1270 --filter '\.\./'
1272 Configuration Files
1274 WARNING:
1275 Config files are an experimental feature and may be subject to
1276 change without prior notice.
1277 Defaults for the command line options can be set in a configuration
1279 file. Example:
1280 filter = src/
1282 html-details = yes # info about each source file
1283 output = build/coverage.html
1284 How the configuration file is found: If a --config option is provided,
1286 that file is used. Otherwise, a gcovr.cfg file in the -r/--root direc‐
1287 tory is used, if that file exists.
1288 Each line contains a key = value pair. Space around the = is optional.
1290 The value may be empty. Comments start with a hash # and ignore the
1291 rest of the line, but cannot start within a word. Empty lines are also
1292 ignored.
1293 The available config keys correspond closely to the command line op‐
1295 tions, and are parsed similarly. In most cases, the name of a long
1296 command line option can be used as a config key. If not, this is docu‐
1297 mented in the option's help message. For example, --gcov-executable
1298 can be set via the gcov-executable config key. But -b/--branches is
1299 set via txt-branch.
1300 Just like command line options, the config keys can be specified multi‐
1302 ple times. Depending on the option the last one wins or a list will be
1303 built. For example, -f/--filter can be provided multiple times:
1304 # Only show coverage for files in src/, lib/foo, or for main.cpp files.
1306 filter = src/
1307 filter = lib/foo/
1308 filter = *./main\.cpp
1309 Note that relative filters specified in config files will be inter‐
1311 preted relative to the location of the config file itself.
1312 Option arguments are parsed with the following precedence:
1314 • First the config file is parsed, if any.
1316 • Then, all command line arguments are added.
1318 • Finally, if an option was specified neither in a config file nor on
1320 the command line, its documented default value is used.
1321 Therefore, it doesn't matter whether a value is provided in the config
1323 file or the command line.
1324 Boolean flags are treated specially. When their config value is “yes”
1326 they are enabled, as if the flag had been provided on the command line.
1327 When their value is “no”, they are explicitly disabled by assigning
1328 their default value. The -j flag is special as it takes an optional
1329 argument. In the config file, gcov-parallel = yes would refer to the
1330 no-argument form, whereas gcov-parallel = 4 would provide an explicit
1331 argument.
1332 If the option is a path and is not absolute the path is used relative
1334 to the config file. For the option gcovr --add-tracefile the directory
1335 of the config file is always prepended.
1336 Some config file syntax is explicitly reserved for future extensions:
1338 Semicolon comments, INI-style sections, multi-line values, quoted val‐
1339 ues, variable substitutions, alternative key–value separators, …
1340 Exclusion Markers
1342 You can exclude parts of your code from coverage metrics.
1343 • If GCOVR_EXCL_LINE appears within a line, that line is ignored.
1345 • If GCOVR_EXCL_START appears within a line, all following lines (in‐
1347 cluding the current line) are ignored until a GCOVR_EXCL_STOP marker
1348 is encountered.
1349 • If GCOVR_EXCL_BR_* markers are used the same exclusion rules apply as
1351 above, with the difference beeing that they are only taken into ac‐
1352 count for branch coverage.
1353 Instead of GCOVR_*, the markers may also start with GCOV_* or LCOV_*.
1355 However, start and stop markers must use the same style. The prefix is
1356 configurable with the option --exclude-pattern-prefix.
1357 The excluded region not includes the line with the stop marker:
1359 code
1361 code
1362 excluded // GCOVR_EXCL_START
1363 still excluded
1364 ...
1365 still excluded
1366 NOT excluded // GCOVR_EXCL_STOP
1367 code
1368 code
1369 In the excluded regions, any coverage is excluded.
1371 Reproducible Timestamps
1373 In some cases, it may be desirable to list a specific timestamp in the
1374 report. Timestamps are shown in the HTML Output, Coveralls JSON Out‐
1375 put, and the Cobertura XML Output. This can be achieved via the
1376 --timestamp option or via Using SOURCE_DATE_EPOCH environment variable.
1377 This option does not affect the modification times or other filesystem
1378 metadata.
1379 New in version 6.0: Respect environment variable SOURCE_DATE_EPOCH for
1381 default of gcovr --timestamp.
1382 New in version 5.1: The gcovr --timestamp option.
1385 Timestamp Syntax
1388 The timestamp option understands different formats: Unix timestamps and
1389 RFC-3339 timestamps.
1390 Unix timestamps (also known as Posix time or Epoch) are the number of
1392 seconds since 1 Jan 1970. These timestamps are always resolved in the
1393 UTC timezone. Example usage:
1394 gcovr --timestamp 1640606727
1396 RFC 3339 specifies a reasonable subset of ISO-8601 timestamps. This is
1398 the YYYY-MM-DDThh:mm:ss format, optionally followed by a timezone off‐
1399 set (+hh:mm, or Z for UTC). Example usage without a timezone:
1400 gcovr --timestamp '2021-12-27 13:05:27'
1402 Example usages that show equivalent specifications for UTC timestamps:
1404 gcovr --timestamp '2021-12-27T13:05:27Z'
1406 gcovr --timestamp '2021-12-27T13:05:27+00:00'
1407 gcovr --timestamp '2021-12-27T13:05:27-00:00'
1408 Differences and clarifications with respect to RFC-3339:
1410 • the time zone may be omitted
1412 • the date and time parts may be separated by a space character instead
1414 of the T
1415 • the date is parsed in a case insensitive manner
1417 • sub-second accuracy is not currently supported
1419 Additional formats may be added in the future. To ensure that time‐
1421 stamps are handled in the expected manner, it is possible to select a
1422 particular timestamp syntax with a prefix.
1423 • Epoch timestamps can be selected with a @ or epoch: prefix.
1425 • RFC-3339 timestamps can be selected with a rfc3339: prefix.
1427 Examples of prefixes:
1429 gcovr --timestamp @1640606727
1431 gcovr --timestamp epoch:1640606727
1432 gcovr --timestamp 'rfc3339:2021-12-27 13:05:27'
1433 Using timestamps from Git commits
1435 As an example of using the timestamp feature, we might want to attri‐
1436 bute a coverage report to the time when a Git commit was created. Git
1437 lets us extract the commit date from a commit with the git show com‐
1438 mand. For the current HEAD commit:
1439 git show --no-patch --format=%cI HEAD
1441 This can be combined into a Bash one-liner like this:
1443 gcovr --timestamp="$(git show --no-patch --format=%cI HEAD)"
1445 Each Git commit has two dates, the author date and the committer date.
1447 This information can be extracted with various format codes, e.g. %aI
1448 for the author date and %cI for the committer date. These format codes
1449 are also available in different formats. The supported Git formats
1450 are:
1451 • Unix timestamps: %at, %ct
1453 • "Strict ISO" format: %aI, %cI
1455 • depending on the --date option: %ad, %cd
1457 Git's --date option is documented in git log. The supported settings
1459 are:
1460 • Unix timestamps: --date=unix
1462 • "Strict ISO" format: --date=iso-strict, --date=iso8601-strict,
1464 --date=iso-strict-local, --date=iso8601-strict-local
1465 Using SOURCE_DATE_EPOCH
1467 The Reproducible Builds project defines the SOURCE_DATE_EPOCH variable.
1468 Gcovr will use this variable as a default timestamp if no explicit
1469 --timestamp is set.
1470 The contents of this variable must be an UTC epoch, without any prefix.
1472 No other format is supported. Example usage:
1473 SOURCE_DATE_EPOCH=1640606727 gcovr
1475 For more information on setting and using this variable, see the
1477 Reproducible Builds documentation on SOURCE_DATE_EPOCH.
1478 Related documents:
1480 • Installation
1482 • Getting Started
1484 • Command Line Reference
1486 • Cookbook
1488 • Frequently Asked Questions
1490 • Contributing (includes instructions for bug reports)
1492 • Change Log
1494 • License
1496
1498 The gcovr command recursively searches a directory tree to find gcov
1499 coverage files, and generates a text summary of the code coverage. The
1500 -h/--help option generates the following summary of the gcovr command
1501 line options:
1502 gcovr
1504 A utility to run gcov and summarize the coverage in simple reports.
1505 usage: gcovr [options] [search_paths...]
1507 See <http://gcovr.com/> for the full manual.
1509 Options
1511 search_paths
1512 Search these directories for coverage files. Defaults to --root
1513 and --object-directory. Config key: search-path.
1514 -h, --help
1516 Show this help message, then exit.
1517 --version
1519 Print the version number, then exit.
1520 -v, --verbose
1522 Print progress messages. Please include this output in bug re‐
1523 ports.
1524 -r <root>, --root <root>
1526 The root directory of your source files. Defaults to '.', the
1527 current directory. File names are reported relative to this
1528 root. The --root is the default --filter.
1529 -a <add_tracefile>, --add-tracefile <add_tracefile>
1531 Combine the coverage data from JSON files. Coverage files con‐
1532 tains source files structure relative to root directory. Those
1533 structures are combined in the output relative to the current
1534 root directory. Unix style wildcards can be used to add the
1535 pathnames matching a specified pattern. In this case pattern
1536 must be set in double quotation marks. Option can be specified
1537 multiple times. When option is used gcov is not run to collect
1538 the new coverage data.
1539 --config <config>
1541 Load that configuration file. Defaults to gcovr.cfg in the
1542 --root directory.
1543 --no-markers
1545 Turn off exclusion markers. Any exclusion markers specified in
1546 source files will be ignored.
1547 --fail-under-line <min>
1549 Exit with a status of 2 if the total line coverage is less than
1550 MIN. Can be ORed with exit status of '--fail-under-branch' op‐
1551 tion.
1552 --fail-under-branch <min>
1554 Exit with a status of 4 if the total branch coverage is less
1555 than MIN. Can be ORed with exit status of '--fail-under-line'
1556 option.
1557 --source-encoding <source_encoding>
1559 Select the source file encoding. Defaults to the system default
1560 encoding (utf-8).
1561 --exclude-lines-by-pattern <exclude_lines_by_pattern>
1563 Exclude lines that match this regex.
1564 --exclude-branches-by-pattern <exclude_branches_by_pattern>
1566 Exclude branches that match this regex.
1567 --exclude-pattern-prefix <exclude_pattern_prefix>
1569 Define the regex prefix used in markers / line exclusions (i.e
1570 ..._EXCL_START, ..._EXCL_START, ..._EXCL_STOP)
1571 Output Options
1573 Gcovr prints a text report by default, but can switch to XML or HTML.
1574 -o <output>, --output <output>
1576 Print output to this filename. Defaults to stdout. Individual
1577 output formats can override this.
1578 -b, --branches
1580 Report the branch coverage instead of the line coverage. For
1581 text report only. Config key: txt-branch.
1582 --decisions
1584 Report the decision coverage. For HTML and JSON report.
1585 --calls
1587 Report the calls coverage. For HTML report.
1588 -u, --sort-uncovered
1590 Sort entries by increasing number of uncovered lines. For text
1591 and HTML report.
1592 -p, --sort-percentage
1594 Sort entries by increasing percentage of uncovered lines. For
1595 text and HTML report.
1596 --txt <output>
1598 Generate a text report. OUTPUT is optional and defaults to
1599 --output.
1600 --cobertura <output>, -x <output>, --xml <output>
1602 Generate a Cobertura XML report. OUTPUT is optional and defaults
1603 to --output.
1604 --cobertura-pretty, --xml-pretty
1606 Pretty-print the Cobertura XML report. Implies --cobertura. De‐
1607 fault: False.
1608 --html <output>
1610 Generate a HTML report. OUTPUT is optional and defaults to
1611 --output.
1612 --html-details <output>
1614 Add annotated source code reports to the HTML report. Implies
1615 --html, can not be used together with --html-nested. OUTPUT is
1616 optional and defaults to --output.
1617 --html-nested <output>
1619 Add annotated source code reports to the HTML report. A page is
1620 created for each directory that summarize subdirectories with
1621 aggregated statistics. Implies --html, can not be used together
1622 with --html-details. OUTPUT is optional and defaults to --out‐
1623 put.
1624 --html-syntax-highlighting, --html-details-syntax-highlighting
1626 Use syntax highlighting in HTML source page. Enabled by default.
1627 Negation: --no-html-syntax-highlighting, --no-html-details-syn‐
1628 tax-highlighting.
1629 --html-theme {green,blue}
1631 Override the default color theme for the HTML report. Default is
1632 green.
1633 --html-css <css>
1635 Override the default style sheet for the HTML report.
1636 --html-title <title>
1638 Use TITLE as title for the HTML report. Default is 'GCC Code
1639 Coverage Report'.
1640 --html-medium-threshold <medium>
1642 If the coverage is below MEDIUM, the value is marked as low cov‐
1643 erage in the HTML report. MEDIUM has to be lower than or equal
1644 to value of --html-high-threshold and greater than 0. If MEDIUM
1645 is equal to value of --html-high-threshold the report has only
1646 high and low coverage. Default is 75.0.
1647 --html-high-threshold <high>
1649 If the coverage is below HIGH, the value is marked as medium
1650 coverage in the HTML report. HIGH has to be greater than or
1651 equal to value of --html-medium-threshold. If HIGH is equal to
1652 value of --html-medium-threshold the report has only high and
1653 low coverage. Default is 90.0.
1654 --html-medium-threshold-branch <medium_branch>
1656 If the coverage is below MEDIUM_BRANCH, the value is marked as
1657 low coverage in the HTML report. MEDIUM_BRANCH has to be lower
1658 than or equal to value of --html-high-threshold-branch and
1659 greater than 0. If MEDIUM_BRANCH is equal to value of
1660 --html-medium-threshold-branch the report has only high and low
1661 coverage. Default is taken from --html-medium-threshold.
1662 --html-high-threshold-branch <high_branch>
1664 If the coverage is below HIGH_BRANCH, the value is marked as
1665 medium coverage in the HTML report. HIGH_BRANCH has to be
1666 greater than or equal to value of --html-medium-thresh‐
1667 old-branch. If HIGH_BRANCH is equal to value of
1668 --html-medium-threshold-branch the report has only high and low
1669 coverage. Default is taken from --html-high-threshold.
1670 --html-medium-threshold-line <medium_line>
1672 If the coverage is below MEDIUM_LINE, the value is marked as low
1673 coverage in the HTML report. MEDIUM_LINE has to be lower than or
1674 equal to value of --html-high-threshold-line and greater than 0.
1675 If MEDIUM_LINE is equal to value of --html-medium-threshold-line
1676 the report has only high and low coverage. Default is taken from
1677 --html-medium-threshold.
1678 --html-high-threshold-line <high_line>
1680 If the coverage is below HIGH_LINE, the value is marked as
1681 medium coverage in the HTML report. HIGH_LINE has to be greater
1682 than or equal to value of --html-medium-threshold-line. If
1683 HIGH_LINE is equal to value of --html-medium-threshold-line the
1684 report has only high and low coverage. Default is taken from
1685 --html-high-threshold.
1686 --html-tab-size <html_tab_size>
1688 Used spaces for a tab in a source file. Default is 4
1689 --html-absolute-paths
1691 Use absolute paths to link the --html-details reports. Defaults
1692 to relative links.
1693 --html-encoding <html_encoding>
1695 Override the declared HTML report encoding. Defaults to UTF-8.
1696 See also --source-encoding.
1697 --html-self-contained
1699 Control whether the HTML report bundles resources like CSS
1700 styles. Self-contained reports can be sent via email, but con‐
1701 flict with the Content Security Policy of some web servers. De‐
1702 faults to self-contained reports unless --html-details is used.
1703 Negation: --no-html-self-contained.
1704 -s, --print-summary
1706 Print a small report to stdout with line & function & branch
1707 percentage coverage. This is in addition to other reports. De‐
1708 fault: False.
1709 --sonarqube <output>
1711 Generate sonarqube generic coverage report in this file name.
1712 OUTPUT is optional and defaults to --output.
1713 --json <output>
1715 Generate a JSON report. OUTPUT is optional and defaults to
1716 --output.
1717 --json-pretty
1719 Pretty-print the JSON report. Implies --json. Default: False.
1720 --json-summary <output>
1722 Generate a JSON summary report. OUTPUT is optional and defaults
1723 to --output.
1724 --json-summary-pretty
1726 Pretty-print the JSON SUMMARY report.Implies --json-summary. De‐
1727 fault: False.
1728 --json-base <path>
1730 Prepend the given path to all file paths in JSON report.
1731 --csv <output>
1733 Generate a CSV summary report. OUTPUT is optional and defaults
1734 to --output.
1735 --coveralls <output>
1737 Generate Coveralls API coverage report in this file name. OUTPUT
1738 is optional and defaults to --output.
1739 --coveralls-pretty
1741 Pretty-print the coveralls report. Implies --coveralls. Default:
1742 False.
1743 --timestamp <timestamp>
1745 Override current time for reproducible reports. Can use
1746 YYYY-MM-DD hh:mm:ss or epoch notation. Used by HTML, Coveralls,
1747 and Cobertura reports. Default: Environment variable
1748 SOURCE_DATE_EPOCH (see
1749 https://reproducible-builds.org/docs/source-date-epoch) or cur‐
1750 rent time.
1751 Filter Options
1753 Filters decide which files are included in the report. Any filter must
1754 match, and no exclude filter must match. A filter is a regular expres‐
1755 sion that matches a path. Filter paths use forward slashes, even on
1756 Windows. If the filter looks like an absolute path it is matched
1757 against an absolute path. Otherwise, the filter is matched against a
1758 relative path, where that path is relative to the current directory or
1759 if defined in a configuration file to the directory of the file.
1760 -f <filter>, --filter <filter>
1762 Keep only source files that match this filter. Can be specified
1763 multiple times. Relative filters are relative to the current
1764 working directory or if defined in a configuration file. If no
1765 filters are provided, defaults to --root.
1766 -e <exclude>, --exclude <exclude>
1768 Exclude source files that match this filter. Can be specified
1769 multiple times.
1770 --gcov-filter <gcov_filter>
1772 Keep only gcov data files that match this filter. Can be speci‐
1773 fied multiple times.
1774 --gcov-exclude <gcov_exclude>
1776 Exclude gcov data files that match this filter. Can be specified
1777 multiple times.
1778 --exclude-directories <exclude_dirs>
1780 Exclude directories that match this regex while searching raw
1781 coverage files. Can be specified multiple times.
1782 GCOV Options
1784 The 'gcov' tool turns raw coverage files (.gcda and .gcno) into .gcov
1785 files that are then processed by gcovr. The gcno files are generated by
1786 the compiler. The gcda files are generated when the instrumented pro‐
1787 gram is executed.
1788 --gcov-executable <gcov_cmd>
1790 Use a particular gcov executable. Must match the compiler you
1791 are using, e.g. 'llvm-cov gcov' for Clang. Can include addi‐
1792 tional arguments. Defaults to the GCOV environment variable, or
1793 'gcov': 'gcov'.
1794 --include-internal-functions
1796 Include function coverage of compiler internal functions (start‐
1797 ing with '__' or '_GLOBAL__sub_I_').
1798 --exclude-unreachable-branches
1800 Exclude branch coverage from lines without useful source code
1801 (often, compiler-generated "dead" code). Default: False.
1802 --exclude-function-lines
1804 Exclude coverage from lines defining a function. Default: False.
1805 --merge-mode-functions
1807 {strict,merge-use-line-0,merge-use-line-min,merge-use-line-max,sepa‐
1808 rate}
1809 The merge mode for functions coverage from different gcov files
1810 for same sourcefile.Default: strict.
1811 --exclude-noncode-lines
1813 Exclude coverage from lines which seem to be non-code. Default:
1814 False. Negation: --no-exclude-noncode-lines.
1815 --exclude-throw-branches
1817 For branch coverage, exclude branches that the compiler gener‐
1818 ates for exception handling. This often leads to more "sensible"
1819 coverage reports. Default: False.
1820 -g, --use-gcov-files
1822 Use existing gcov files for analysis. Default: False.
1823 --gcov-ignore-errors {all,no_working_dir_found}
1825 Ignore errors from invoking GCOV command instead of exiting with
1826 an error. A report will be shown on stderr. Default: None.
1827 --gcov-ignore-parse-errors {all,negative_hits.warn,nega‐
1829 tive_hits.warn_once_per_file}
1830 Skip lines with parse errors in GCOV files instead of exiting
1831 with an error. A report will be shown on stderr. Default: None.
1832 --object-directory <objdir>
1834 Override normal working directory detection. Gcovr needs to
1835 identify the path between gcda files and the directory where the
1836 compiler was originally run. Normally, gcovr can guess cor‐
1837 rectly. This option specifies either the path from gcc to the
1838 gcda file (i.e. gcc's '-o' option), or the path from the gcda
1839 file to gcc's working directory.
1840 -k, --keep
1842 Keep gcov files after processing. This applies both to files
1843 that were generated by gcovr, or were supplied via the
1844 --use-gcov-files option. Default: False. Config key:
1845 keep-gcov-files.
1846 -d, --delete
1848 Delete gcda files after processing. Default: False. Config key:
1849 delete-gcov-files.
1850 -j <gcov_parallel>
1852 Set the number of threads to use in parallel. Config key:
1853 gcov-parallel.
1854 For guide-level explanation on using these options, see the User Guide.
1856
1858 This section contains how-to guides on creating code coverage reports
1859 for various purposes. For an introduction on using gcovr, see the User
1860 Guide instead.
1861 Recipes in the cookbook:
1863 • How to collect coverage for C extensions in Python
1865 • Out-of-Source Builds with CMake
1867 • Support of Keil uVision format
1869 • How to create a standalone application
1871 How to collect coverage for C extensions in Python
1873 Collecting code coverage data on the C code that makes up a Python ex‐
1874 tension module is not quite as straightforward as with a regular C pro‐
1875 gram.
1876 As with a normal C project, we have to compile our code with coverage
1878 instrumentation. Here, we export CFLAGS="--coverage" and then run
1879 python3 setup.py build_ext.
1880 Unfortunately, build_ext can rebuild a source file even if the current
1882 object file is up to date. If multiple extension modules share the
1883 same source code file, gcov will get confused by the different time‐
1884 stamps and report inaccurate coverage. It is nontrivial to adapt the
1885 build_ext process to avoid this.
1886 Instead, we can use the ccache utility to make the compilation lazy
1888 (works best on Unix systems). Before we invoke the build_ext step, we
1889 first export CC="ccache gcc". Ccache works well but isn't absolutely
1890 perfect, see the ccache manual for caveats.
1891 A shell session might look like this:
1893 # Set required env vars
1895 export CFLAGS="--coverage"
1896 export CC="ccache gcc"
1897 # clear out build files so we get a fresh compile
1899 rm -rf build/temp.* # contains old .gcda, .gcno files
1900 rm -rf build/lib.*
1901 # rebuild extensions
1903 python3 setup.py build_ext --inplace # possibly --force
1904 # run test command i.e. pytest
1906 # run gcovr
1908 rm -rf coverage; mkdir coverage
1909 gcovr --filter src/ --print-summary --html-details coverage/index.html
1910 Out-of-Source Builds with CMake
1912 Tools such as cmake encourage the use of out-of-source builds, where
1913 the code is compiled in a directory other than the one which contains
1914 the sources. This is an extra complication for gcov. In order to pass
1915 the correct compiler and linker flags, the following commands need to
1916 be in CMakeLists.txt:
1917 # This flags are used if cmake is called with -DCMAKE_BUILD_TYPE=PROFILE
1919 set(CMAKE_C_FLAGS_PROFILE --coverage)
1920 set(CMAKE_CXX_FLAGS_PROFILE --coverage)
1921 add_executable(program example.cpp)
1923 The --coverage compiler flag is an alternative to -fprofile-arcs
1925 -ftest-coverage for recent version of gcc. In versions 3.13 and later
1926 of cmake, the target_link_libraries command can be removed and
1927 add_link_options("--coverage") added after the add_compile_options com‐
1928 mand.
1929 We then follow a normal cmake build process:
1931 cd $BLD_DIR
1933 cmake -DCMAKE_BUILD_TYPE=PROFILE $SRC_DIR
1934 make VERBOSE=1
1935 and run the program:
1937 cd $BLD_DIR
1939 ./program
1940 However, invocation of gcovr itself has to change. The assorted .gcno
1942 and .gcda files will appear under the CMakeFiles directory in BLD_DIR,
1943 rather than next to the sources. Since gcovr requires both, the command
1944 we need to run is:
1945 cd $BLD_DIR
1947 gcovr -r $SRC_DIR .
1948 Support of Keil uVision format
1950 As mentioned in comment of issue 697 the format of gcov file generated
1951 by the Keil uVision compiler is not compatible with the gcov specifica‐
1952 tion. To support coverage data generated by this compiler you have to
1953 create the gcov files as documented in Keil uVision documentation and
1954 process them before running gcov to get the correct format.
1955 Save the following Sed script as fix-gcov.sed:
1957 # fix markers for uncovered code:
1959 # match any of #=%$ repeated 6 times
1960 s/^\([#=%$]\)\(\1\{5\}\)/\2/
1961 # fix branch tags
1963 /^branch/ {
1964 s/executed 0/never executed/
1965 s/executed .*/taken 1/
1966 s/skipped .*/never executed/
1967 }
1968 Then, apply this Sed script to all gcov files before invoking gcovr:
1970 find . -name '*.gcov' -exec sed -i -f fix-gcov.sed {} \;
1972 gcovr --use-gcov-files
1973 WARNING:
1975 Untested because we have no access to Keil uVision compiler
1976 How to create a standalone application
1978 To create a standalone application you need to install the test suite
1979 (see Test suite). In this test suite you can build a standalone exe‐
1980 cutable with the command python3 -m nox --session build_app. The com‐
1981 mand creates the application build/gcovr and calls the executable whith
1982 each format to check if it's working correct.
1983
1985 What is the difference between lcov and gcovr?
1986 Both lcov and gcovr are tools to create coverage reports.
1987 Gcovr was originally created as a simple script to provide a convenient
1989 command line interface to gcov that produced more easily digestible
1990 output similar to Python's coverage utilities.
1991 Later, we added XML output that could be used with the Cobertura plugin
1993 of the Jenkins continuous integration server. This gave us nice cover‐
1994 age reports for C/C++ code in Jenkins.
1995 HTML output was added much later. If all you need is HTML, pick which‐
1997 ever one produces the output you like better or integrates easier with
1998 your existing workflow.
1999 Lcov is a far older project that is part of the Linux Test Project. It
2001 provides some features that gcovr does not have: For example, lcov has
2002 explicit support for capturing Linux kernel coverage. Lcov also sup‐
2003 ports various trace file manipulation functions such as merging trace
2004 files from different test runs. You can learn more at the lcov website
2005 or the lcov GitHub repository.
2006 Why does C++ code have so many uncovered branches?
2008 Gcovr's branch coverage reports are based on GCC's -profile-arcs fea‐
2009 ture, which uses the compiler's control flow graph (CFG) of each func‐
2010 tion to determine branches. This is a very low-level view: to under‐
2011 stand the branches in a given function, it can help to view the func‐
2012 tion's assembly, e.g. via the Godbolt Compiler Explorer.
2013 What gcovr calls a branch is in fact an arc between basic blocks in the
2015 CFG. This means gcovr's reports have many branches that are not caused
2016 by if statements! For example:
2017 • Arcs are caused by C/C++ branching operators: for, if, while,
2019 switch/case, &&, ||, ? :. Note that switches are often compiled as a
2020 decision tree which introduces extra arcs, not just one per case.
2021 • (Arcs into another function are not shown.)
2023 • Arcs are caused when a function that may throw returns: one arc to
2025 the next block or statement for normal returns, and one arc to an ex‐
2026 ception handler for exceptions, if this function contains an excep‐
2027 tion handler. Every local variable with a destructor is an exception
2028 handler as well.
2029 • Compiler-generated code that deals with exceptions often needs extra
2031 branches: throw statements, catch clauses, and destructors.
2032 • Extra arcs are created for static initialization and destruction.
2034 • Arcs may be added or removed by compiler optimizations. If you com‐
2036 pile without optimizations, some arcs may even be unreachable!
2037 Gcovr is not able to remove any “unwanted” branches because GCC's gcov
2039 tool does not make the necessary information available, and because
2040 different projects are interested in different kinds of branches. How‐
2041 ever, gcovr has the following options to reduce unwanted branches:
2042 With the gcovr --exclude-unreachable-branches option, gcovr parses the
2044 source code to see whether that line even contains any code. If the
2045 line is empty or only contains curly braces, this could be an indica‐
2046 tion of compiler-generated code that was mis-attributed to that line
2047 (such as that for static destruction) and branch coverage will be ig‐
2048 nored on that line.
2049 With the gcovr --exclude-throw-branches option, exception-only branches
2051 will be ignored. These are typically arcs from a function call into an
2052 exception handler.
2053 With the gcovr --decisions option, gcovr parses the source code to ex‐
2055 tract a ISO 26262 compliant metric for decision coverage. This metric
2056 can be interpreted as the branch coverage on C/C++-Level. While the
2057 feature is not always able to detect the decisions reliabily when the
2058 code is written very compact (uncheckable decisions will be marked), it
2059 provides a reliable tool for (i.e. MISRA-compliant) code in secu‐
2060 rity-relevant situations.
2061 Compiling with optimizations will typically remove unreachable branches
2063 and remove superfluous branches, but makes the coverage report less ex‐
2064 act. For example, branching operators might be optimized away. Deci‐
2065 sion coverage analysis will be very buggy when compiling with optimiza‐
2066 tions. See also: Gcov and Optimization in the GCC documentation.
2067 Despite these approaches, 100% branch coverage will be impossible for
2069 most programs.
2070 Why are uncovered files not reported?
2072 Gcovr does report files that have zero coverage, even when no .gcda
2073 file is available for that compilation unit.
2074 However, the gcov tool in some versions of GCC refuses to generate out‐
2076 put for uncovered files.
2077 To fix this, upgrade GCC to:
2079 • version 5.5 or later,
2081 • version 6.2 or later, or
2083 • any version since 7.
2085 Note that the compiler may ignore inline functions that are never used.
2087 Which options are used for calling gcov?
2089 The options used for calling gcov depends on the version of gcov.
2090 Following options are always used:
2092 • --branch-counts
2094 • --branch-probabilities
2096 • --object-directory
2098 Following options are only used if available:
2100 • --demangled-names: Not available for LLVM based gcov.
2102 • --hash-filenames: Available since GCC 7, as fallback the option
2104 --preserve-paths is used.
2105
2107 This document contains:
2108 • our guidelines for bug reports
2110 • general contribution guidelines
2112 • a checklist for pull requests
2114 • a developer guide that explains the development environment, project
2116 structure, and test suite
2117 How to report bugs
2119 When reporting a bug, first search our issues to avoid duplicates. In
2120 your bug report, please describe what you expected gcovr to do, and
2121 what it actually did. Also try to include the following details:
2122 • how you invoked gcovr, i.e. the exact flags and from which directory
2124 • your project layout
2126 • your gcovr version
2128 • your compiler version
2130 • your operating system
2132 • and any other relevant details.
2134 Ideally, you can provide a short script and the smallest possible
2136 source file to reproduce the problem.
2137 How to help
2139 If you would like to help out, please take a look at our open issues
2140 and pull requests. The issues labeled help wanted and needs review
2141 would have the greatest impact.
2142 There are many ways how you can help:
2144 • assist other users with their problems
2146 • share your perspective as a gcovr user in discussions
2148 • test proposed changes in your real-world projects
2150 • improve our documentation
2152 • submit pull requests with bug fixes and enhancements
2154 How to submit a Pull Request
2156 Thank you for helping with gcovr development! Please follow this
2157 checklist for your pull request:
2158 • Is this a good approach? Fixing open issues is always welcome! If
2160 you want to implement an enhancement, please discuss it first as a
2161 GitHub issue.
2162 • Does it work? Please run the tests locally:
2164 python3 -m nox
2166 (see also: Test suite)
2168 In any case, the tests will run automatically when you open the pull
2170 request. But please prevent unnecessary build failures and run the
2171 tests yourself first. If you cannot run the tests locally, you can
2172 activate GitHub for your fork, or run the tests with Docker. If
2173 there are differences the updated files will be available for down‐
2174 load from the CI system (one ZIP for each test environment).
2175 If you add new features, please try to add a test case.
2177 • Does it conform to the style guide? The source code should conform
2179 to the PEP 8 standard. Please check your code:
2180 python3 -m nox --session lint
2182 # or:
2184 python3 -m flake8 doc gcovr
2186 The command python3 -m nox will run the linter, run the tests, and
2188 check that the docs can be built.
2189 • Add yourself as an author. If this is your first contribution to
2191 gcovr, please add yourself to the AUTHORS.txt file.
2192 • One change at a time. Please keep your commits and your whole pull
2194 request fairly small, so that the changes are easy to review. Each
2195 commit should only contain one kind of change, e.g. refactoring or
2196 new functionality.
2197 • Why is this change necessary? When you open the PR, please explain
2199 why we need this change and what your PR does. If this PR fixes an
2200 open issue, reference that issue in the pull request description.
2201 Add a reference to the issue in the CHANGELOG.rst, if the change
2202 should not be visible in the changelog (minor or not of interest),
2203 add the following string to a single line in the PR body:
2204 [no changelog]
2205 Once you submit the PR, it will be automatically tested on Windows and
2207 Linux, and code coverage will be collected. Your code will be re‐
2208 viewed. This can take a week. Please fix any issues that are discov‐
2209 ered during this process. Feel free to force-push your updates to the
2210 pull request branch.
2211 If you need assistance for your pull request, you can
2213 • chat in our Gitter room
2215 • discuss your problem in an issue
2217 • open an unfinished pull request as a work in progress (WIP), and
2219 explain what you've like to get reviewed
2220 How to set up a development environment
2222 For working on gcovr, you will need a supported version of Python 3,
2223 GCC version 5, 6, 8, 9, 10 or 11 (other GCC versions are supported by
2224 gcovr, but will cause spurious test failures) or clang version 10 or
2225 13, make, cmake and ninja. Please make sure that the tools are in the
2226 system PATH. On Windows, you will need to install a GCC toolchain as
2227 the tests expect a Unix-like environment. You can use MinGW-W64 or
2228 MinGW. An easier way is to run tests with Docker, on Windows a Pro li‐
2229 cense or the WSL (Windows subsystem for Linux) is needed.
2230 • Check your GCC installation, the binary directory must be added to
2232 the PATH environment. If on of the following command groups are ev‐
2233 erything is OK.
2234 • gcc-5/g++-5/gcov-5
2236 • gcc-6/g++-6/gcov-6
2238 • gcc-8/g++-8/gcov-8
2240 • gcc-9/g++-9/gcov-9
2242 • gcc-10/g++-10/gcov-10
2244 • gcc-11/g++-11/gcov-11
2246 • clang-10/clang++-10/llvm-cov
2248 • clang-13/clang++-13/llvm-cov
2250 • clang-14/clang++-14/llvm-cov
2252 are available everything is OK. The test suite uses the newest GCC
2254 found in the PATH. To use another one you need to set the environment
2255 CC=... see run and filter tests. If you only have gcc in your path
2256 the version is detected to select the correct reference. You can
2257 also create symlinks for the gcc executables with the following
2258 steps. You can check the GCC version with gcc --version. If the out‐
2259 put says version 8, you should also be able to run gcc-8 --version.
2260 Your Linux distribution should have set all of this up already. If
2261 you don't have an alias like gcc-8, perform the following steps to
2262 create an alias for gcc, this should also work in the MSYS shell un‐
2263 der Windows:
2264 1. Create a directory somewhere, e.g. in your home directory: mkdir
2266 ~/bin
2267 2. Create a symlink in that directory which points to GCC: ln -s
2269 $(which gcc) ~/bin/gcc-8
2270 3. Add this directory to your PATH: export PATH="$HOME/bin:$PATH"
2272 4. Re-test gcc-8 --version to ensure everything worked.
2274 5. Create additional symlinks for g++ -> g++-8 and gcov -> gcov-8.
2276 • (Optional) Fork the project on GitHub.
2278 • Clone the git repository.
2280 • (Optional) Set up a virtualenv (e.g. with python3 -m venv my-venv)
2282 • Install gcovr in development mode, and install nox:
2284 pip install -e .
2286 pip install nox
2287 You can then run gcovr as gcovr or python3 -m gcovr.
2289 Run the tests to verify that everything works (see Test suite).
2291 • (Optional) Activate GitHub Actions for your forked repository, so
2293 that the cross-platform compatibility tests get run whenever you push
2294 your work to your repository. These tests will also be run when you
2295 open a pull request to the main gcovr repository.
2296 Tip: If you have problems getting everything set up, consider looking
2298 at these files:
2299 • for Linux: .github/workflows/test.yml and admin/Dockerfile.qa
2301 • for Windows: .github/workflows/test.yml
2303 Project Structure
2305 ┌───────────────────┬────────────────────────────┐
2306 │Path │ Description │
2307 ├───────────────────┼────────────────────────────┤
2308 │/ │ project root │
2309 └───────────────────┴────────────────────────────┘
2310 │/gcovr/ │ the gcovr source code │
2312 │ │ (Python module) │
2313 ├───────────────────┼────────────────────────────┤
2314 │/gcovr/__main__.py │ command line interface + │
2315 │ │ top-level behaviour │
2316 ├───────────────────┼────────────────────────────┤
2317 │/gcovr/templates/ │ HTML report templates │
2318 ├───────────────────┼────────────────────────────┤
2319 │/gcovr/tests/ │ unit tests + integration │
2320 │ │ test corpus │
2321 ├───────────────────┼────────────────────────────┤
2322 │/noxfile.py │ Definition of tests tasks │
2323 ├───────────────────┼────────────────────────────┤
2324 │/setup.py │ Python package configura‐ │
2325 │ │ tion │
2326 ├───────────────────┼────────────────────────────┤
2327 │/doc/ │ documentation │
2328 ├───────────────────┼────────────────────────────┤
2329 │/doc/sources/ │ user guide + website │
2330 ├───────────────────┼────────────────────────────┤
2331 │/doc/examples/ │ runnable examples for the │
2332 │ │ user guide │
2333 └───────────────────┴────────────────────────────┘
2334 The program entrypoint and command line interface is in
2336 gcovr/__main__.py. The coverage data is parsed in the gcovr.gcov mod‐
2337 ule. The HTML, XML, text, and summary reports are in gcovr.genera‐
2338 tor.html and respective modules.
2339 Test suite
2341 The QA process (python3 -m nox) consists of multiple parts:
2342 • linting and checking format(python3 -m nox --session lint)
2344 • tests (python3 -m nox --session tests)
2346 • unit tests in gcovr/tests
2348 • integration tests in gcovr/tests
2350 • documentation examples in doc/examples
2352 • documentation build (python3 -m nox --session doc)
2354 The tests are in the gcovr/tests directory. You can run the tests with
2356 python3 -m nox --session tests for the default GCC version (specified
2357 via CC environment variable, defaults to gcc-5). You can also select
2358 the gcc version if you run the tests with e.g. python3 -m nox --ses‐
2359 sion 'tests_compiler(gcc-8)'.
2360 There are unit tests for some parts of gcovr, and a comprehensive cor‐
2362 pus of example projects that are executed as the test_gcovr.py integra‐
2363 tion test. Each gcovr/tests/* directory is one such example project.
2364 You can format files with python3 -m nox --session black)
2366 To get a list of all available sessions run python3 -m nox -l.
2368 The next sections discuss the structure of integration tests, how to
2370 run and filter tests, and how to run tests with Docker.
2371 Changed in version 5.2: If black is called without arguments, all files
2373 are reformated instead of checked. To check the format use the session
2374 lint.
2375 Structure of integration tests
2378 Each project in the corpus contains a Makefile and a reference direc‐
2379 tory:
2380 gcovr/tests/sometest/
2382 reference/
2383 Makefile
2384 README
2385 example.cpp
2386 The Makefile controls how the project is built, and how gcovr should be
2388 invoked. The reference directory contains baseline files against which
2389 the gcovr output is compared. Tests can be executed even without base‐
2390 line files.
2391 Each Makefile contains the following targets:
2393 • all: builds the example project. Can be shared between gcovr invoca‐
2395 tions.
2396 • run: lists available targets which must be a subset of the available
2398 output formats.
2399 • clean: remove any generated files after all tests of the scenario
2401 have finished.
2402 • output formats (txt, html, json, sonarqube, ...): invoke gcovr to
2404 produce output files of the correct format. The test runner automat‐
2405 ically finds the generated files (if any) and compares them to the
2406 baseline files in the reference directory. All formats are optional,
2407 but using at least JSON is recommended.
2408 • clean-each: if provided, will be invoked by the test runner after
2410 testing each format.
2411 Run and filter tests
2413 To run all tests, use python3 -m nox. The tests currently assume that
2414 you are using GCC 5 and have set up a development environment. You can
2415 select a different GCC version by setting the CC environment variable.
2416 Supported versions are CC=gcc-5, CC=gcc-6, CC=gcc-8, CC=gcc-9, gcc-10,
2417 gcc-11, clang-10, clang-13 and clang-14.
2418 You can run the tests with additional options by adding -- and then the
2420 options to the test invocation. Run all tests after each change is a
2421 bit slow, therefore you can limit the tests to a specific test file,
2422 example project, or output format. For example:
2423 # run only XML tests
2425 python3 -m nox --session tests -- -k 'xml'
2426 # run the simple1 tests
2428 python3 -m nox --session tests -- -k 'simple1'
2429 # run the simple1 tests only for XML
2431 python3 -m nox --session tests -- -k 'xml and simple1'
2432 To see which tests would be run, add the --collect-only option:
2434 #see which tests would be run
2436 python3 -m nox --session tests -- --collect-only
2437 Sometimes during development you need to create reference files for new
2439 test or update the current reference files. To do this you have to add
2440 --generate_reference or --update-reference option to the test invoca‐
2441 tion. By default generated output files are automatically removed af‐
2442 ter test run. To skip this process you can add --skip_clean option the
2443 test invocation. For example:
2444 # run tests and generate references for simple1 example
2446 python3 -m nox --session tests -- -k 'simple1' --generate_reference
2447 # run tests and update xml references for simple1 example
2449 python3 -m nox --session tests -- -k 'xml and simple1' --update_reference
2450 # run only XML tests and do not remove generated files
2452 python3 -m nox --session tests -- -k 'xml' --skip_clean
2453 To update the refernce data for all compiler in one call see run tests
2455 with Docker.
2456 When the currently generated output reports differ to the reference
2458 files you can create a ZIP archive named diff.zip in the tests direc‐
2459 tory by using --archive_differences option. Currently in gcovr it is
2460 used by GitHub CI to create a ZIP file with the differences as an arti‐
2461 fact.
2462 # run tests and generate a ZIP archive when there were differences
2464 python3 -m nox --session tests -- --archive_differences
2465 Changed in version 5.1: Change how to start test from make test to
2467 python3 -m nox --session tests
2468 New in version 5.0: Added test options --generate_reference, --up‐
2471 date_reference, --skip_clean, '--archive_differences' and changed way
2472 to call tests only by make test.
2473 Run tests with Docker
2476 If you can't set up a toolchain locally, you can run the QA process via
2477 Docker. First, build the container image:
2478 python3 -m nox --session docker_build
2480 Then, run the container, which executes nox within the container:
2482 python3 -m nox --session docker_run -s qa
2484 Or to build and run the container in one step:
2486 python3 -m nox --session docker_qa
2488 You can select the gcc version to use inside the docker by setting the
2490 environment variable CC to gcc-5 (default), gcc-6, gcc-8, gcc-9,
2491 gcc-10, gcc-11, clang-10, clang-13 or clang-14 or you can build and run
2492 the container with:
2493 python3 -m nox --session 'docker_qa_compiler(gcc-9)'
2495 To run a specific session you can use the session docker_compiler and
2497 give the arguments to the nox executed inside the container after a --
2498 :
2499 python3 -m nox --session 'docker_compiler(gcc-9)' -- -s tests
2501 You can also use the compiler 'all' to run the tests for all compiler
2503 versions. This is useful to update the all reference files:
2504 python3 -m nox --session 'docker_compiler(all)' -- -s tests -- --update_reference
2506 Become a gcovr developer
2508 After you've contributed a bit (whether with discussions, documenta‐
2509 tion, or code), consider becoming a gcovr developer. As a developer,
2510 you can:
2511 • manage issues and pull requests (label and close them)
2513 • review pull requests (a developer must approve each PR before it can
2515 be merged)
2516 • participate in votes
2518 Just open an issue that you're interested, and we'll have a quick vote.
2520
2522 gcovr Release History and Change Log
2523 6.0 (08 March 2023)
2525 Known bugs:
2526 Breaking changes:
2528 • Remove not allowed attributes function-rate, functions-covered and
2530 functions-valid from cobertura report. (#671)
2531 • Remove "noncode" entries in JSON reports. (#663)
2533 • New --exclude-noncode-lines to exclude noncode lines. Noncode lines
2535 are not excluded by default anymore. (#704, #705)
2536 • Changed --gcov-ignore-parse-errors to accept list of errors to ig‐
2538 nore. (#701)
2539 • The default filename for --cobertura is changed from coverage.xml to
2541 cobertura.xml (#721)
2542 • Handling of gcov errors:
2544 • Do not ignore return code of gcov. (#653)
2546 • New --gcov-ignore-errors to ignore gcov errors. Old behavior was to
2548 print a warning and continue. (#718)
2549 • Revert changes from #623 and add documentation entry Support of Keil
2551 uVision format. (#727)
2552 New features and notable changes:
2554 • New --html-nested for reports that summarize subdirectories with ag‐
2556 gregated statistics per directory. (#687)
2557 • Accept NAN % which is used in GCOV 7.5.0 instead of an invalid value.
2559 (#651)
2560 • New --json-base to define a base bath used in JSON reports. (#656)
2562 • New --calls to report call coverage: function calls invoked/total (‐
2564 #666)
2565 • New nox session to generate a portable application with pyinstaller,
2567 see How to create a standalone application. (#661)
2568 • Print a warning if root directory contains symlinks. (#652)
2570 • Change --keep when calling gcov internaly. (#703)
2572 • Allow annotations for never executed branches. (#711)
2574 • Add function merge mode for same function defined in different lines.
2576 (#700)
2577 • Update link to gcovr documentation in HTML report to point to the
2579 documentation of the used version. (#723)
2580 • Add environment SOURCE_DATE_EPOCH to set default for --timestamp. (‐
2582 #729)
2583 Bug fixes and small improvements:
2585 • Fix --html-tab-size feature. (#650)
2587 • Fix alphabetical sort of html report, for when there are symlinks. (‐
2589 #685)
2590 • Handle --version before parsing the configuration file. (#696)
2592 • Fix reports of excluded coverage. (#409, #503, #663)
2594 • Fix handling for nonexistent source code for HTML-details and Cover‐
2596 alls reports. (#663)
2597 • Exclude functions with Exclusion Markers. (#713)
2599 • Fix problem in decision parser if open block brace is on same line.
2601 (#681)
2602 • Add Python 3.11 to test matrix. (#717)
2604 • Fix casing of files if filesystem is case insensitive. (#694)
2606 • Fix deadlock if -j is used and there are errors from gcov execution.
2608 (#719)
2609 • Fix problem in decision parser if case is not on a single line with
2611 the break statement. (#738)
2612 • Do not use realpath for DirectoryPrefixFilter to support symlinks in
2614 root directory. (#712)
2615 Documentation:
2617 • Add detailed reference for the JSON output format. (#663)
2619 Internal changes:
2621 • Select the --html-theme using CSS classes. (#650)
2623 • Change and extend cmake tests. (#676)
2625 • Detect gcc version for running tests. (#686)
2627 • Use scrubbed data for --update_reference option. (#698)
2629 • Install ninja with package manager instead of GitHub action. (#699)
2631 • Rename the reference files coverage.xml to cobertura.xml and the test
2633 from xml to cobertura (#721)
2634 • Add support for clang-14 in our test suite and improve startup per‐
2636 formance of docker image. (#731)
2637 • Compare files by extension in test suite. (#733)
2639 • Split HTML templates into one file for each part of the page. (#735)
2641 • Change docker image to be able to use it like the nox command itself.
2643 (#734)
2644 5.2 (06 August 2022)
2646 New features and notable changes:
2647 • Log additional info on gcov parsing errors. (#589)
2649 • Add support for branch exclude markers. (#644)
2651 • Additional options to configure the thresholds for lines and branches
2653 in HTML separate. (#645)
2654 Bug fixes and small improvements:
2656 • Remove function coverage from sonarcube report. (#591)
2658 • Fix parallel processing of gcov data. (#592)
2660 • Better diagnostics when dealing with corrupted input files. (#593)
2662 • Accept metadata lines without values (introduced in gcc-11). (#601)
2664 • Properly close <a> element in detailed HTML report. (#602)
2666 • Use ≥ sign instead of >= in HTML legend. (#603)
2668 • Using --add-tracefile will now correctly merge branch coverage. (‐
2670 #600)
2671 • Fix package-level function coverage statistics in Cobertura XML re‐
2673 ports. (#605)
2674 • Respect excluded/noncode lines for aggregated branchcoverage. (#611)
2676 • Fix list options in configuration file (search-path). (#612)
2678 • Fix assert and key error in --decisions flag. (#642)
2680 • Fix adding none existing lines by decision analysis to data model. (‐
2682 #617)
2683 • Always treat relative paths in config files as relative to the direc‐
2685 tory of the file. (#615)
2686 • More flexible .gcov parsing to support files generated by third party
2688 tools. (#621, #623)
2689 Internal changes:
2691 • Fix black check to fail on format errors. (#594)
2693 • Change session black with no arguments to format all files. (#595)
2695 • Add gcc-10 and gcc-11 to the test suite. (#597)
2697 • Improved internal coverage data model to simplify processing. (#600)
2699 • Use pretty print for cobertura and coveralls in test suite. (#606)
2701 • Forward nox options --reuse-existing-virtualenvs and --no-install to
2703 call inside docker. (#616)
2704 5.1 (26 March 2022)
2706 Breaking changes:
2707 • Dropped support for Python 3.6 (#550)
2709 • Changed xml configuration key to cobertura (#552)
2711 • JSON summary output: all percentages are now reported from 0 to 100
2713 (#570)
2714 New features and notable changes:
2716 • Report function coverage (#362, #515, #554)
2718 • Consistent support for symlinks across operating systems
2720 • Support for Windows junctions (#535)
2722 • Symlinks are only resolved for evaluating filters (#565)
2724 • Show error message on STDERR when --fail-under-line or
2726 --fail-under-branch fails (#502)
2727 • Can report decision coverage with --decisions option (reasonably for‐
2729 matted C/C++ source files only, HTML and JSON output) (#350)
2730 • Can create reproducible reports with the --timestamp option (#546)
2732 • Improvements to Exclusion Markers (LINE/START/STOP)
2734 • Can ignore markers in code with --no-markers option (#361)
2736 • Can customize patterns with --exclude-pattern-prefix option (#561)
2738 • Can use --cobertura as a less ambiguous alias for --xml. (#552)
2740 Bug fixes and small improvements:
2742 • Gcov is invoked without localization by setting LC_ALL=C (#513)
2744 • Gcov is invoked without temporary directories (#525)
2746 • Gcov: solved problems with file name limitations. (#528)
2748 • Fixed "root" path in JSON summary report. (#548)
2750 • Correctly resolve relative filters in configuration files. (#568)
2752 • HTML output: indicate lines with excluded coverage (#503)
2754 • HTML output: fixed sanity check to support empty files (#571)
2756 • HTML output: support jinja2 >= 3.1 (#576)
2758 Documentation:
2760 • Split documentation into smaller pages (#552)
2762 • Document used options for gcov (#528)
2764 Internal changes:
2766 • Replaced own logger with Python's logging module. (#540)
2768 • New parser for .gcov file format, should be more robust. (#512)
2770 • New tests
2772 • more compilers: clang-10 (#484), clang-13 (#527), gcc-9 (#527)
2774 • -fprofile-abs-path compiler option (#521)
2776 • enabled symlink tests for Windows (#539)
2778 • Improvements to the test suite
2780 • Use Nox instead of Makefiles to manage QA checks (#516, #555)
2782 • Can run tests for all compiler versions in one go (#514)
2784 • More linter checks (#566) and code style enforcement with black (‐
2786 #579)
2787 • Better XML diffing with yaxmldiff (#495, #509)
2789 • Share test reference data between compiler versions where possible
2791 (#556)
2792 • Better environment variable handling (#493, #541)
2794 • Fixed glob patterns for collecting reference files (#533)
2796 • Add timeout for each single test. (#572)
2798 • Improvements and fixes to the release process (#494, #537)
2800 • Normalize shell scripts to Unix line endings (#538, #547)
2802 5.0 (11 June 2021)
2804 Breaking changes:
2805 • Dropped support for Python 2 and Python 3.5. From now on, gcovr will
2807 only support Python versions that enjoy upstream support.
2808 Improvements and new features:
2810 • Handles spaces in gcov path. (#385)
2812 • Early fail when output cannot be created. (#382)
2814 • Add --txt for text output. (#387)
2816 • Add --csv for CSV output. (#376)
2818 • Add --exclude-lines-by-pattern to filter out source lines by arbi‐
2820 trary regex. (#356)
2821 • Add --json-summary to generate a JSON Summary report. (#366)
2823 • Add --coveralls to generate a Coveralls compatible JSON report. (‐
2825 #328)
2826 • Add support for output directories. If the output ends with a / or \
2828 it is used as a directory. (#416)
2829 • Compare paths case insensitive if file system of working directory is
2831 case insensitive. (#329)
2832 • Add wildcard pattern to json --add-tracefile. (#351)
2834 • Enable --filter and --exclude for Merging coverage. (#373)
2836 • Only output 100.0% in text and HTML output if really 100.0%, else use
2838 99.9%. (#389)
2839 • Support relative source location for shadow builds. (#410)
2841 • Incorrect path for header now can still generate html-details reports
2843 (#271)
2844 • Change format version in JSON output from number to string and update
2846 it to "0.2". (#418, #463)
2847 • Only remove --root path at the start of file paths. (#452)
2849 • Fix coverage report for cmake ninja builds with given in-source ob‐
2851 ject-directory. (#453)
2852 • Add issue templates. (#461)
2854 • Add --exclude-function-lines to exclude the line of the function def‐
2856 inition in the coverage report. (#430)
2857 • Changes for HTML output format:
2859 • Redesign HTML generation. Add --html-self-contained to control ex‐
2861 ternal or internal CSS. (#367)
2862 • Change legend for threshold in html report. (#371)
2864 • Use HTML title also for report heading. Default value for
2866 --html-title changed. (#378)
2867 • Add --html-tab-size to configure tab size in HTML details. (#377)
2869 • Add option --html-css for user defined styling. (#380)
2871 • Create details html filename independent from OS. (#375)
2873 • Add --html-theme to change the color theme. (#393)
2875 • Add linkable lines in HTML details. (#401)
2877 • Add syntax highlighting in the details HTML report. This can be
2879 turned off with --no-html-details-syntax-highlighting. (#402, #415)
2880 Documentation:
2882 • Cookbook: Out-of-Source Builds with CMake (#340, #341)
2884 Internal changes:
2886 • Add makefile + dockerfile for simpler testing.
2888 • Add .gitbugtraq to link comments to issue tracker in GUIs. (#429)
2890 • Add GitHub actions to test PRs and master branch. (#404)
2892 • Remove Travis CI. (#419)
2894 • Remove Appveyor CI and upload coverage report from Windows and Ubuntu
2896 from the GitHub actions. (#455)
2897 • Add check if commit is mentioned in the CHANGELOG.rst. (#457)
2899 • Move flake8 config to setup.cfg and add black code formatter. (#444)
2901 • Fix filter/exclude relative path issue in Windows. (#320, #479)
2903 • Extend test framework for CI:
2905 • Set make variable TEST_OPTS as environment variable inside docker.
2907 (#372)
2908 • Add make variable USE_COVERAGE to extend flags for coverage report
2910 in GitHub actions. (#404)
2911 • Extend tests to use an unified diff in the assert. Add test options
2913 --generate_reference, --update_reference and --skip_clean. (#379)
2914 • Support multiple output patterns in integration tests. (#383)
2916 • New option --archive_differences to save the different files as
2918 ZIP. Use this ZIP as artifact in AppVeyor. (#392)
2919 • Add support for gcc-8 to test suite and docker tests. (#423)
2921 • Run as limited user inside docker container and add test with read
2923 only directory. (#445)
2924 4.2 (6 November 2019)
2926 Breaking changes:
2927 • Dropped support for Python 3.4.
2929 • Format flag parameters like --xml or --html now take an optional out‐
2931 put file name. This potentially changes the interpretation of search
2932 paths. In gcovr --xml foo, previous gcovr versions would search the
2933 foo directory for coverage data. Now, gcovr will try to write the
2934 Cobertura report to the foo file. To keep the old meaning, separate
2935 positional arguments like gcovr --xml -- foo.
2936 Improvements and new features:
2938 • Configuration file support (experimental). (#167, #229, #279, #281,
2940 #293, #300, #304)
2941 • JSON output. (#301, #321, #326)
2943 • Merging coverage with gcovr --add-tracefile. (#10, #326)
2945 • SonarQube XML Output. (#308)
2947 • Handle cyclic symlinks correctly during coverage data search. (#284)
2949 • Simplification of --object-directory heuristics. (#18, #273, #280)
2951 • Exception-only code like a catch clause is now shown as uncovered.
2953 (#283)
2954 • New --exclude-throw-branches option to exclude exception handler
2956 branches. (#283)
2957 • Support --root .. style invocation, which might fix some CMake-re‐
2959 lated problems. (#294)
2960 • Fix wrong names in report when source and build directories have sim‐
2962 ilar names. (#299)
2963 • Stricter argument handling. (#267)
2965 • Reduce XML memory usage by moving to lxml. (#1, #118, #307)
2967 • Can write multiple reports at the same time by giving the output file
2969 name to the report format parameter. Now, gcovr --html -o cov.html
2970 and gcovr --html cov.html are equivalent. (#291)
2971 • Override gcov locale properly. (#334)
2973 • Make gcov parser more robust when used with GCC 8. (#315)
2975 Known issues:
2977 • The --keep option only works when using existing gcov files with -g/‐
2979 --use-gcov-files. (#285, #286)
2980 • Gcovr may get confused when header files in different directories
2982 have the same name. (#271)
2983 • Gcovr may not work when no en_US locale is available. (#166)
2985 Documentation:
2987 • Exclusion marker documentation.
2989 • FAQ: Why does C++ code have so many uncovered branches? (#283)
2991 • FAQ: Why are uncovered files not reported? (#33, #100, #154, #290,
2993 #298)
2994 Internal changes:
2996 • More tests. (#269, #268, #269)
2998 • Refactoring and removal of dead code. (#280)
3000 • New internal data model.
3002 4.1 (2 July 2018)
3004 • Fixed/improved --exclude-directories option. (#266)
3005 • New "Cookbook" section in the documentation. (#265)
3007 4.0 (17 June 2018)
3009 Breaking changes:
3010 • This release drops support for Python 2.6. (#250)
3012 • PIP is the only supported installation method.
3014 • No longer encoding-agnostic under Python 2.7. If your source files
3016 do not use the system encoding (probably UTF-8), you will have to
3017 specify a --source-encoding. (#148, #156, #256)
3018 • Filters now use forward slashes as path separators, even on Windows.
3020 (#191, #257)
3021 • Filters are no longer normalized into pseudo-paths. This could
3023 change the interpretation of filters in some edge cases.
3024 Improvements and new features:
3026 • Improved --help output. (#236)
3028 • Parse the GCC 8 gcov format. (#226, #228)
3030 • New --source-encoding option, which fixes decoding under Python 3.
3032 (#256)
3033 • New --gcov-ignore-parse-errors flag. By default, gcovr will now
3035 abort upon parse errors. (#228)
3036 • Detect the error when gcov cannot create its output files (#243,
3038 #244)
3039 • Add -j flag to run gcov processes in parallel. (#3, #36, #239)
3041 • The --html-details flag now implies --html. (#93, #211)
3043 • The --html output can now be used without an --output filename (#223)
3045 • The docs are now managed with Sphinx. (#235, #248, #249, #252, #253)
3047 • New --html-title option to change the title of the HTML report. (‐
3049 #261, #263)
3050 • New options --html-medium-threshold and --html-high-threshold to cus‐
3052 tomize the color legend. (#261, #264)
3053 Internal changes:
3055 • Huge refactoring. (#214, #215, #221 #225, #228, #237, #246)
3057 • Various testing improvements. (#213, #214, #216, #217, #218, #222,
3059 #223, #224, #227, #240, #241, #245)
3060 • HTML reports are now rendered with Jinja2 templates. (#234)
3062 • New contributing guide. (#253)
3064 3.4 (12 February 2018)
3066 • Added --html-encoding command line option (#139).
3067 • Added --fail-under-line and --fail-under-branch options, which will
3069 error under a given minimum coverage. (#173, #116)
3070 • Better pathname resolution heuristics for --use-gcov-file. (#146)
3072 • The --root option defaults to current directory '.'.
3074 • Improved reports for "(", ")", ";" lines.
3076 • HTML reports show full timestamp, not just date. (#165)
3078 • HTML reports treat 0/0 coverage as NaN, not 100% or 0%. (#105, #149,
3080 #196)
3081 • Add support for coverage-04.dtd Cobertura XML format (#164, #186)
3083 • Only Python 2.6+ is supported, with 2.7+ or 3.4+ recommended. (#195)
3085 • Added CI testing for Windows using Appveyor. (#189, #200)
3087 • Reports use forward slashes in paths, even on Windows. (#200)
3089 • Fix to support filtering with absolute paths.
3091 • Fix HTML generation with Python 3. (#168, #182, #163)
3093 • Fix --html-details under Windows. (#157)
3095 • Fix filters under Windows. (#158)
3097 • Fix verbose output when using existing gcov files (#143, #144)
3099 3.3 (6 August 2016)
3101 • Added CI testing using TravisCI
3102 • Added more tests for out of source builds and other nested builds
3104 • Avoid common file prefixes in HTML output (#103)
3106 • Added the --execlude-directories argument to exclude directories from
3108 the search for symlinks (#87)
3109 • Added branches taken/not taken to HTML (#75)
3111 • Use --object-directory to scan for gcov data files (#72)
3113 • Improved logic for nested makefiles (#135)
3115 • Fixed unexpected semantics with --root argument (#108)
3117 • More careful checks for covered lines (#109)
3119 3.2 (5 July 2014)
3121 • Adding a test for out of source builds
3122 • Using the starting directory when processing gcov filenames. (#42)
3124 • Making relative paths the default in html output.
3126 • Simplify html bar with coverage is zero.
3128 • Add option for using existing gcov files (#35)
3130 • Fixing --root argument processing (#27)
3132 • Adding logic to cover branches that are ignored (#28)
3134 3.1 (6 December 2013)
3136 • Change to make the -r/--root options define the root directory for
3137 source files.
3138 • Fix to apply the -p option when the --html option is used.
3140 • Adding new option, '--exclude-unreachable-branches' that will exclude
3142 branches in certain lines from coverage report.
3143 • Simplifying and standardizing the processing of linked files.
3145 • Adding tests for deeply nested code, and symbolic links.
3147 • Add support for multiple —filter options in same manner as —exclude
3149 option.
3150 3.0 (10 August 2013)
3152 • Adding the '--gcov-executable' option to specify the name/location of
3153 the gcov executable. The command line option overrides the environ‐
3154 ment variable, which overrides the default 'gcov'.
3155 • Adding an empty "<methods/>" block to <classes/> in the XML output:
3157 this makes out XML complient with the Cobertura DTD. (#3951)
3158 • Allow the GCOV environment variable to override the default 'gcov'
3160 executable. The default is to search the PATH for 'gcov' if the GCOV
3161 environment variable is not set. (#3950)
3162 • Adding support for LCOV-style flags for excluding certain lines from
3164 coverage analysis. (#3942)
3165 • Setup additional logic to test with Python 2.5.
3167 • Added the --html and --html-details options to generate HTML.
3169 • Sort output for XML to facilitate baseline tests.
3171 • Added error when the --object-directory option specifies a bad direc‐
3173 tory.
3174 • Added more flexible XML testing, which can ignore XML elements that
3176 frequently change (e.g. timestamps).
3177 • Added the '—xml-pretty' option, which is used to generate pretty XML
3179 output for the user manual.
3180 • Many documentation updates
3182 2.4 (13 April 2012)
3184 • New approach to walking the directory tree that is more robust to
3185 symbolic links (#3908)
3186 • Normalize all reported path names
3188 • Normalize using the full absolute path (#3921)
3190 • Attempt to resolve files referenced through symlinks to a common
3192 project-relative path
3193 • Process gcno files when there is no corresponding gcda file to pro‐
3195 vide coverage information for unexecuted modules (#3887)
3196 • Windows compatibility fixes
3198 • Fix for how we parse source: file names (#3913)
3200 • Better handling od EOL indicators (#3920)
3202 • Fix so that gcovr cleans up all .gcov files, even those filtered by
3204 command line arguments
3205 • Added compatibility with GCC 4.8 (#3918)
3207 • Added a check to warn users who specify an empty --root option (see
3209 #3917)
3210 • Force gcov to run with en_US localization, so the gcovr parser runs
3212 correctly on systems with non-English locales (#3898, #3902).
3213 • Segregate warning/error information onto the stderr stream (#3924)
3215 • Miscellaneous (Python 3.x) portability fixes
3217 • Added the master svn revision number as part of the verson identifier
3219 2.3.1 (6 January 2012)
3221 • Adding support for Python 3.x
3222 2.3 (11 December 2011)
3224 • Adding the --gcov-filter and --gcov-exclude options.
3225 2.2 (10 December 2011)
3227 • Added a test driver for gcovr.
3228 • Improved estimation of the <sources> element when using gcovr with
3230 filters.
3231 • Added revision and date keywords to gcovr so it is easier to identify
3233 what version of the script users are using (especially when they are
3234 running a snapshot from trunk).
3235 • Addressed special case mentioned in [comment:ticket:3884:1]: do not
3237 truncate the reported file name if the filter does not start matching
3238 at the beginning of the string.
3239 • Overhaul of the --root / --filter logic. This should resolve the is‐
3241 sue raised in #3884, along with the more general filter issue raised
3242 in [comment:ticket:3884:1]
3243 • Overhaul of gcovr's logic for determining gcc/g++'s original working
3245 directory. This resolves issues introduced in the original implemen‐
3246 tation of --object-directory (#3872, #3883).
3247 • Bugfix: gcovr was only including a <sources> element in the XML re‐
3249 port if the user specified -r (#3869)
3250 • Adding timestamp and version attributes to the gcovr XML report (see
3252 #3877). It looks like the standard Cobertura output reports number
3253 of seconds since the epoch for the timestamp and a doted decimal ver‐
3254 sion string. Now, gcovr reports seconds since the epoch and "gcovr
3255 ``"+``__version__ (e.g. "gcovr 2.2") to differentiate it from a pure
3256 Cobertura report.
3257 2.1 (26 November 2010)
3259 • Added the --object-directory option, which allows for a flexible
3260 specification of the directory that contains the objects generated by
3261 gcov.
3262 • Adding fix to compare the absolute path of a filename to an exclusion
3264 pattern.
3265 • Adding error checking when no coverage results are found. The line
3267 and branch counts can be zero.
3268 • Adding logic to process the -o/--output option (#3870).
3270 • Adding patch to scan for lines that look like:
3272 creating `foo'
3274 as well as
3276 creating 'foo'
3278 • Changing the semantics for EOL to be portable for MS Windows.
3280 • Add attributes to xml format so that it could be used by hudson/bam‐
3282 boo with cobertura plug-in.
3283 2.0 (22 August 2010)
3285 • Initial release as a separate package. Earlier versions of gcovr
3286 were managed within the 'fast' Python package.
3287
3289 Copyright (c) 2013-2023 the gcovr authors Copyright (c) 2013 Sandia
3290 Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia
3291 Corporation, the U.S. Government retains certain rights in this soft‐
3292 ware.
3293 This software is distributed under the 3-clause BSD License. See LI‐
3295 CENSE.txt for full details. See AUTHORS.txt for the full list of con‐
3296 tributors.
3297 Gcovr development moved to this repository in September, 2013 from San‐
3299 dia National Laboratories.
3300 License Terms
3302 Gcovr is available under the terms of a BSD-3-clause license:
3303 Copyright (c) 2013-2023 the gcovr authors
3305 Copyright (c) 2013 Sandia Corporation.
3306 Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
3307 the U.S. Government retains certain rights in this software.
3308 All rights reserved.
3310 Redistribution and use in source and binary forms, with or without
3312 modification, are permitted provided that the following conditions
3313 are met:
3314 * Redistributions of source code must retain the above copyright notice,
3316 this list of conditions and the following disclaimer.
3317 * Redistributions in binary form must reproduce the above copyright
3319 notice, this list of conditions and the following disclaimer in the
3320 documentation and/or other materials provided with the distribution.
3321 * Neither the name of the Sandia National Laboratories nor the names of
3323 its contributors may be used to endorse or promote products derived from
3324 this software without specific prior written permission.
3325 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
3327 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
3328 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
3329 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
3330 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
3331 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
3332 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
3333 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
3334 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
3335 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
3336 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3337 Acknowledgements
3340 Gcovr is maintained by:
3341 Lukas Atkinson and Michael Förderer.
3342 The following developers contributed to gcovr (ordered alphabetically):
3344 alex43dm, Andrew Stone, Antonio Quarta, Arvin Schnell, Attie Grande,
3345 Bernhard Breinbauer, Carlos Jenkins, Cary Converse, Cezary Gapiński,
3346 Christian Taedcke, Dave George, Davide Pesavento, Dom Postorivo,
3347 ebmmy, Elektrobit Automotive GmbH, Ensky Lin, Glenn Töws, Grégoire
3348 Roussel, goriy, Irfan Adilovic, ja11sop, James Reynolds, Jeremy Fix‐
3349 emer, Jessica Levine, Joachim Kuebart, Joel Klinghed, Johan
3350 Bertrand, John Siirola, Jörg Kreuzberger, Jordi Sabater, Kai
3351 Blaschke, Kevin Broselge, Kevin Cai, Klaus Weinbauer, Leon Ma,
3352 libPhipp, Lukas Atkinson, Lukas Baischer, Luke Woydziak, Marek Kur‐
3353 dej, Martin Mraz, Matsumoto Taichi, Matthew Stadelman, Matthias
3354 Schmieder, Matthieu Darbois, Matthieu Eyraud, Michael Förderer,
3355 Michał Pszona, Mikael Salson, Mikk Leini, Nikolaj Schumacher, Olek‐
3356 siy Pikalo, Pablo Martín, Phil Clapham, Piotr Dziwinski, Reto
3357 Schneider, Richard Kjerstadius, Robert Rosengren, Songmin Li, Steven
3358 Myint, Sylvestre Ledru, TFA-N, Thibault Gasc, Tilo Wiedera, Tyler W.
3359 Mace, trapzero, Will Thompson, William Hart, Zachary J. Fields,
3360 Zachary P. Hensley, and possibly others.
3361 The development of Gcovr has been partially supported by Sandia Na‐
3363 tional Laboratories. Sandia National Laboratories is a multi-program
3364 laboratory managed and operated by Sandia Corporation, a wholly owned
3365 subsidiary of Lockheed Martin Corporation, for the U.S. Department of
3366 Energy's National Nuclear Security Administration under contract
3367 DE-AC04-94AL85000.
3368
3370 the gcovr authors
3371
3373 2023, the gcovr authors
33746.0 Jul 19, 2023 GCOVR(1)