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 5.2.
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 18.04 and 20.04 and Windows
114 Server 2019.
115 Compiler:
117 GCC and Clang.
118 The automated tests run on GCC 5, 6, and 8.
120
122 The gcovr command provides a summary of the lines that have been exe‐
123 cuted in a program. Code coverage statistics help you discover
124 untested parts of a program, which is particularly important when as‐
125 sessing code quality. Well-tested code is a characteristic of high
126 quality code, and software developers often assess code coverage sta‐
127 tistics when deciding if software is ready for a release.
128 GCC can instrument the executables to emit coverage data. You need to
130 recompile your code with the following flags:
131 --coverage -g -O0
133 Next, run your test suite. This will generate raw coverage files.
135 Finally, invoke gcovr. This will print a tabular report on the con‐
137 sole.
138 gcovr
140 You can also generate detailed HTML reports:
142 gcovr --html-details coverage.html
144 Gcovr will create one HTML report per source file next to the cover‐
146 age.html summary.
147 You should run gcovr from the build directory. The -r option should
149 point to the root of your project. This only matters if you have a
150 separate build directory. For example:
151 cd build; gcovr -r ..
153 What to read next
155 The User Guide explains how to use the features of gcovr. In particu‐
156 lar:
157 • Compiling for Coverage
159 • Output Formats
161 • Using Filters
163 The Command Line Reference provides an overview of all options.
165 Specific problems might be addressed in the Cookbook or the Frequently
167 Asked Questions.
168
170 The user guide describes the various features of gcovr. It assumes you
171 have read the Getting Started guide.
172 This User Guide provides the following sections:
174 Compiling for Coverage
176 In order to collect coverage data, your software must be “instrumented”
177 by the compiler. That means, you must re-compile your software with
178 special compiler options.
179 The general workflow is:
181 1. compile your software to enable coverage profiling
183 2. execute your software to collect coverage profiles
185 3. run gcovr to create reports from the collected coverage profiling
187 data
188 This document explains how you can use GCC or Clang to compile with
190 coverage instrumentation.
191 If you cannot compile your software with coverage flags, you cannot use
193 gcovr. However, other tools like kcov might help.
194 Example Code
196 The following example.cpp program is used to illustrate the compilation
197 process:
198 1 // example.cpp
200 2
201 3 int foo(int param)
202 4 {
203 5 if (param)
204 6 {
205 7 return 1;
206 8 }
207 9 else
208 10 {
209 11 return 0;
210 12 }
211 13 }
212 14
213 15 int main(int argc, char* argv[])
214 16 {
215 17 foo(0);
216 18
217 19 return 0;
218 20 }
219 This code executes several subroutines in this program, but some lines
221 in the program are not executed.
222 Compiler Options
224 We compile example.cpp with the GCC compiler as follows:
225 g++ -fprofile-arcs -ftest-coverage -fPIC -O0 example.cpp -o program
227 What do these compiler flags mean?
229 • We compile without optimization (-O0), because optimizations may
231 merge lines of code or otherwise change the flow of execution in the
232 program. This can change the measured coverage.
233 On the other hand, enabling basic optimizations with -O1 can some‐
235 times produce “better” coverage reports, especially for C++. This is
236 a matter of personal preference, just make sure to avoid comparing
237 coverage metrics across optimization levels.
238 If you are having problems with lots of uncovered branches, see: Why
240 does C++ code have so many uncovered branches?
241 • Either --coverage or -fprofile-arcs -ftest-coverage are needed so
243 that the compiler produces the information necessary to gather cover‐
244 age data.
245 With these options, the compiler adds logic to the output program
247 that counts how often which part of the code was executed. The com‐
248 piler will also create a example.gcno file with metadata. The name
249 of the gcno file matches the compilation unit (see below).
250 Optional compiler flags:
252 • You can use other flags like -g or -fPIC as required by your tests.
254 These don't affect the coverage results.
255 • Using -fprofile-abs-path (available since GCC 8) can avoid some prob‐
257 lems with interpreting the coverage data correctly. By default, the
258 additional coverage files generated by GCC contain relative paths
259 from the working directory to the source files. If there are multi‐
260 ple potential working directories from which you might have run the
261 compiler, gcovr can get confused. Adding this option is more robust.
262 This examples uses the g++ compiler for C++ code, but any GCC or
264 Clang-based compiler should work.
265 If you are using CMake, see Out-of-Source Builds with CMake for infor‐
267 mation on configuring that build system to compile your software with
268 coverage enabled.
269 Running the Program
271 The above compiler invocation generated a program executable. Now, we
272 have to execute this command:
273 ./program
275 This will run whatever you designed this program to do. Often, such a
277 program would contain unit tests to exercise your code.
278 As a side effect, this will create an example.gcda file with the cover‐
280 age data for our compilation unit. This is a binary file so it needs
281 to be processed first. Together, the .gcda and .gcno files can be used
282 to create coverage reports.
283 Processing Coverage
285 Your compiler ships with tools to analyze the coverage data files. For
286 GCC, this is gcov. For Clang, this is llvm-cov. You don't have to
287 call these programs yourself – gcovr will do that for you.
288 So let's invoke gcovr:
290 gcovr
292 This will search for all your .gcno and .gcda files, run the compiler's
294 gcov tool, and summarize the code coverage statistics into a report.
295 By default, we get a text summary on the command line that shows aggre‐
296 gate statistics for each line:
297 ------------------------------------------------------------------------------
299 GCC Code Coverage Report
300 Directory: .
301 ------------------------------------------------------------------------------
302 File Lines Exec Cover Missing
303 ------------------------------------------------------------------------------
304 example.cpp 7 6 85% 7
305 ------------------------------------------------------------------------------
306 TOTAL 7 6 85%
307 ------------------------------------------------------------------------------
308 Gcovr supports many different Output Formats that you can generate in‐
311 stead.
312 Choosing the Right Gcov Executable
314 If you have multiple compilers installed or if you are using Clang, you
315 will likely need to tell gcovr which gcov executable to use. By de‐
316 fault, gcovr just uses the program named gcov. This is fine for the
317 default GCC compiler, e.g. gcc or g++. Otherwise, you must use the
318 --gcov-executable to tell gcovr what to use.
319 If you have used a specific GCC version (e.g. gcc-8 or g++-8), then you
321 must name the gcov tool with the corresponding version. For example:
322 gcovr --gcov-executable gcov-8
324 If you have used Clang, then you can use its gcov emulation mode. For
326 example:
327 gcovr --gcov-executable "llvm-cov gcov"
329 Again, the llvm-cov name may have to include your compiler version.
331 Working with Multiple Object Files
333 Code coverage instrumentation works on a per object file basis, which
334 means you have to re-compile your entire project to collect coverage
335 data.
336 The C/C++ model has a concept of “compilation units”. A large project
338 is typically not compiled in one go, but in separate steps. The result
339 of compiling a compilation unit is a .o object file with the machine
340 code. The object code from multiple compilation units is later linked
341 into the final executable or library. The previous example only had a
342 single compilation unit, so no explicit linking step was necessary.
343 Because each compilation unit is compiled independently, every one has
345 to be instrumented with coverage counters separately. A common mistake
346 is to add the compiler flags for coverage (e.g. in the CFLAGS or
347 CXXFLAGS variables) but then forgetting to force a re-compile. Depend‐
348 ing on the build system, it may be necessary to clear out the old ob‐
349 ject files that weren't compiled with coverage, e.g. with a make clean
350 command. Other build systems use a separate build directory when com‐
351 piling with coverage so that incremental compilation works as expected.
352 Each object file will have an associated .gcno and .gcda file in the
354 same directory as the .o object file. For example, consider the fol‐
355 lowing compilation process:
356 # (1) compile to object code
358 g++ --coverage -c -o a.o a.cpp
359 g++ --coverage -c -o b.o b.cpp
360 # (2) link the object files in the program
362 g++ --coverage -o the-program a.o b.o
363 # (3) run the program
365 ./the-program
366 1. Compiling the object code creates the a.o and b.o object files, but
368 also corresponding a.gcno and b.gcno notes files, one for each com‐
369 pilation unit. The -c option is used to only compile but to not
370 link the code.
371 2. Linking the object code produces the final program. This has no ef‐
373 fect on coverage processing, except that the --coverage flag makes
374 sure that a compiler-internal gcov support library is linked.
375 3. Running the program will increment the in-memory coverage counters
377 for all executed lines. At the end, the counters are written into
378 gcov data files, one for each compilation unit. Here, we would get
379 a.gcda and b.gcda files.
380 If you only want coverage data for certain source files, it is suffi‐
382 cient to only compile those compilation units with coverage enabled
383 that contain these source files. But this can be tricky to do cor‐
384 rectly. For example, header files are often part of multiple compila‐
385 tion units.
386 Output Formats
388 Gcovr supports a variety of output formats that are documented on the
389 following pages.
390 Text Output
392 The text output format summarizes coverage in a plain-text table. This
393 is the default output format if no other format is selected. This out‐
394 put format can also be explicitly selected with the gcovr --txt option.
395 New in version 5.0: Added explicit --txt option.
397 Example output:
400 ------------------------------------------------------------------------------
402 GCC Code Coverage Report
403 Directory: .
404 ------------------------------------------------------------------------------
405 File Lines Exec Cover Missing
406 ------------------------------------------------------------------------------
407 example.cpp 7 6 85% 7
408 ------------------------------------------------------------------------------
409 TOTAL 7 6 85%
410 ------------------------------------------------------------------------------
411 Line Coverage
414 Running gcovr without any explicit output formats …
415 gcovr
417 generates a text summary of the lines executed:
419 ------------------------------------------------------------------------------
421 GCC Code Coverage Report
422 Directory: .
423 ------------------------------------------------------------------------------
424 File Lines Exec Cover Missing
425 ------------------------------------------------------------------------------
426 example.cpp 7 6 85% 7
427 ------------------------------------------------------------------------------
428 TOTAL 7 6 85%
429 ------------------------------------------------------------------------------
430 The same result can be achieved when explicit --txt option is set. For
433 example:
434 gcovr --txt
436 generates the same text summary.
438 Each line of this output includes a summary for a given source file,
440 including the number of lines instrumented, the number of lines exe‐
441 cuted, the percentage of lines executed, and a summary of the line num‐
442 bers that were not executed. To improve clarity, gcovr uses an aggres‐
443 sive approach to grouping uncovered lines and will combine uncovered
444 lines separated by "non-code" lines (blank, freestanding braces, and
445 single-line comments) into a single region. As a result, the number of
446 lines listed in the "Missing" list may be greater than the difference
447 of the "Lines" and "Exec" columns.
448 Note that gcov accumulates statistics by line. Consequently, it works
450 best with a programming style that places only one statement on each
451 line.
452 Branch Coverage
454 The gcovr command can also summarize branch coverage using the
455 -b/--branches option:
456 gcovr --branches
458 This generates a tabular output that summarizes the number of branches,
460 the number of branches taken and the branches that were not completely
461 covered:
462 ------------------------------------------------------------------------------
464 GCC Code Coverage Report
465 Directory: .
466 ------------------------------------------------------------------------------
467 File Branches Taken Cover Missing
468 ------------------------------------------------------------------------------
469 example.cpp 2 1 50% 5
470 ------------------------------------------------------------------------------
471 TOTAL 2 1 50%
472 ------------------------------------------------------------------------------
473 The same result can be achieved when explicit --txt option is set. For
476 example:
477 gcovr --branches --txt
479 prints the same tabular output.
481 HTML Output
483 The gcovr command can also generate a simple HTML output using the
484 --html option:
485 gcovr --html
487 This generates a HTML summary of the lines executed. In this example,
489 the file example1.html is generated, which has the following output:
490 [image]
491 The default behavior of the --html option is to generate HTML for a
493 single webpage that summarizes the coverage for all files. The HTML is
494 printed to standard output, but the -o/--output option is used to spec‐
495 ify a file that stores the HTML output.
496 The --html-details option is used to create a separate web page for
498 each file. Each of these web pages includes the contents of file with
499 annotations that summarize code coverage. Consider the following com‐
500 mand:
501 gcovr --html-details example_html.details.html
503 This generates the following HTML page for the file example1.cpp: [im‐
505 age]
506 Note that the --html-details option needs a named output, e.g. via the
508 the -o/--output option. For example, if the output is named cover‐
509 age.html, then the web pages generated for each file will have names of
510 the form coverage.<filename>.html.
511 The --html-self-contained option controls whether assets like CSS
513 styles are bundled into the HTML file. The --html report defaults to
514 self-contained mode. but --html-details defaults to
515 --no-html-self-contained in order to avoid problems with the Content
516 Security Policy of some servers, especially Jenkins.
517 New in version 5.0: Added --html-self-contained and
519 --no-html-self-contained.
520 Changed in version 5.0: Default to external CSS file for
523 --html-details.
524 Cobertura XML Output
527 The default output format for gcovr is to generate a tabular summary in
528 plain text. The gcovr command can also generate a Cobertura XML output
529 using the --cobertura and --cobertura-pretty options:
530 gcovr --cobertura-pretty
532 This generates an XML summary of the lines executed:
534 <?xml version='1.0' encoding='UTF-8'?>
536 <!DOCTYPE coverage SYSTEM 'http://cobertura.sourceforge.net/xml/coverage-04.dtd'>
537 <coverage line-rate="0.8571428571428571" branch-rate="0.5" lines-covered="6" lines-valid="7" branches-covered="1" branches-valid="2" function-rate="1.0" functions-covered="2" functions-valid="2" complexity="0.0" timestamp="1573053861" version="gcovr 5.2">
538 <sources>
539 <source>.</source>
540 </sources>
541 <packages>
542 <package name="" line-rate="0.8571428571428571" branch-rate="0.5" function-rate="1.0" complexity="0.0">
543 <classes>
544 <class name="example_cpp" filename="example.cpp" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
545 <methods/>
546 <lines>
547 <line number="3" hits="1" branch="false"/>
548 <line number="5" hits="1" branch="true" condition-coverage="50% (1/2)">
549 <conditions>
550 <condition number="0" type="jump" coverage="50%"/>
551 </conditions>
552 </line>
553 <line number="7" hits="0" branch="false"/>
554 <line number="11" hits="1" branch="false"/>
555 <line number="15" hits="1" branch="false"/>
556 <line number="17" hits="1" branch="false"/>
557 <line number="19" hits="1" branch="false"/>
558 </lines>
559 </class>
560 </classes>
561 </package>
562 </packages>
563 </coverage>
564 This XML format is in the Cobertura XML format suitable for import and
566 display within the Jenkins and Hudson continuous integration servers
567 using the Cobertura Plugin. Gcovr also supports a Sonarqube XML Out‐
568 put.
569 The --cobertura option generates a denser XML output, and the
571 --cobertura-pretty option generates an indented XML output that is eas‐
572 ier to read. Note that the XML output contains more information than
573 the tabular summary. The tabular summary shows the percentage of cov‐
574 ered lines, while the XML output includes branch statistics and the
575 number of times that each line was covered. Consequently, XML output
576 can be used to support performance optimization in the same manner that
577 gcov does.
578 New in version 5.1: The --cobertura and --cobertura-pretty options were
580 added as an alias for -x/--xml and --xml-pretty, respectively. This
581 avoids confusion with other XML output formats like Sonarqube XML Out‐
582 put. The old options remain available for backwards compatibility.
583 Sonarqube XML Output
586 If you are using Sonarqube, you can get a coverage report in a suitable
587 XML format via the --sonarqube option:
588 gcovr --sonarqube coverage.xml
590 The Sonarqube XML format is documented at
592 https://docs.sonarqube.org/latest/analysis/generic-test/.
593 JSON Output
595 The gcovr command can also generate a JSON output using the --json and
596 --json-pretty options:
597 gcovr --json coverage.json
599 The --json-pretty option generates an indented JSON output that is eas‐
601 ier to read.
602 If you just need a summary of the coverage information, similar to the
604 tabulated text based output, you can use --json-summary instead (see
605 JSON Summary Output).
606 Multiple JSON files can be merged into the coverage data with sum of
608 lines and branches execution, see Merging Coverage Data.
609 JSON Format Reference
611 Structure of file is based on gcov JSON intermediate format with addi‐
612 tional key names specific to gcovr.
613 Structure of the JSON is following:
615 {
617 "gcovr/format_version": gcovr_json_version
618 "files": [file]
619 }
620 gcovr_json_version: version of gcovr JSON format. This is indepen‐
622 dently versioned from gcovr itself.
623 Each file has the following form:
625 {
627 "file": file
628 "lines": [line]
629 }
630 file: path to source code file, relative to gcovr root directory.
632 Each line has the following form:
634 {
636 "branches": [branch]
637 "count": count
638 "line_number": line_number
639 "gcovr/noncode": gcovr_noncode
640 }
641 gcovr_noncode: if True coverage info on this line should be ignored
643 Each branch has the following form:
645 {
647 "count": count
648 "fallthrough": fallthrough
649 "throw": throw
650 }
651 file, line and branch have the structure defined in gcov intermediate
653 format. This format is documented at
654 https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov.
655 JSON Summary Output
657 The --json-summary option output coverage summary in a machine-readable
658 format for additional post processing. The format is identical to JSON
659 output --json option without detailed lines information. The
660 --json-summary-pretty option generates an indented JSON summary output
661 that is easier to read. Consider the following command:
662 gcovr --json-summary-pretty --json-summary
664 This generates an indented JSON summary:
666 {
668 "branch_covered": 1,
669 "branch_percent": 50.0,
670 "branch_total": 2,
671 "files": [
672 {
673 "branch_covered": 1,
674 "branch_percent": 50.0,
675 "branch_total": 2,
676 "filename": "example.cpp",
677 "function_covered": 2,
678 "function_percent": 100.0,
679 "function_total": 2,
680 "line_covered": 6,
681 "line_percent": 85.7,
682 "line_total": 7
683 }
684 ],
685 "function_covered": 2,
686 "function_percent": 100.0,
687 "function_total": 2,
688 "gcovr/summary_format_version": "0.5",
689 "line_covered": 6,
690 "line_percent": 85.7,
691 "line_total": 7,
692 "root": "."
693 }
694 New in version 5.0: Added --json-summary and --json-summary-pretty.
696 CSV Output
699 The --csv option output comma-separated values summarizing the coverage
700 of each file. Consider the following command:
701 gcovr --csv
703 This generates an CSV:
705 filename,line_total,line_covered,line_percent,branch_total,branch_covered,branch_percent,function_total,function_covered,function_percent
707 example.cpp,7,6,0.857,2,1,0.5,2,2,1.0
708 New in version 5.0: Added --csv.
711 Coveralls JSON Output
714 If you are using Coveralls, you can get a coverage report in a suitable
715 JSON format via the --coveralls option:
716 gcovr --coveralls coverage.json
718 The --coveralls-pretty option generates an indented JSON output that is
720 easier to read.
721 Keep in mind that the output contains the checksums of the source
723 files. If you are using different OSes, the line endings shall be the
724 same.
725 If available, environment variable COVERALLS_REPO_TOKEN will be con‐
727 sumed and baked into the JSON output.
728 If running in a CI additional variables are used:
730 • In Travis CI:
732 • TRAVIS_JOB_ID
734 • TRAVIS_BUILD_NUMBER
736 • TRAVIS_PULL_REQUEST
738 • TRAVIS_COMMIT
740 • TRAVIS_BRANCH
742 • In Appveyor:
744 • APPVEYOR_JOB_ID
746 • APPVEYOR_JOB_NUMBER
748 • APPVEYOR_PULL_REQUEST_NUMBER
750 • APPVEYOR_REPO_COMMIT
752 • APPVEYOR_REPO_BRANCH
754 • In Jenkins CI:
756 • JOB_NAME
758 • BUILD_ID
760 • CHANGE_ID
762 • GIT_COMMIT (if available)
764 • BRANCH_NAME
766 • In GitHub Actions:
768 • GITHUB_WORKFLOW
770 • GITHUB_RUN_ID
772 • GITHUB_SHA
774 • GITHUB_HEAD_REF (if available)
776 • GITHUB_REF
778 The Coveralls JSON format is documented at
780 https://docs.coveralls.io/api-introduction.
781 New in version 5.0: Added --coveralls and --coveralls-pretty.
783 You can use Multiple Output Formats at the same time.
786 Multiple Output Formats
788 You can write multiple report formats with one gcovr invocation by
789 passing the output filename directly to the report format flag. If no
790 filename is specified for the format, the value from -o/--output is
791 used by default, which itself defaults to stdout.
792 The following report format flags can take an optional output file
794 name:
795 • gcovr --csv
797 • gcovr --txt
799 • gcovr --cobertura
801 • gcovr --html
803 • gcovr --html-details
805 • gcovr --sonarqube
807 • gcovr --json
809 • gcovr --json-summary
811 • gcovr --coveralls
813 If the value given to the output option ends with a path seperator (/
815 or \) it is used a directory which is created first and a default file‐
816 name depending on the format is used.
817 Note that --html-details overrides any value of --html if it is
819 present.
820 Merging Coverage Data
822 You can merge coverage data from multiple runs with -a/--add-tracefile.
823 For each run, generate JSON output:
825 ... # compile and run first test case
827 gcovr ... --json run-1.json
828 ... # compile and run second test case
829 gcovr ... --json run-2.json
830 Next, merge the json files and generate the desired report:
832 gcovr --add-tracefile run-1.json --add-tracefile run-2.json --html-details coverage.html
834 You can also use unix style wildcards to merge the json files without
836 duplicating -a/--add-tracefile. With this option you have to place your
837 pathnames with wildcards in double quotation marks:
838 gcovr --add-tracefile "run-*.json" --html-details coverage.html
840 Using Filters
842 Gcovr tries to only report coverage for files within your project, not
843 for your libraries. This is influenced by the following options:
844 • -r, --root
846 • -f, --filter
848 • -e, --exclude
850 • --gcov-filter
852 • --gcov-exclude
854 • --exclude-directories
856 • (the current working directory where gcovr is invoked)
858 These options take filters. A filter is a regular expression that
860 matches a file path. Because filters are regexes, you will have to es‐
861 cape “special” characters with a backslash \.
862 Always use forward slashes / as path separators, even on Windows:
864 • wrong: --filter C:\project\src\
866 • correct: --filter C:/project/src/
868 If the filter looks like an absolute path, it is matched against an ab‐
870 solute path. Otherwise, the filter is matched against a relative path,
871 where that path is relative to the current directory or if defined in a
872 configuration file to the directory of the file.
873 Examples of relative filters:
875 • --filter subdir/ matches only that subdirectory
877 • --filter '\.\./src/' matches a sibling directory ../src. But because
879 a dot . matches any character in a regex, we have to escape it. You
880 have to use additional shell escaping. This example uses single
881 quotes for Bash or POSIX shell.
882 • --filter '(.+/)?foo\.c$' matches only files called foo.c. The regex
884 must match from the start of the relative path, so we ignore any
885 leading directory parts with (.+/)?. The $ at the end ensures that
886 the path ends here.
887 If no -f/--filter is provided, the -r/--root is turned into a default
889 filter. Therefore, files outside of the -r/--root directory are ex‐
890 cluded.
891 To be included in a report, the source file must match any -f/--filter,
893 and must not match any -e/--exclude filter.
894 The --gcov-filter and --gcov-exclude filters apply to the .gcov files
896 created by gcov. This is useful mostly when running gcov yourself, and
897 then invoking gcovr with -g/--use-gcov-files. But these filters also
898 apply when gcov is launched by gcovr.
899 Speeding up coverage data search
901 The --exclude-directories filter is used while searching for raw cover‐
902 age data (or for existing .gcov files when -g/--use-gcov-files is ac‐
903 tive). This filter is matched against directory paths, not file paths.
904 If a directory matches, all its contents (files and subdirectories)
905 will be excluded from the search. For example, consider this build di‐
906 rectory:
907 build/
909 ├─ main.o
910 ├─ main.gcda
911 ├─ main.gcno
912 ├─ a/
913 │ ├─ awesome_code.o
914 │ ├─ awesome_code.gcda
915 │ └─ awesome_code.gcno
916 └─ b/
917 ├─ better_code.o
918 ├─ better_code.gcda
919 └─ better_code.gcno
920 If we run gcovr --exclude-directories 'build/a$', this will exclude
922 anything in the build/a directory but will use the coverage data for
923 better_code.o and main.o.
924 This can speed up gcovr when you have a complicated build directory
926 structure. Consider also using the search_paths or --object-directory
927 arguments to specify where gcovr starts searching. If you are unsure
928 which directories are being searched, run gcovr in -v/--verbose mode.
929 For each found coverage data file gcovr will invoke the gcov tool.
931 This is typically the slowest part, and other filters can only be ap‐
932 plied after this step. In some cases, parallel execution with the -j
933 option might be helpful to speed up processing.
934 Filters for symlinks
936 Gcovr matches filters against real paths that have all their symlinks
937 resolved. E.g. consider this project layout:
938 /home/you/
940 ├─ project/ (pwd)
941 │ ├─ src/
942 │ ├─ relevant-library/ -> ../external-library/
943 │ └─ ignore-this/
944 └─ external-library/
945 └─ src/
946 Here, the relevant-library has the real path /home/you/external-li‐
948 brary.
949 To write a filter that includes both src/ and relevant-library/src/, we
951 cannot use --filter relevant-library/src/ because that contains a sym‐
952 link. Instead, we have to use an absolute path to the real name:
953 gcovr --filter src/ --filter /home/you/external-library/src/
955 or a relative path to the real path:
957 gcovr --filter src/ --filter '\.\./external-library/src/'
959 New in version 5.1: gcovr also supports symlinks/junctions/drive sub‐
961 stitutions on Windows.
962 Configuration Files
965 WARNING:
966 Config files are an experimental feature and may be subject to
967 change without prior notice.
968 Defaults for the command line options can be set in a configuration
970 file. Example:
971 filter = src/
973 html-details = yes # info about each source file
974 output = build/coverage.html
975 How the configuration file is found: If a --config option is provided,
977 that file is used. Otherwise, a gcovr.cfg file in the -r/--root direc‐
978 tory is used, if that file exists.
979 Each line contains a key = value pair. Space around the = is optional.
981 The value may be empty. Comments start with a hash # and ignore the
982 rest of the line, but cannot start within a word. Empty lines are also
983 ignored.
984 The available config keys correspond closely to the command line op‐
986 tions, and are parsed similarly. In most cases, the name of a long
987 command line option can be used as a config key. If not, this is docu‐
988 mented in the option's help message. For example, --gcov-executable
989 can be set via the gcov-executable config key. But -b/--branches is
990 set via txt-branch.
991 Just like command line options, the config keys can be specified multi‐
993 ple times. Depending on the option the last one wins or a list will be
994 built. For example, -f/--filter can be provided multiple times:
995 # Only show coverage for files in src/, lib/foo, or for main.cpp files.
997 filter = src/
998 filter = lib/foo/
999 filter = *./main\.cpp
1000 Note that relative filters specified in config files will be inter‐
1002 preted relative to the location of the config file itself.
1003 Option arguments are parsed with the following precedence:
1005 • First the config file is parsed, if any.
1007 • Then, all command line arguments are added.
1009 • Finally, if an option was specified neither in a config file nor on
1011 the command line, its documented default value is used.
1012 Therefore, it doesn't matter whether a value is provided in the config
1014 file or the command line.
1015 Boolean flags are treated specially. When their config value is “yes”
1017 they are enabled, as if the flag had been provided on the command line.
1018 When their value is “no”, they are explicitly disabled by assigning
1019 their default value. The -j flag is special as it takes an optional
1020 argument. In the config file, gcov-parallel = yes would refer to the
1021 no-argument form, whereas gcov-parallel = 4 would provide an explicit
1022 argument.
1023 If the option is a path and is not absolute the path is used relative
1025 to the config file. For the option gcovr --add-tracefile the directory
1026 of the config file is always prepended.
1027 Some config file syntax is explicitly reserved for future extensions:
1029 Semicolon comments, INI-style sections, multi-line values, quoted val‐
1030 ues, variable substitutions, alternative key–value separators, …
1031 Exclusion Markers
1033 You can exclude parts of your code from coverage metrics.
1034 • If GCOVR_EXCL_LINE appears within a line, that line is ignored.
1036 • If GCOVR_EXCL_START appears within a line, all following lines (in‐
1038 cluding the current line) are ignored until a GCOVR_EXCL_STOP marker
1039 is encountered.
1040 Instead of GCOVR_*, the markers may also start with GCOV_* or LCOV_*.
1042 However, start and stop markers must use the same style. The prefix is
1043 configurable with the option --exclude-pattern-prefix.
1044 In the excluded regions, any coverage is excluded. It is not currently
1046 possible to exclude only branch coverage in that region. In particu‐
1047 lar, lcov's EXCL_BR markers are not supported (see issue #121).
1048 Reproducible Timestamps
1050 In some cases, it may be desirable to list a specific timestamp in the
1051 report. Timestamps are shown in the HTML Output, Coveralls JSON Out‐
1052 put, and the Cobertura XML Output. This can be achieved via the
1053 --timestamp option. This option does not affect the modification times
1054 or other filesystem metadata.
1055 New in version 5.1: The gcovr --timestamp option.
1057 Timestamp Syntax
1060 The timestamp option understands different formats: Unix timestamps and
1061 RFC-3339 timestamps.
1062 Unix timestamps (also known as Posix time or Epoch) are the number of
1064 seconds since 1 Jan 1970. These timestamps are always resolved in the
1065 UTC timezone. Example usage:
1066 gcovr --timestamp 1640606727
1068 RFC 3339 specifies a reasonable subset of ISO-8601 timestamps. This is
1070 the YYYY-MM-DDThh:mm:ss format, optionally followed by a timezone off‐
1071 set (+hh:mm, or Z for UTC). Example usage without a timezone:
1072 gcovr --timestamp '2021-12-27 13:05:27'
1074 Example usages that show equivalent specifications for UTC timestamps:
1076 gcovr --timestamp '2021-12-27T13:05:27Z'
1078 gcovr --timestamp '2021-12-27T13:05:27+00:00'
1079 gcovr --timestamp '2021-12-27T13:05:27-00:00'
1080 Differences and clarifications with respect to RFC-3339:
1082 • the time zone may be omitted
1084 • the date and time parts may be separated by a space character instead
1086 of the T
1087 • the date is parsed in a case insensitive manner
1089 • sub-second accuracy is not currently supported
1091 Additional formats may be added in the future. To ensure that time‐
1093 stamps are handled in the expected manner, it is possible to select a
1094 particular timestamp syntax with a prefix.
1095 • Epoch timestamps can be selected with a @ or epoch: prefix.
1097 • RFC-3339 timestamps can be selected with a rfc3339: prefix.
1099 Examples of prefixes:
1101 gcovr --timestamp @1640606727
1103 gcovr --timestamp epoch:1640606727
1104 gcovr --timestamp 'rfc3339:2021-12-27 13:05:27'
1105 Using timestamps from Git commits
1107 As an example of using the timestamp feature, we might want to attri‐
1108 bute a coverage report to the time when a Git commit was created. Git
1109 lets us extract the commit date from a commit with the git show com‐
1110 mand. For the current HEAD commit:
1111 git show --no-patch --format=%cI HEAD
1113 This can be combined into a Bash one-liner like this:
1115 gcovr --timestamp="$(git show --no-patch --format=%cI HEAD)"
1117 Each Git commit has two dates, the author date and the committer date.
1119 This information can be extracted with various format codes, e.g. %aI
1120 for the author date and %cI for the committer date. These format codes
1121 are also available in different formats. The supported Git formats
1122 are:
1123 • Unix timestamps: %at, %ct
1125 • "Strict ISO" format: %aI, %cI
1127 • depending on the --date option: %ad, %cd
1129 Git's --date option is documented in git log. The supported settings
1131 are:
1132 • Unix timestamps: --date=unix
1134 • "Strict ISO" format: --date=iso-strict, --date=iso8601-strict,
1136 --date=iso-strict-local, --date=iso8601-strict-local
1137 Related documents:
1139 • Installation
1141 • Getting Started
1143 • Command Line Reference
1145 • Cookbook
1147 • Frequently Asked Questions
1149 • Contributing (includes instructions for bug reports)
1151 • Change Log
1153 • License
1155
1157 The gcovr command recursively searches a directory tree to find gcov
1158 coverage files, and generates a text summary of the code coverage. The
1159 -h/--help option generates the following summary of the gcovr command
1160 line options:
1161 gcovr
1163 A utility to run gcov and summarize the coverage in simple reports.
1164 usage: gcovr [options] [search_paths...]
1166 See <http://gcovr.com/> for the full manual.
1168 Options
1170 search_paths
1171 Search these directories for coverage files. Defaults to --root
1172 and --object-directory. Config key: search-path.
1173 -h, --help
1175 Show this help message, then exit.
1176 --version
1178 Print the version number, then exit.
1179 -v, --verbose
1181 Print progress messages. Please include this output in bug re‐
1182 ports.
1183 -r <root>, --root <root>
1185 The root directory of your source files. Defaults to '.', the
1186 current directory. File names are reported relative to this
1187 root. The --root is the default --filter.
1188 -a <add_tracefile>, --add-tracefile <add_tracefile>
1190 Combine the coverage data from JSON files. Coverage files con‐
1191 tains source files structure relative to root directory. Those
1192 structures are combined in the output relative to the current
1193 root directory. Unix style wildcards can be used to add the
1194 pathnames matching a specified pattern. In this case pattern
1195 must be set in double quotation marks. Option can be specified
1196 multiple times. When option is used gcov is not run to collect
1197 the new coverage data.
1198 --config <config>
1200 Load that configuration file. Defaults to gcovr.cfg in the
1201 --root directory.
1202 --no-markers
1204 Turn off exclusion markers. Any exclusion markers specified in
1205 source files will be ignored.
1206 --fail-under-line <min>
1208 Exit with a status of 2 if the total line coverage is less than
1209 MIN. Can be ORed with exit status of '--fail-under-branch' op‐
1210 tion.
1211 --fail-under-branch <min>
1213 Exit with a status of 4 if the total branch coverage is less
1214 than MIN. Can be ORed with exit status of '--fail-under-line'
1215 option.
1216 --source-encoding <source_encoding>
1218 Select the source file encoding. Defaults to the system default
1219 encoding (utf-8).
1220 --exclude-lines-by-pattern <exclude_lines_by_pattern>
1222 Exclude lines that match this regex.
1223 --exclude-branches-by-pattern <exclude_branches_by_pattern>
1225 Exclude branches that match this regex.
1226 --exclude-pattern-prefix <exclude_pattern_prefix>
1228 Define the regex prefix used in markers / line exclusions (i.e
1229 ..._EXCL_START, ..._EXCL_START, ..._EXCL_STOP)
1230 Output Options
1232 Gcovr prints a text report by default, but can switch to XML or HTML.
1233 -o <output>, --output <output>
1235 Print output to this filename. Defaults to stdout. Individual
1236 output formats can override this.
1237 -b, --branches
1239 Report the branch coverage instead of the line coverage. For
1240 text report only. Config key: txt-branch.
1241 --decisions
1243 Report the decision coverage. For HTML and JSON report.
1244 -u, --sort-uncovered
1246 Sort entries by increasing number of uncovered lines. For text
1247 and HTML report.
1248 -p, --sort-percentage
1250 Sort entries by increasing percentage of uncovered lines. For
1251 text and HTML report.
1252 --txt <output>
1254 Generate a text report. OUTPUT is optional and defaults to
1255 --output.
1256 --cobertura <output>, -x <output>, --xml <output>
1258 Generate a Cobertura XML report. OUTPUT is optional and defaults
1259 to --output.
1260 --cobertura-pretty, --xml-pretty
1262 Pretty-print the Cobertura XML report. Implies --cobertura. De‐
1263 fault: False.
1264 --html <output>
1266 Generate a HTML report. OUTPUT is optional and defaults to
1267 --output.
1268 --html-details <output>
1270 Add annotated source code reports to the HTML report. Implies
1271 --html. OUTPUT is optional and defaults to --output.
1272 --html-details-syntax-highlighting
1274 Use syntax highlighting in HTML details page. Enabled by de‐
1275 fault. Negation: --no-html-details-syntax-highlighting.
1276 --html-theme {green,blue}
1278 Override the default color theme for the HTML report. Default is
1279 green.
1280 --html-css <css>
1282 Override the default style sheet for the HTML report.
1283 --html-title <title>
1285 Use TITLE as title for the HTML report. Default is 'GCC Code
1286 Coverage Report'.
1287 --html-medium-threshold <medium>
1289 If the coverage is below MEDIUM, the value is marked as low cov‐
1290 erage in the HTML report. MEDIUM has to be lower than or equal
1291 to value of --html-high-threshold and greater than 0. If MEDIUM
1292 is equal to value of --html-high-threshold the report has only
1293 high and low coverage. Default is 75.0.
1294 --html-high-threshold <high>
1296 If the coverage is below HIGH, the value is marked as medium
1297 coverage in the HTML report. HIGH has to be greater than or
1298 equal to value of --html-medium-threshold. If HIGH is equal to
1299 value of --html-medium-threshold the report has only high and
1300 low coverage. Default is 90.0.
1301 --html-medium-threshold-branch <medium_branch>
1303 If the coverage is below MEDIUM_BRANCH, the value is marked as
1304 low coverage in the HTML report. MEDIUM_BRANCH has to be lower
1305 than or equal to value of --html-high-threshold-branch and
1306 greater than 0. If MEDIUM_BRANCH is equal to value of
1307 --html-medium-threshold-branch the report has only high and low
1308 coverage. Default is taken from --html-medium-threshold.
1309 --html-high-threshold-branch <high_branch>
1311 If the coverage is below HIGH_BRANCH, the value is marked as
1312 medium coverage in the HTML report. HIGH_BRANCH has to be
1313 greater than or equal to value of --html-medium-thresh‐
1314 old-branch. If HIGH_BRANCH is equal to value of
1315 --html-medium-threshold-branch the report has only high and low
1316 coverage. Default is taken from --html-high-threshold.
1317 --html-medium-threshold-line <medium_line>
1319 If the coverage is below MEDIUM_LINE, the value is marked as low
1320 coverage in the HTML report. MEDIUM_LINE has to be lower than or
1321 equal to value of --html-high-threshold-line and greater than 0.
1322 If MEDIUM_LINE is equal to value of --html-medium-threshold-line
1323 the report has only high and low coverage. Default is taken from
1324 --html-medium-threshold.
1325 --html-high-threshold-line <high_line>
1327 If the coverage is below HIGH_LINE, the value is marked as
1328 medium coverage in the HTML report. HIGH_LINE has to be greater
1329 than or equal to value of --html-medium-threshold-line. If
1330 HIGH_LINE is equal to value of --html-medium-threshold-line the
1331 report has only high and low coverage. Default is taken from
1332 --html-high-threshold.
1333 --html-tab-size <html_tab_size>
1335 Used spaces for a tab in a source file. Default is 4
1336 --html-absolute-paths
1338 Use absolute paths to link the --html-details reports. Defaults
1339 to relative links.
1340 --html-encoding <html_encoding>
1342 Override the declared HTML report encoding. Defaults to UTF-8.
1343 See also --source-encoding.
1344 --html-self-contained
1346 Control whether the HTML report bundles resources like CSS
1347 styles. Self-contained reports can be sent via email, but con‐
1348 flict with the Content Security Policy of some web servers. De‐
1349 faults to self-contained reports unless --html-details is used.
1350 Negation: --no-html-self-contained.
1351 -s, --print-summary
1353 Print a small report to stdout with line & function & branch
1354 percentage coverage. This is in addition to other reports. De‐
1355 fault: False.
1356 --sonarqube <output>
1358 Generate sonarqube generic coverage report in this file name.
1359 OUTPUT is optional and defaults to --output.
1360 --json <output>
1362 Generate a JSON report. OUTPUT is optional and defaults to
1363 --output.
1364 --json-pretty
1366 Pretty-print the JSON report. Implies --json. Default: False.
1367 --json-summary <output>
1369 Generate a JSON summary report. OUTPUT is optional and defaults
1370 to --output.
1371 --json-summary-pretty
1373 Pretty-print the JSON SUMMARY report.Implies --json-summary. De‐
1374 fault: False.
1375 --csv <output>
1377 Generate a CSV summary report. OUTPUT is optional and defaults
1378 to --output.
1379 --coveralls <output>
1381 Generate Coveralls API coverage report in this file name. OUTPUT
1382 is optional and defaults to --output.
1383 --coveralls-pretty
1385 Pretty-print the coveralls report. Implies --coveralls. Default:
1386 False.
1387 --timestamp <timestamp>
1389 Override current time for reproducible reports. Can use
1390 YYYY-MM-DD hh:mm:ss or epoch notation. Used by HTML, Coveralls,
1391 and Cobertura reports. Default: current time.
1392 Filter Options
1394 Filters decide which files are included in the report. Any filter must
1395 match, and no exclude filter must match. A filter is a regular expres‐
1396 sion that matches a path. Filter paths use forward slashes, even on
1397 Windows. If the filter looks like an absolute path it is matched
1398 against an absolute path. Otherwise, the filter is matched against a
1399 relative path, where that path is relative to the current directory or
1400 if defined in a configuration file to the directory of the file.
1401 -f <filter>, --filter <filter>
1403 Keep only source files that match this filter. Can be specified
1404 multiple times. Relative filters are relative to the current
1405 working directory or if defined in a configuration file. If no
1406 filters are provided, defaults to --root.
1407 -e <exclude>, --exclude <exclude>
1409 Exclude source files that match this filter. Can be specified
1410 multiple times.
1411 --gcov-filter <gcov_filter>
1413 Keep only gcov data files that match this filter. Can be speci‐
1414 fied multiple times.
1415 --gcov-exclude <gcov_exclude>
1417 Exclude gcov data files that match this filter. Can be specified
1418 multiple times.
1419 --exclude-directories <exclude_dirs>
1421 Exclude directories that match this regex while searching raw
1422 coverage files. Can be specified multiple times.
1423 GCOV Options
1425 The 'gcov' tool turns raw coverage files (.gcda and .gcno) into .gcov
1426 files that are then processed by gcovr. The gcno files are generated by
1427 the compiler. The gcda files are generated when the instrumented pro‐
1428 gram is executed.
1429 --gcov-executable <gcov_cmd>
1431 Use a particular gcov executable. Must match the compiler you
1432 are using, e.g. 'llvm-cov gcov' for Clang. Can include addi‐
1433 tional arguments. Defaults to the GCOV environment variable, or
1434 'gcov': 'gcov'.
1435 --include-internal-functions
1437 Include function coverage of compiler internal functions (start‐
1438 ing with '__' or '_GLOBAL__sub_I_').
1439 --exclude-unreachable-branches
1441 Exclude branch coverage from lines without useful source code
1442 (often, compiler-generated "dead" code). Default: False.
1443 --exclude-function-lines
1445 Exclude coverage from lines defining a function Default: False.
1446 --exclude-throw-branches
1448 For branch coverage, exclude branches that the compiler gener‐
1449 ates for exception handling. This often leads to more "sensible"
1450 coverage reports. Default: False.
1451 -g, --use-gcov-files
1453 Use existing gcov files for analysis. Default: False.
1454 --gcov-ignore-parse-errors
1456 Skip lines with parse errors in GCOV files instead of exiting
1457 with an error. A report will be shown on stderr. Default: False.
1458 --object-directory <objdir>
1460 Override normal working directory detection. Gcovr needs to
1461 identify the path between gcda files and the directory where the
1462 compiler was originally run. Normally, gcovr can guess cor‐
1463 rectly. This option specifies either the path from gcc to the
1464 gcda file (i.e. gcc's '-o' option), or the path from the gcda
1465 file to gcc's working directory.
1466 -k, --keep
1468 Keep gcov files after processing. This applies both to files
1469 that were generated by gcovr, or were supplied via the
1470 --use-gcov-files option. Default: False. Config key:
1471 keep-gcov-files.
1472 -d, --delete
1474 Delete gcda files after processing. Default: False. Config key:
1475 delete-gcov-files.
1476 -j <gcov_parallel>
1478 Set the number of threads to use in parallel. Config key:
1479 gcov-parallel.
1480 For guide-level explanation on using these options, see the User Guide.
1482
1484 This section contains how-to guides on creating code coverage reports
1485 for various purposes. For an introduction on using gcovr, see the User
1486 Guide instead.
1487 Recipes in the cookbook:
1489 • How to collect coverage for C extensions in Python
1491 • Out-of-Source Builds with CMake
1493 How to collect coverage for C extensions in Python
1495 Collecting code coverage data on the C code that makes up a Python ex‐
1496 tension module is not quite as straightforward as with a regular C pro‐
1497 gram.
1498 As with a normal C project, we have to compile our code with coverage
1500 instrumentation. Here, we export CFLAGS="--coverage" and then run
1501 python3 setup.py build_ext.
1502 Unfortunately, build_ext can rebuild a source file even if the current
1504 object file is up to date. If multiple extension modules share the
1505 same source code file, gcov will get confused by the different time‐
1506 stamps and report inaccurate coverage. It is nontrivial to adapt the
1507 build_ext process to avoid this.
1508 Instead, we can use the ccache utility to make the compilation lazy
1510 (works best on Unix systems). Before we invoke the build_ext step, we
1511 first export CC="ccache gcc". Ccache works well but isn't absolutely
1512 perfect, see the ccache manual for caveats.
1513 A shell session might look like this:
1515 # Set required env vars
1517 export CFLAGS="--coverage"
1518 export CC="ccache gcc"
1519 # clear out build files so we get a fresh compile
1521 rm -rf build/temp.* # contains old .gcda, .gcno files
1522 rm -rf build/lib.*
1523 # rebuild extensions
1525 python3 setup.py build_ext --inplace # possibly --force
1526 # run test command i.e. pytest
1528 # run gcovr
1530 rm -rf coverage; mkdir coverage
1531 gcovr --filter src/ --print-summary --html-details coverage/index.html
1532 Out-of-Source Builds with CMake
1534 Tools such as cmake encourage the use of out-of-source builds, where
1535 the code is compiled in a directory other than the one which contains
1536 the sources. This is an extra complication for gcov. In order to pass
1537 the correct compiler and linker flags, the following commands need to
1538 be in CMakeLists.txt:
1539 # This flags are used if cmake is called with -DCMAKE_BUILD_TYPE=PROFILE
1541 set(CMAKE_C_FLAGS_PROFILE --coverage)
1542 set(CMAKE_CXX_FLAGS_PROFILE --coverage)
1543 add_executable(program example.cpp)
1545 The --coverage compiler flag is an alternative to -fprofile-arcs
1547 -ftest-coverage for recent version of gcc. In versions 3.13 and later
1548 of cmake, the target_link_libraries command can be removed and
1549 add_link_options("--coverage") added after the add_compile_options com‐
1550 mand.
1551 We then follow a normal cmake build process:
1553 cd $BLD_DIR
1555 cmake -DCMAKE_BUILD_TYPE=PROFILE $SRC_DIR
1556 make VERBOSE=1
1557 and run the program:
1559 cd $BLD_DIR
1561 ./program
1562 However, invocation of gcovr itself has to change. The assorted .gcno
1564 and .gcda files will appear under the CMakeFiles directory in BLD_DIR,
1565 rather than next to the sources. Since gcovr requires both, the command
1566 we need to run is:
1567 cd $BLD_DIR
1569 gcovr -r $SRC_DIR .
1570
1572 What is the difference between lcov and gcovr?
1573 Both lcov and gcovr are tools to create coverage reports.
1574 Gcovr was originally created as a simple script to provide a convenient
1576 command line interface to gcov that produced more easily digestible
1577 output similar to Python's coverage utilities.
1578 Later, we added XML output that could be used with the Cobertura plugin
1580 of the Jenkins continuous integration server. This gave us nice cover‐
1581 age reports for C/C++ code in Jenkins.
1582 HTML output was added much later. If all you need is HTML, pick which‐
1584 ever one produces the output you like better or integrates easier with
1585 your existing workflow.
1586 Lcov is a far older project that is part of the Linux Test Project. It
1588 provides some features that gcovr does not have: For example, lcov has
1589 explicit support for capturing Linux kernel coverage. Lcov also sup‐
1590 ports various trace file manipulation functions such as merging trace
1591 files from different test runs. You can learn more at the lcov website
1592 or the lcov GitHub repository.
1593 Why does C++ code have so many uncovered branches?
1595 Gcovr's branch coverage reports are based on GCC's -profile-arcs fea‐
1596 ture, which uses the compiler's control flow graph (CFG) of each func‐
1597 tion to determine branches. This is a very low-level view: to under‐
1598 stand the branches in a given function, it can help to view the func‐
1599 tion's assembly, e.g. via the Godbolt Compiler Explorer.
1600 What gcovr calls a branch is in fact an arc between basic blocks in the
1602 CFG. This means gcovr's reports have many branches that are not caused
1603 by if statements! For example:
1604 • Arcs are caused by C/C++ branching operators: for, if, while,
1606 switch/case, &&, ||, ? :. Note that switches are often compiled as a
1607 decision tree which introduces extra arcs, not just one per case.
1608 • (Arcs into another function are not shown.)
1610 • Arcs are caused when a function that may throw returns: one arc to
1612 the next block or statement for normal returns, and one arc to an ex‐
1613 ception handler for exceptions, if this function contains an excep‐
1614 tion handler. Every local variable with a destructor is an exception
1615 handler as well.
1616 • Compiler-generated code that deals with exceptions often needs extra
1618 branches: throw statements, catch clauses, and destructors.
1619 • Extra arcs are created for static initialization and destruction.
1621 • Arcs may be added or removed by compiler optimizations. If you com‐
1623 pile without optimizations, some arcs may even be unreachable!
1624 Gcovr is not able to remove any “unwanted” branches because GCC's gcov
1626 tool does not make the necessary information available, and because
1627 different projects are interested in different kinds of branches. How‐
1628 ever, gcovr has the following options to reduce unwanted branches:
1629 With the gcovr --exclude-unreachable-branches option, gcovr parses the
1631 source code to see whether that line even contains any code. If the
1632 line is empty or only contains curly braces, this could be an indica‐
1633 tion of compiler-generated code that was mis-attributed to that line
1634 (such as that for static destruction) and branch coverage will be ig‐
1635 nored on that line.
1636 With the gcovr --exclude-throw-branches option, exception-only branches
1638 will be ignored. These are typically arcs from a function call into an
1639 exception handler.
1640 With the gcovr --decisions option, gcovr parses the source code to ex‐
1642 tract a ISO 26262 compliant metric for decision coverage. This metric
1643 can be interpreted as the branch coverage on C/C++-Level. While the
1644 feature is not always able to detect the decisions reliabily when the
1645 code is written very compact (uncheckable decisions will be marked), it
1646 provides a reliable tool for (i.e. MISRA-compliant) code in secu‐
1647 rity-relevant situations.
1648 Compiling with optimizations will typically remove unreachable branches
1650 and remove superfluous branches, but makes the coverage report less ex‐
1651 act. For example, branching operators might be optimized away. Deci‐
1652 sion coverage analysis will be very buggy when compiling with optimiza‐
1653 tions. See also: Gcov and Optimization in the GCC documentation.
1654 Despite these approaches, 100% branch coverage will be impossible for
1656 most programs.
1657 Why are uncovered files not reported?
1659 Gcovr does report files that have zero coverage, even when no .gcda
1660 file is available for that compilation unit.
1661 However, the gcov tool in some versions of GCC refuses to generate out‐
1663 put for uncovered files.
1664 To fix this, upgrade GCC to:
1666 • version 5.5 or later,
1668 • version 6.2 or later, or
1670 • any version since 7.
1672 Note that the compiler may ignore inline functions that are never used.
1674 Which options are used for calling gcov?
1676 The options used for calling gcov depends on the version of gcov.
1677 Following options are always used:
1679 • --branch-counts
1681 • --branch-probabilities
1683 • --object-directory
1685 Following options are only used if available:
1687 • --demangled-names: Not available for LLVM based gcov.
1689 • --hash-filenames: Available since GCC 7, as fallback the option
1691 --preserve-paths is used.
1692
1694 This document contains:
1695 • our guidelines for bug reports
1697 • general contribution guidelines
1699 • a checklist for pull requests
1701 • a developer guide that explains the development environment, project
1703 structure, and test suite
1704 How to report bugs
1706 When reporting a bug, first search our issues to avoid duplicates. In
1707 your bug report, please describe what you expected gcovr to do, and
1708 what it actually did. Also try to include the following details:
1709 • how you invoked gcovr, i.e. the exact flags and from which directory
1711 • your project layout
1713 • your gcovr version
1715 • your compiler version
1717 • your operating system
1719 • and any other relevant details.
1721 Ideally, you can provide a short script and the smallest possible
1723 source file to reproduce the problem.
1724 How to help
1726 If you would like to help out, please take a look at our open issues
1727 and pull requests. The issues labeled help wanted and needs review
1728 would have the greatest impact.
1729 There are many ways how you can help:
1731 • assist other users with their problems
1733 • share your perspective as a gcovr user in discussions
1735 • test proposed changes in your real-world projects
1737 • improve our documentation
1739 • submit pull requests with bug fixes and enhancements
1741 How to submit a Pull Request
1743 Thank you for helping with gcovr development! Please follow this
1744 checklist for your pull request:
1745 • Is this a good approach? Fixing open issues is always welcome! If
1747 you want to implement an enhancement, please discuss it first as a
1748 GitHub issue.
1749 • Does it work? Please run the tests locally:
1751 python3 -m nox
1753 (see also: Test suite)
1755 In any case, the tests will run automatically when you open the pull
1757 request. But please prevent unnecessary build failures and run the
1758 tests yourself first. If you cannot run the tests locally, you can
1759 activate GitHub for your fork, or run the tests with Docker. If
1760 there are differences the updated files will be available for down‐
1761 load from the CI system (one ZIP for each test environment).
1762 If you add new features, please try to add a test case.
1764 • Does it conform to the style guide? The source code should conform
1766 to the PEP 8 standard. Please check your code:
1767 python3 -m nox --session lint
1769 # or:
1771 python3 -m flake8 doc gcovr
1773 The command python3 -m nox will run the linter, run the tests, and
1775 check that the docs can be built.
1776 • Add yourself as an author. If this is your first contribution to
1778 gcovr, please add yourself to the AUTHORS.txt file.
1779 • One change at a time. Please keep your commits and your whole pull
1781 request fairly small, so that the changes are easy to review. Each
1782 commit should only contain one kind of change, e.g. refactoring or
1783 new functionality.
1784 • Why is this change necessary? When you open the PR, please explain
1786 why we need this change and what your PR does. If this PR fixes an
1787 open issue, reference that issue in the pull request description.
1788 Add a reference to the issue in the CHANGELOG.rst, if the change
1789 should not be visible in the changelog (minor or not of interest),
1790 add the following string to a single line in the PR body:
1791 [no changelog]
1792 Once you submit the PR, it will be automatically tested on Windows and
1794 Linux, and code coverage will be collected. Your code will be re‐
1795 viewed. This can take a week. Please fix any issues that are discov‐
1796 ered during this process. Feel free to force-push your updates to the
1797 pull request branch.
1798 If you need assistance for your pull request, you can
1800 • chat in our Gitter room
1802 • discuss your problem in an issue
1804 • open an unfinished pull request as a work in progress (WIP), and
1806 explain what you've like to get reviewed
1807 How to set up a development environment
1809 For working on gcovr, you will need a supported version of Python 3,
1810 GCC version 5, 6 or 8 (other GCC versions are supported by gcovr, but
1811 will cause spurious test failures) or clang version 10, make, cmake and
1812 ninja. Please make sure that the tools are in the system PATH. On
1813 Windows, you will need to install a GCC toolchain as the tests expect a
1814 Unix-like environment. You can use MinGW-W64 or MinGW. An easier way
1815 is to run tests with Docker, on Windows a Pro license or the WSL (Win‐
1816 dows subsystem for Linux) is needed.
1817 • Check your GCC installation, the binary directory must be added to
1819 the PATH environment. If on of the following command groups are ev‐
1820 erything is OK.
1821 • gcc-5/g++-5/gcov-5
1823 • gcc-6/g++-6/gcov-6
1825 • gcc-8/g++-8/gcov-8
1827 • gcc-9/g++-9/gcov-9
1829 • gcc-10/g++-10/gcov-10
1831 • gcc-11/g++-11/gcov-11
1833 • clang-10/clang++-10/llvm-cov
1835 • clang-13/clang++-13/llvm-cov
1837 are available everything is OK. For gcc-6, gcc-8, gcc-9, gcc-10,
1839 gcc-11, clang-10 and clang-13 you should use the option CC=... see
1840 run and filter tests. If this isn't OK you can set the reference
1841 data to use by setting the environment CC_REFERENCE=gcc-8 or you have
1842 to create symlinks for the gcc executables with the following steps.
1843 You can check the GCC version with gcc --version. If the output says
1844 version 8, you should also be able to run gcc-8 --version. Your Linux
1845 distribution should have set all of this up already. If you don't
1846 have an alias like gcc-8, perform the following steps to create an
1847 alias for gcc, this should also work in the MSYS shell under Windows:
1848 1. Create a directory somewhere, e.g. in your home directory: mkdir
1850 ~/bin
1851 2. Create a symlink in that directory which points to GCC: ln -s
1853 $(which gcc) ~/bin/gcc-8
1854 3. Add this directory to your PATH: export PATH="$HOME/bin:$PATH"
1856 4. Re-test gcc-8 --version to ensure everything worked.
1858 5. Create additional symlinks for g++ -> g++-8 and gcov -> gcov-8.
1860 • (Optional) Fork the project on GitHub.
1862 • Clone the git repository.
1864 • (Optional) Set up a virtualenv (e.g. with python3 -m venv my-venv)
1866 • Install gcovr in development mode, and install nox:
1868 pip install -e .
1870 pip install nox
1871 You can then run gcovr as gcovr or python3 -m gcovr.
1873 Run the tests to verify that everything works (see Test suite).
1875 • (Optional) Activate GitHub Actions for your forked repository, so
1877 that the cross-platform compatibility tests get run whenever you push
1878 your work to your repository. These tests will also be run when you
1879 open a pull request to the main gcovr repository.
1880 Tip: If you have problems getting everything set up, consider looking
1882 at these files:
1883 • for Linux: .github/workflows/test.yml and admin/Dockerfile.qa
1885 • for Windows: .github/workflows/test.yml
1887 Project Structure
1889 ┌───────────────────┬────────────────────────────┐
1890 │Path │ Description │
1891 ├───────────────────┼────────────────────────────┤
1892 │/ │ project root │
1893 ├───────────────────┼────────────────────────────┤
1894 │/gcovr/ │ the gcovr source code │
1895 │ │ (Python module) │
1896 ├───────────────────┼────────────────────────────┤
1897 │/gcovr/__main__.py │ command line interface + │
1898 │ │ top-level behaviour │
1899 ├───────────────────┼────────────────────────────┤
1900 │/gcovr/templates/ │ HTML report templates │
1901 ├───────────────────┼────────────────────────────┤
1902 │/gcovr/tests/ │ unit tests + integration │
1903 │ │ test corpus │
1904 ├───────────────────┼────────────────────────────┤
1905 │/noxfile.py │ Definition of tests tasks │
1906 ├───────────────────┼────────────────────────────┤
1907 │/setup.py │ Python package configura‐ │
1908 │ │ tion │
1909 ├───────────────────┼────────────────────────────┤
1910 │/doc/ │ documentation │
1911 ├───────────────────┼────────────────────────────┤
1912 │/doc/sources/ │ user guide + website │
1913 ├───────────────────┼────────────────────────────┤
1914 │/doc/examples/ │ runnable examples for the │
1915 │ │ user guide │
1916 └───────────────────┴────────────────────────────┘
1917 The program entrypoint and command line interface is in
1919 gcovr/__main__.py. The coverage data is parsed in the gcovr.gcov mod‐
1920 ule. The HTML, XML, text, and summary reports are in gcovr.genera‐
1921 tor.html and respective modules.
1922 Test suite
1924 The QA process (python3 -m nox) consists of multiple parts:
1925 • linting and checking format(python3 -m nox --session lint)
1927 • tests (python3 -m nox --session tests)
1929 • unit tests in gcovr/tests
1931 • integration tests in gcovr/tests
1933 • documentation examples in doc/examples
1935 • documentation build (python3 -m nox --session doc)
1937 The tests are in the gcovr/tests directory. You can run the tests with
1939 python3 -m nox --session tests for the default GCC version (specified
1940 via CC environment variable, defaults to gcc-5). You can also select
1941 the gcc version if you run the tests with e.g. python3 -m nox --ses‐
1942 sion 'tests_compiler(gcc-8)'.
1943 There are unit tests for some parts of gcovr, and a comprehensive cor‐
1945 pus of example projects that are executed as the test_gcovr.py integra‐
1946 tion test. Each gcovr/tests/* directory is one such example project.
1947 You can format files with python3 -m nox --session black)
1949 To get a list of all available sessions run python3 -m nox -l.
1951 The next sections discuss the structure of integration tests, how to
1953 run and filter tests, and how to run tests with Docker.
1954 Changed in version 5.2: If black is called without arguments, all files
1956 are reformated instead of checked. To check the format use the session
1957 lint.
1958 Structure of integration tests
1961 Each project in the corpus contains a Makefile and a reference direc‐
1962 tory:
1963 gcovr/tests/sometest/
1965 reference/
1966 Makefile
1967 README
1968 example.cpp
1969 The Makefile controls how the project is built, and how gcovr should be
1971 invoked. The reference directory contains baseline files against which
1972 the gcovr output is compared. Tests can be executed even without base‐
1973 line files.
1974 Each Makefile contains the following targets:
1976 • all: builds the example project. Can be shared between gcovr invoca‐
1978 tions.
1979 • run: lists available targets which must be a subset of the available
1981 output formats.
1982 • clean: remove any generated files after all tests of the scenario
1984 have finished.
1985 • output formats (txt, html, json, sonarqube, ...): invoke gcovr to
1987 produce output files of the correct format. The test runner automat‐
1988 ically finds the generated files (if any) and compares them to the
1989 baseline files in the reference directory. All formats are optional,
1990 but using at least JSON is recommended.
1991 • clean-each: if provided, will be invoked by the test runner after
1993 testing each format.
1994 Run and filter tests
1996 To run all tests, use python3 -m nox. The tests currently assume that
1997 you are using GCC 5 and have set up a development environment. You can
1998 select a different GCC version by setting the CC environment variable.
1999 Supported versions are CC=gcc-5, CC=gcc-6, CC=gcc-8, CC=gcc-9, gcc-10,
2000 gcc-11, clang-10 and clang-13.
2001 You can run the tests with additional options by adding -- and then the
2003 options to the test invocation. Run all tests after each change is a
2004 bit slow, therefore you can limit the tests to a specific test file,
2005 example project, or output format. For example:
2006 # run only XML tests
2008 python3 -m nox --session tests -- -k 'xml'
2009 # run the simple1 tests
2011 python3 -m nox --session tests -- -k 'simple1'
2012 # run the simple1 tests only for XML
2014 python3 -m nox --session tests -- -k 'xml and simple1'
2015 To see which tests would be run, add the --collect-only option:
2017 #see which tests would be run
2019 python3 -m nox --session tests -- --collect-only
2020 Sometimes during development you need to create reference files for new
2022 test or update the current reference files. To do this you have to add
2023 --generate_reference or --update-reference option to the test invoca‐
2024 tion. By default generated output files are automatically removed af‐
2025 ter test run. To skip this process you can add --skip_clean option the
2026 test invocation. For example:
2027 # run tests and generate references for simple1 example
2029 python3 -m nox --session tests -- -k 'simple1' --generate_reference
2030 # run tests and update xml references for simple1 example
2032 python3 -m nox --session tests -- -k 'xml and simple1' --update_reference
2033 # run only XML tests and do not remove generated files
2035 python3 -m nox --session tests -- -k 'xml' --skip_clean
2036 To update the refernce data for all compiler in one call see run tests
2038 with Docker.
2039 When the currently generated output reports differ to the reference
2041 files you can create a ZIP archive named diff.zip in the tests direc‐
2042 tory by using --archive_differences option. Currently in gcovr it is
2043 used by GitHub CI to create a ZIP file with the differences as an arti‐
2044 fact.
2045 # run tests and generate a ZIP archive when there were differences
2047 python3 -m nox --session tests -- --archive_differences
2048 Changed in version 5.1: Change how to start test from make test to
2050 python3 -m nox --session tests
2051 New in version 5.0: Added test options --generate_reference, --up‐
2054 date_reference, --skip_clean, '--archive_differences' and changed way
2055 to call tests only by make test.
2056 Run tests with Docker
2059 If you can't set up a toolchain locally, you can run the QA process via
2060 Docker. First, build the container image:
2061 python3 -m nox --session docker_qa_build
2063 Then, run the container, which executes python3 -m nox within the con‐
2065 tainer:
2066 python3 -m nox --session docker_qa_run
2068 Or to build and run the container in one step:
2070 python3 -m nox --session docker_qa
2072 You can select the gcc version to use inside the docker by setting the
2074 environment variable CC to gcc-5 (default), gcc-6, gcc-8, gcc-9,
2075 gcc-10, gcc-11, clang-10 or clang-13 or you can build and run the con‐
2076 tainer with:
2077 python3 -m nox --session 'docker_qa_compiler(gcc-9)'
2079 You can also use the compiler 'all' to run the tests for all compiler
2081 versions. This is usefull to update the all reference files:
2082 python3 -m nox --session 'docker_qa_compiler(all)' -- --update_reference
2084 Become a gcovr developer
2086 After you've contributed a bit (whether with discussions, documenta‐
2087 tion, or code), consider becoming a gcovr developer. As a developer,
2088 you can:
2089 • manage issues and pull requests (label and close them)
2091 • review pull requests (a developer must approve each PR before it can
2093 be merged)
2094 • participate in votes
2096 Just open an issue that you're interested, and we'll have a quick vote.
2098
2100 gcovr Release History and Change Log
2101 5.2 (06 August 2022)
2103 Known bugs:
2104 Breaking changes:
2106 New features and notable changes:
2108 • Log additional info on gcov parsing errors. (#589)
2110 • Add support for branch exclude markers. (#644)
2112 • Additional options to configure the thresholds for lines and branches
2114 in HTML separate. (#645)
2115 Bug fixes and small improvements:
2117 • Remove function coverage from sonarcube report. (#591)
2119 • Fix parallel processing of gcov data. (#592)
2121 • Better diagnostics when dealing with corrupted input files. (#593)
2123 • Accept metadata lines without values (introduced in gcc-11). (#601)
2125 • Properly close <a> element in detailed HTML report. (#602)
2127 • Use ≥ sign instead of >= in HTML legend. (#603)
2129 • Using --add-tracefile will now correctly merge branch coverage. (‐
2131 #600)
2132 • Fix package-level function coverage statistics in Cobertura XML re‐
2134 ports. (#605)
2135 • Respect excluded/noncode lines for aggregated branchcoverage. (#611)
2137 • Fix list options in configuration file (search-path). (#612)
2139 • Fix assert and key error in --decisions flag. (#642)
2141 • Fix adding none existing lines by decision analysis to data model. (‐
2143 #617)
2144 • Always treat relative paths in config files as relative to the direc‐
2146 tory of the file. (#615)
2147 • More flexible .gcov parsing to support files generated by third party
2149 tools. (#621, #623)
2150 Documentation:
2152 Internal changes:
2154 • Fix black check to fail on format errors. (#594)
2156 • Change session black with no arguments to format all files. (#595)
2158 • Add gcc-10 and gcc-11 to the test suite. (#597)
2160 • Improved internal coverage data model to simplify processing. (#600)
2162 • Use pretty print for cobertura and coveralls in test suite. (#606)
2164 • Forward nox options --reuse-existing-virtualenvs and --no-install to
2166 call inside docker. (#616)
2167 5.1 (26 March 2022)
2169 Breaking changes:
2170 • Dropped support for Python 3.6 (#550)
2172 • Changed xml configuration key to cobertura (#552)
2174 • JSON summary output: all percentages are now reported from 0 to 100
2176 (#570)
2177 New features and notable changes:
2179 • Report function coverage (#362, #515, #554)
2181 • Consistent support for symlinks across operating systems
2183 • Support for Windows junctions (#535)
2185 • Symlinks are only resolved for evaluating filters (#565)
2187 • Show error message on STDERR when --fail-under-line or
2189 --fail-under-branch fails (#502)
2190 • Can report decision coverage with --decisions option (reasonably for‐
2192 matted C/C++ source files only, HTML and JSON output) (#350)
2193 • Can create reproducible reports with the --timestamp option (#546)
2195 • Improvements to Exclusion Markers (LINE/START/STOP)
2197 • Can ignore markers in code with --no-markers option (#361)
2199 • Can customize patterns with --exclude-pattern-prefix option (#561)
2201 • Can use --cobertura as a less ambiguous alias for --xml. (#552)
2203 Bug fixes and small improvements:
2205 • Gcov is invoked without localization by setting LC_ALL=C (#513)
2207 • Gcov is invoked without temporary directories (#525)
2209 • Gcov: solved problems with file name limitations. (#528)
2211 • Fixed "root" path in JSON summary report. (#548)
2213 • Correctly resolve relative filters in configuration files. (#568)
2215 • HTML output: indicate lines with excluded coverage (#503)
2217 • HTML output: fixed sanity check to support empty files (#571)
2219 • HTML output: support jinja2 >= 3.1 (#576)
2221 Documentation:
2223 • Split documentation into smaller pages (#552)
2225 • Document used options for gcov (#528)
2227 Internal changes:
2229 • Replaced own logger with Python's logging module. (#540)
2231 • New parser for .gcov file format, should be more robust. (#512)
2233 • New tests
2235 • more compilers: clang-10 (#484), clang-13 (#527), gcc-9 (#527)
2237 • -fprofile-abs-path compiler option (#521)
2239 • enabled symlink tests for Windows (#539)
2241 • Improvements to the test suite
2243 • Use Nox instead of Makefiles to manage QA checks (#516, #555)
2245 • Can run tests for all compiler versions in one go (#514)
2247 • More linter checks (#566) and code style enforcement with black (‐
2249 #579)
2250 • Better XML diffing with yaxmldiff (#495, #509)
2252 • Share test reference data between compiler versions where possible
2254 (#556)
2255 • Better environment variable handling (#493, #541)
2257 • Fixed glob patterns for collecting reference files (#533)
2259 • Add timeout for each single test. (#572)
2261 • Improvements and fixes to the release process (#494, #537)
2263 • Normalize shell scripts to Unix line endings (#538, #547)
2265 5.0 (11 June 2021)
2267 Breaking changes:
2268 • Dropped support for Python 2 and Python 3.5. From now on, gcovr will
2270 only support Python versions that enjoy upstream support.
2271 Improvements and new features:
2273 • Handles spaces in gcov path. (#385)
2275 • Early fail when output cannot be created. (#382)
2277 • Add --txt for text output. (#387)
2279 • Add --csv for CSV output. (#376)
2281 • Add --exclude-lines-by-pattern to filter out source lines by arbi‐
2283 trary regex. (#356)
2284 • Add --json-summary to generate a JSON Summary report. (#366)
2286 • Add --coveralls to generate a Coveralls compatible JSON report. (‐
2288 #328)
2289 • Add support for output directories. If the output ends with a / or \
2291 it is used as a directory. (#416)
2292 • Compare paths case insensitive if file system of working directory is
2294 case insensitive. (#329)
2295 • Add wildcard pattern to json --add-tracefile. (#351)
2297 • Enable --filter and --exclude for Merging coverage. (#373)
2299 • Only output 100.0% in text and HTML output if really 100.0%, else use
2301 99.9%. (#389)
2302 • Support relative source location for shadow builds. (#410)
2304 • Incorrect path for header now can still generate html-details reports
2306 (#271)
2307 • Change format version in JSON output from number to string and update
2309 it to "0.2". (#418, #463)
2310 • Only remove --root path at the start of file paths. (#452)
2312 • Fix coverage report for cmake ninja builds with given in-source ob‐
2314 ject-directory. (#453)
2315 • Add issue templates. (#461)
2317 • Add --exclude-function-lines to exclude the line of the function def‐
2319 inition in the coverage report. (#430)
2320 • Changes for HTML output format:
2322 • Redesign HTML generation. Add --html-self-contained to control ex‐
2324 ternal or internal CSS. (#367)
2325 • Change legend for threshold in html report. (#371)
2327 • Use HTML title also for report heading. Default value for
2329 --html-title changed. (#378)
2330 • Add --html-tab-size to configure tab size in HTML details. (#377)
2332 • Add option --html-css for user defined styling. (#380)
2334 • Create details html filename independent from OS. (#375)
2336 • Add --html-theme to change the color theme. (#393)
2338 • Add linkable lines in HTML details. (#401)
2340 • Add syntax highlighting in the details HTML report. This can be
2342 turned off with --no-html-details-syntax-highlighting. (#402, #415)
2343 Documentation:
2345 • Cookbook: Out-of-Source Builds with CMake (#340, #341)
2347 Internal changes:
2349 • Add makefile + dockerfile for simpler testing.
2351 • Add .gitbugtraq to link comments to issue tracker in GUIs. (#429)
2353 • Add GitHub actions to test PRs and master branch. (#404)
2355 • Remove Travis CI. (#419)
2357 • Remove Appveyor CI and upload coverage report from Windows and Ubuntu
2359 from the GitHub actions. (#455)
2360 • Add check if commit is mentioned in the CHANGELOG.rst. (#457)
2362 • Move flake8 config to setup.cfg and add black code formatter. (#444)
2364 • Fix filter/exclude relative path issue in Windows. (#320, #479)
2366 • Extend test framework for CI:
2368 • Set make variable TEST_OPTS as environment variable inside docker.
2370 (#372)
2371 • Add make variable USE_COVERAGE to extend flags for coverage report
2373 in GitHub actions. (#404)
2374 • Extend tests to use an unified diff in the assert. Add test options
2376 --generate_reference, --update_reference and --skip_clean. (#379)
2377 • Support multiple output patterns in integration tests. (#383)
2379 • New option --archive_differences to save the different files as
2381 ZIP. Use this ZIP as artifact in AppVeyor. (#392)
2382 • Add support for gcc-8 to test suite and docker tests. (#423)
2384 • Run as limited user inside docker container and add test with read
2386 only directory. (#445)
2387 4.2 (6 November 2019)
2389 Breaking changes:
2390 • Dropped support for Python 3.4.
2392 • Format flag parameters like --xml or --html now take an optional out‐
2394 put file name. This potentially changes the interpretation of search
2395 paths. In gcovr --xml foo, previous gcovr versions would search the
2396 foo directory for coverage data. Now, gcovr will try to write the
2397 Cobertura report to the foo file. To keep the old meaning, separate
2398 positional arguments like gcovr --xml -- foo.
2399 Improvements and new features:
2401 • Configuration file support (experimental). (#167, #229, #279, #281,
2403 #293, #300, #304)
2404 • JSON output. (#301, #321, #326)
2406 • Merging coverage with gcovr --add-tracefile. (#10, #326)
2408 • SonarQube XML Output. (#308)
2410 • Handle cyclic symlinks correctly during coverage data search. (#284)
2412 • Simplification of --object-directory heuristics. (#18, #273, #280)
2414 • Exception-only code like a catch clause is now shown as uncovered.
2416 (#283)
2417 • New --exclude-throw-branches option to exclude exception handler
2419 branches. (#283)
2420 • Support --root .. style invocation, which might fix some CMake-re‐
2422 lated problems. (#294)
2423 • Fix wrong names in report when source and build directories have sim‐
2425 ilar names. (#299)
2426 • Stricter argument handling. (#267)
2428 • Reduce XML memory usage by moving to lxml. (#1, #118, #307)
2430 • Can write multiple reports at the same time by giving the output file
2432 name to the report format parameter. Now, gcovr --html -o cov.html
2433 and gcovr --html cov.html are equivalent. (#291)
2434 • Override gcov locale properly. (#334)
2436 • Make gcov parser more robust when used with GCC 8. (#315)
2438 Known issues:
2440 • The --keep option only works when using existing gcov files with -g/‐
2442 --use-gcov-files. (#285, #286)
2443 • Gcovr may get confused when header files in different directories
2445 have the same name. (#271)
2446 • Gcovr may not work when no en_US locale is available. (#166)
2448 Documentation:
2450 • Exclusion marker documentation.
2452 • FAQ: Why does C++ code have so many uncovered branches? (#283)
2454 • FAQ: Why are uncovered files not reported? (#33, #100, #154, #290,
2456 #298)
2457 Internal changes:
2459 • More tests. (#269, #268, #269)
2461 • Refactoring and removal of dead code. (#280)
2463 • New internal data model.
2465 4.1 (2 July 2018)
2467 • Fixed/improved --exclude-directories option. (#266)
2468 • New "Cookbook" section in the documentation. (#265)
2470 4.0 (17 June 2018)
2472 Breaking changes:
2473 • This release drops support for Python 2.6. (#250)
2475 • PIP is the only supported installation method.
2477 • No longer encoding-agnostic under Python 2.7. If your source files
2479 do not use the system encoding (probably UTF-8), you will have to
2480 specify a --source-encoding. (#148, #156, #256)
2481 • Filters now use forward slashes as path separators, even on Windows.
2483 (#191, #257)
2484 • Filters are no longer normalized into pseudo-paths. This could
2486 change the interpretation of filters in some edge cases.
2487 Improvements and new features:
2489 • Improved --help output. (#236)
2491 • Parse the GCC 8 gcov format. (#226, #228)
2493 • New --source-encoding option, which fixes decoding under Python 3.
2495 (#256)
2496 • New --gcov-ignore-parse-errors flag. By default, gcovr will now
2498 abort upon parse errors. (#228)
2499 • Detect the error when gcov cannot create its output files (#243,
2501 #244)
2502 • Add -j flag to run gcov processes in parallel. (#3, #36, #239)
2504 • The --html-details flag now implies --html. (#93, #211)
2506 • The --html output can now be used without an --output filename (#223)
2508 • The docs are now managed with Sphinx. (#235, #248, #249, #252, #253)
2510 • New --html-title option to change the title of the HTML report. (‐
2512 #261, #263)
2513 • New options --html-medium-threshold and --html-high-threshold to cus‐
2515 tomize the color legend. (#261, #264)
2516 Internal changes:
2518 • Huge refactoring. (#214, #215, #221 #225, #228, #237, #246)
2520 • Various testing improvements. (#213, #214, #216, #217, #218, #222,
2522 #223, #224, #227, #240, #241, #245)
2523 • HTML reports are now rendered with Jinja2 templates. (#234)
2525 • New contributing guide. (#253)
2527 3.4 (12 February 2018)
2529 • Added --html-encoding command line option (#139).
2530 • Added --fail-under-line and --fail-under-branch options, which will
2532 error under a given minimum coverage. (#173, #116)
2533 • Better pathname resolution heuristics for --use-gcov-file. (#146)
2535 • The --root option defaults to current directory '.'.
2537 • Improved reports for "(", ")", ";" lines.
2539 • HTML reports show full timestamp, not just date. (#165)
2541 • HTML reports treat 0/0 coverage as NaN, not 100% or 0%. (#105, #149,
2543 #196)
2544 • Add support for coverage-04.dtd Cobertura XML format (#164, #186)
2546 • Only Python 2.6+ is supported, with 2.7+ or 3.4+ recommended. (#195)
2548 • Added CI testing for Windows using Appveyor. (#189, #200)
2550 • Reports use forward slashes in paths, even on Windows. (#200)
2552 • Fix to support filtering with absolute paths.
2554 • Fix HTML generation with Python 3. (#168, #182, #163)
2556 • Fix --html-details under Windows. (#157)
2558 • Fix filters under Windows. (#158)
2560 • Fix verbose output when using existing gcov files (#143, #144)
2562 3.3 (6 August 2016)
2564 • Added CI testing using TravisCI
2565 • Added more tests for out of source builds and other nested builds
2567 • Avoid common file prefixes in HTML output (#103)
2569 • Added the --execlude-directories argument to exclude directories from
2571 the search for symlinks (#87)
2572 • Added branches taken/not taken to HTML (#75)
2574 • Use --object-directory to scan for gcov data files (#72)
2576 • Improved logic for nested makefiles (#135)
2578 • Fixed unexpected semantics with --root argument (#108)
2580 • More careful checks for covered lines (#109)
2582 3.2 (5 July 2014)
2584 • Adding a test for out of source builds
2585 • Using the starting directory when processing gcov filenames. (#42)
2587 • Making relative paths the default in html output.
2589 • Simplify html bar with coverage is zero.
2591 • Add option for using existing gcov files (#35)
2593 • Fixing --root argument processing (#27)
2595 • Adding logic to cover branches that are ignored (#28)
2597 3.1 (6 December 2013)
2599 • Change to make the -r/--root options define the root directory for
2600 source files.
2601 • Fix to apply the -p option when the --html option is used.
2603 • Adding new option, '--exclude-unreachable-branches' that will exclude
2605 branches in certain lines from coverage report.
2606 • Simplifying and standardizing the processing of linked files.
2608 • Adding tests for deeply nested code, and symbolic links.
2610 • Add support for multiple —filter options in same manner as —exclude
2612 option.
2613 3.0 (10 August 2013)
2615 • Adding the '--gcov-executable' option to specify the name/location of
2616 the gcov executable. The command line option overrides the environ‐
2617 ment variable, which overrides the default 'gcov'.
2618 • Adding an empty "<methods/>" block to <classes/> in the XML output:
2620 this makes out XML complient with the Cobertura DTD. (#3951)
2621 • Allow the GCOV environment variable to override the default 'gcov'
2623 executable. The default is to search the PATH for 'gcov' if the GCOV
2624 environment variable is not set. (#3950)
2625 • Adding support for LCOV-style flags for excluding certain lines from
2627 coverage analysis. (#3942)
2628 • Setup additional logic to test with Python 2.5.
2630 • Added the --html and --html-details options to generate HTML.
2632 • Sort output for XML to facilitate baseline tests.
2634 • Added error when the --object-directory option specifies a bad direc‐
2636 tory.
2637 • Added more flexible XML testing, which can ignore XML elements that
2639 frequently change (e.g. timestamps).
2640 • Added the '—xml-pretty' option, which is used to generate pretty XML
2642 output for the user manual.
2643 • Many documentation updates
2645 2.4 (13 April 2012)
2647 • New approach to walking the directory tree that is more robust to
2648 symbolic links (#3908)
2649 • Normalize all reported path names
2651 • Normalize using the full absolute path (#3921)
2653 • Attempt to resolve files referenced through symlinks to a common
2655 project-relative path
2656 • Process gcno files when there is no corresponding gcda file to pro‐
2658 vide coverage information for unexecuted modules (#3887)
2659 • Windows compatibility fixes
2661 • Fix for how we parse source: file names (#3913)
2663 • Better handling od EOL indicators (#3920)
2665 • Fix so that gcovr cleans up all .gcov files, even those filtered by
2667 command line arguments
2668 • Added compatibility with GCC 4.8 (#3918)
2670 • Added a check to warn users who specify an empty --root option (see
2672 #3917)
2673 • Force gcov to run with en_US localization, so the gcovr parser runs
2675 correctly on systems with non-English locales (#3898, #3902).
2676 • Segregate warning/error information onto the stderr stream (#3924)
2678 • Miscellaneous (Python 3.x) portability fixes
2680 • Added the master svn revision number as part of the verson identifier
2682 2.3.1 (6 January 2012)
2684 • Adding support for Python 3.x
2685 2.3 (11 December 2011)
2687 • Adding the --gcov-filter and --gcov-exclude options.
2688 2.2 (10 December 2011)
2690 • Added a test driver for gcovr.
2691 • Improved estimation of the <sources> element when using gcovr with
2693 filters.
2694 • Added revision and date keywords to gcovr so it is easier to identify
2696 what version of the script users are using (especially when they are
2697 running a snapshot from trunk).
2698 • Addressed special case mentioned in [comment:ticket:3884:1]: do not
2700 truncate the reported file name if the filter does not start matching
2701 at the beginning of the string.
2702 • Overhaul of the --root / --filter logic. This should resolve the is‐
2704 sue raised in #3884, along with the more general filter issue raised
2705 in [comment:ticket:3884:1]
2706 • Overhaul of gcovr's logic for determining gcc/g++'s original working
2708 directory. This resolves issues introduced in the original implemen‐
2709 tation of --object-directory (#3872, #3883).
2710 • Bugfix: gcovr was only including a <sources> element in the XML re‐
2712 port if the user specified -r (#3869)
2713 • Adding timestamp and version attributes to the gcovr XML report (see
2715 #3877). It looks like the standard Cobertura output reports number
2716 of seconds since the epoch for the timestamp and a doted decimal ver‐
2717 sion string. Now, gcovr reports seconds since the epoch and "gcovr
2718 ``"+``__version__ (e.g. "gcovr 2.2") to differentiate it from a pure
2719 Cobertura report.
2720 2.1 (26 November 2010)
2722 • Added the --object-directory option, which allows for a flexible
2723 specification of the directory that contains the objects generated by
2724 gcov.
2725 • Adding fix to compare the absolute path of a filename to an exclusion
2727 pattern.
2728 • Adding error checking when no coverage results are found. The line
2730 and branch counts can be zero.
2731 • Adding logic to process the -o/--output option (#3870).
2733 • Adding patch to scan for lines that look like:
2735 creating `foo'
2737 as well as
2739 creating 'foo'
2741 • Changing the semantics for EOL to be portable for MS Windows.
2743 • Add attributes to xml format so that it could be used by hudson/bam‐
2745 boo with cobertura plug-in.
2746 2.0 (22 August 2010)
2748 • Initial release as a separate package. Earlier versions of gcovr
2749 were managed within the 'fast' Python package.
2750
2752 Copyright (c) 2013-2022 the gcovr authors Copyright (c) 2013 Sandia
2753 Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia
2754 Corporation, the U.S. Government retains certain rights in this soft‐
2755 ware.
2756 This software is distributed under the 3-clause BSD License. See LI‐
2758 CENSE.txt for full details. See AUTHORS.txt for the full list of con‐
2759 tributors.
2760 Gcovr development moved to this repository in September, 2013 from San‐
2762 dia National Laboratories.
2763 License Terms
2765 Gcovr is available under the terms of a BSD-3-clause license:
2766 Copyright (c) 2013-2022 the gcovr authors
2768 Copyright (c) 2013 Sandia Corporation.
2769 Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
2770 the U.S. Government retains certain rights in this software.
2771 All rights reserved.
2773 Redistribution and use in source and binary forms, with or without
2775 modification, are permitted provided that the following conditions
2776 are met:
2777 * Redistributions of source code must retain the above copyright notice,
2779 this list of conditions and the following disclaimer.
2780 * Redistributions in binary form must reproduce the above copyright
2782 notice, this list of conditions and the following disclaimer in the
2783 documentation and/or other materials provided with the distribution.
2784 * Neither the name of the Sandia National Laboratories nor the names of
2786 its contributors may be used to endorse or promote products derived from
2787 this software without specific prior written permission.
2788 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
2790 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2791 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
2792 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
2793 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
2794 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
2795 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
2796 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
2797 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
2798 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
2799 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2800 Acknowledgements
2803 Gcovr is maintained by:
2804 Lukas Atkinson and Michael Förderer.
2805 The following developers contributed to gcovr (ordered alphabetically):
2807 alex43dm, Andrew Stone, Antonio Quarta, Arvin Schnell, Attie Grande,
2808 Bernhard Breinbauer, Carlos Jenkins, Cary Converse, Cezary Gapiński,
2809 Christian Taedcke, Dave George, Davide Pesavento, Dom Postorivo,
2810 ebmmy, Elektrobit Automotive GmbH, Ensky Lin, Glenn Töws, Grégoire
2811 Roussel, goriy, Irfan Adilovic, ja11sop, James Reynolds, Jeremy Fix‐
2812 emer, Jessica Levine, Joachim Kuebart, Joel Klinghed, Johan
2813 Bertrand, John Siirola, Jörg Kreuzberger, Jordi Sabater, Kai
2814 Blaschke, Kevin Broselge, Kevin Cai, Klaus Weinbauer, Leon Ma,
2815 libPhipp, Lukas Atkinson, Luke Woydziak, Marek Kurdej, Martin Mraz,
2816 Matsumoto Taichi, Matthew Stadelman, Matthias Schmieder, Matthieu
2817 Darbois, Matthieu Eyraud, Michael Förderer, Michał Pszona, Mikael
2818 Salson, Mikk Leini, Nikolaj Schumacher, Oleksiy Pikalo, Phil
2819 Clapham, Piotr Dziwinski, Reto Schneider, Richard Kjerstadius,
2820 Robert Rosengren, Songmin Li, Steven Myint, Sylvestre Ledru,
2821 Thibault Gasc, Tilo Wiedera, trapzero, Will Thompson, William Hart,
2822 Zachary J. Fields, Zachary P. Hensley, and possibly others.
2823 The development of Gcovr has been partially supported by Sandia Na‐
2825 tional Laboratories. Sandia National Laboratories is a multi-program
2826 laboratory managed and operated by Sandia Corporation, a wholly owned
2827 subsidiary of Lockheed Martin Corporation, for the U.S. Department of
2828 Energy's National Nuclear Security Administration under contract
2829 DE-AC04-94AL85000.
2830
2832 the gcovr authors
2833
2835 2023, the gcovr authors
28365.2 Jan 21, 2023 GCOVR(1)