1GCOVR(1)                             gcovr                            GCOVR(1)
2
3
4

NAME

6       gcovr - gcovr Documentation
7
8       Gcovr  provides  a utility for managing the use of the GNU gcov utility
9       and generating summarized code coverage results. This  command  is  in‐
10       spired  by  the  Python  coverage.py  package, which provides a similar
11       utility for Python.
12
13       The gcovr command can produce different kinds of coverage reports:
14
15       • default or --txt: compact human-readable summaries
16
17--html: HTML summaries
18
19--html-details: HTML report with annotated source files
20
21-x/--xml: machine readable XML reports in Cobertura format
22
23--sonarqube: machine readable XML reports in Sonarqube format
24
25--json: JSON report with source files structure and coverage
26
27--json-summary: JSON summary coverage report
28
29--csv: CSV report summarizing the coverage of each file
30
31--coveralls: machine readable JSON reports in Coveralls format
32
33       Thus, gcovr can be viewed as a command-line  alternative  to  the  lcov
34       utility,  which  runs gcov and generates an HTML-formatted report.  The
35       development of gcovr was motivated by the need for text  summaries  and
36       XML reports.
37
38          Quick Links
39
40          • Getting Help
41
42Submit a ticket
43
44Stack Overflow
45
46Chat on Gitter
47
48          • Install from PyPI: pip install gcovr
49
50Source Code on GitHub
51
52          • changelog
53

INSTALLATION

55       Gcovr is available as a Python package that can be installed via pip.
56
57       Install newest stable gcovr release from PyPI:
58
59          pip install gcovr
60
61       Install development version from GitHub:
62
63          pip install git+https://github.com/gcovr/gcovr.git
64
65       Which environments does gcovr support?
66
67       Python:
68              3.6+.
69
70              The  automated tests run on CPython (versions 3.6, 3.7, 3.8) and
71              a compatible PyPy3.  Gcovr will only run on Python versions with
72              upstream support.
73
74              Last gcovr release for old Python versions:
75
76                                      ┌───────┬───────┐
77                                      │Python │ gcovr │
78                                      ├───────┼───────┤
79                                      │2.6    │ 3.4   │
80                                      ├───────┼───────┤
81                                      │2.7    │ 4.2   │
82                                      ├───────┼───────┤
83                                      │3.4    │ 4.1   │
84                                      ├───────┼───────┤
85                                      │3.5    │ 4.2   │
86                                      └───────┴───────┘
87
88       Operating System:
89              Linux, Windows, and macOS.
90
91              The  automated  tests  run on Ubuntu 18.04 and 20.04 and Windows
92              Server 2019.
93
94       Compiler:
95              GCC and Clang.
96
97              The automated tests run on GCC 5, 6, and 8.
98

GCOVR USER GUIDE

100       Gcovr provides a utility for managing the use of the GNU  gcov  utility
101       and  generating  summarized  code coverage results. This command is in‐
102       spired by the Python coverage.py  package,  which  provides  a  similar
103       utility for Python.
104
105       The gcovr command can produce different kinds of coverage reports:
106
107       • default or --txt: compact human-readable summaries
108
109--html: HTML summaries
110
111--html-details: HTML report with annotated source files
112
113-x/--xml: machine readable XML reports in Cobertura format
114
115--sonarqube: machine readable XML reports in Sonarqube format
116
117--json: JSON report with source files structure and coverage
118
119--json-summary: JSON summary coverage report
120
121--csv: CSV report summarizing the coverage of each file
122
123--coveralls: machine readable JSON reports in Coveralls format
124
125       Thus,  gcovr  can  be  viewed as a command-line alternative to the lcov
126       utility, which runs gcov and generates an HTML-formatted  report.   The
127       development  of  gcovr was motivated by the need for text summaries and
128       XML reports.
129
130       The Gcovr Home Page is http://gcovr.com.  Automated  test  results  are
131       available  through  GitHub  Actions <https://github.com/gcovr/gcovr/ac
132       tions?query=branch:master>.  Gcovr is available under the BSD license.
133
134       This documentation describes Gcovr 5.0.
135
136       This User Guide provides the following sections:
137
138Getting Started
139
140Tabular Output of Code Coverage
141
142Tabular Output of Branch Coverage
143
144Cobertura XML Output
145
146HTML Output
147
148Sonarqube XML Output
149
150JSON Output
151
152JSON Summary Output
153
154CSV Output
155
156Coveralls JSON Output
157
158Multiple Output Formats
159
160Combining Tracefiles
161
162The gcovr Command
163
164gcovr
165
166Using Filters
167
168Speeding up coverage data search
169
170Filters for symlinks
171
172Configuration Files
173
174Exclusion Markers
175
176Acknowledgements
177
178       Related documents:
179
180       • installation
181
182       • contributing (includes instructions for bug reports)
183
184       • cookbook
185
186       • faq
187
188       • changelog
189
190       • license
191
192   Getting Started
193       The gcovr command provides a summary of the lines that have  been  exe‐
194       cuted  in  a  program.   Code  coverage  statistics  help  you discover
195       untested parts of a program, which is particularly important  when  as‐
196       sessing  code  quality.   Well-tested  code is a characteristic of high
197       quality code, and software developers often assess code  coverage  sta‐
198       tistics when deciding if software is ready for a release.
199
200       The  gcovr  command  can be used to analyze programs compiled with GCC.
201       The following sections illustrate the application of gcovr to test cov‐
202       erage of the following program:
203
204           1 // example.cpp
205           2
206           3 int foo(int param)
207           4 {
208           5     if (param)
209           6     {
210           7         return 1;
211           8     }
212           9     else
213          10     {
214          11         return 0;
215          12     }
216          13 }
217          14
218          15 int main(int argc, char* argv[])
219          16 {
220          17     foo(0);
221          18
222          19     return 0;
223          20 }
224
225       This  code executes several subroutines in this program, but some lines
226       in the program are not executed.
227
228   Tabular Output of Code Coverage
229       We compile example1.cpp with the GCC compiler as follows:
230
231          g++ -fprofile-arcs -ftest-coverage -fPIC -O0 example.cpp -o program
232
233       (If you are using CMake, also see oos cmake.)
234
235       Note that we compile this program without optimization,  because  opti‐
236       mization may combine lines of code and otherwise change the flow of ex‐
237       ecution in the program.   Additionally,  we  compile  with  the  -fpro‐
238       file-arcs  -ftest-coverage  -fPIC  compiler options, which add logic to
239       generate output files that can be processed by the gcov command.
240
241       The compiler generates the program executable.  When  we  execute  this
242       command:
243
244          ./program
245
246       the  files  example1.gcno and example1.gcda are generated.  These files
247       are processed by gcov to generate code coverage statistics.  The  gcovr
248       command  calls  gcov  and  summarizes these code coverage statistics in
249       various formats.  For example:
250
251          gcovr -r .
252
253       generates a text summary of the lines executed:
254
255          ------------------------------------------------------------------------------
256                                     GCC Code Coverage Report
257          Directory: .
258          ------------------------------------------------------------------------------
259          File                                       Lines    Exec  Cover   Missing
260          ------------------------------------------------------------------------------
261          example.cpp                                    7       6    85%   7
262          ------------------------------------------------------------------------------
263          TOTAL                                          7       6    85%
264          ------------------------------------------------------------------------------
265
266
267       The same result can be achieved when explicit --txt option is set.  For
268       example:
269
270          gcovr -r . --txt
271
272       generates the same text summary.
273
274       Each  line  of  this output includes a summary for a given source file,
275       including the number of lines instrumented, the number  of  lines  exe‐
276       cuted, the percentage of lines executed, and a summary of the line num‐
277       bers that were not executed.  To improve clarity, gcovr uses an aggres‐
278       sive  approach  to  grouping uncovered lines and will combine uncovered
279       lines separated by "non-code" lines (blank,  freestanding  braces,  and
280       single-line comments) into a single region.  As a result, the number of
281       lines listed in the "Missing" list may be greater than  the  difference
282       of the "Lines" and "Exec" columns.
283
284       The  -r/--root  option  specifies the root directory for the files that
285       are being analyzed.  This allows gcovr to  generate  a  simpler  report
286       (without  absolute path names), and it allows system header files to be
287       excluded from the analysis.
288
289       Note that gcov accumulates statistics by line.  Consequently, it  works
290       best  with  a  programming style that places only one statement on each
291       line.
292
293   Tabular Output of Branch Coverage
294       The  gcovr  command  can  also  summarize  branch  coverage  using  the
295       -b/--branches option:
296
297          gcovr -r . --branches
298
299       This generates a tabular output that summarizes the number of branches,
300       the number of branches taken and the branches that were not  completely
301       covered:
302
303          ------------------------------------------------------------------------------
304                                     GCC Code Coverage Report
305          Directory: .
306          ------------------------------------------------------------------------------
307          File                                    Branches   Taken  Cover   Missing
308          ------------------------------------------------------------------------------
309          example.cpp                                    2       1    50%   5
310          ------------------------------------------------------------------------------
311          TOTAL                                          2       1    50%
312          ------------------------------------------------------------------------------
313
314
315       The  same result can be achieved when explicit --txt option is set. For
316       example:
317
318          gcovr -r . --branches --txt
319
320       print the same tabular output.
321
322       New in version 5.0: Added --txt.
323
324
325   Cobertura XML Output
326       The default output format for gcovr is to generate a tabular summary in
327       plain  text.   The  gcovr command can also generate an XML output using
328       the -x/--xml and --xml-pretty options:
329
330          gcovr -r . --xml-pretty
331
332       This generates an XML summary of the lines executed:
333
334          <?xml version='1.0' encoding='UTF-8'?>
335          <!DOCTYPE coverage SYSTEM 'http://cobertura.sourceforge.net/xml/coverage-04.dtd'>
336          <coverage line-rate="0.8571428571428571" branch-rate="0.5" lines-covered="6" lines-valid="7" branches-covered="1" branches-valid="2" complexity="0.0" timestamp="1573053861" version="gcovr 5.0">
337            <sources>
338              <source>.</source>
339            </sources>
340            <packages>
341              <package name="" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
342                <classes>
343                  <class name="example_cpp" filename="example.cpp" line-rate="0.8571428571428571" branch-rate="0.5" complexity="0.0">
344                    <methods/>
345                    <lines>
346                      <line number="3" hits="1" branch="false"/>
347                      <line number="5" hits="1" branch="true" condition-coverage="50% (1/2)">
348                        <conditions>
349                          <condition number="0" type="jump" coverage="50%"/>
350                        </conditions>
351                      </line>
352                      <line number="7" hits="0" branch="false"/>
353                      <line number="11" hits="1" branch="false"/>
354                      <line number="15" hits="1" branch="false"/>
355                      <line number="17" hits="1" branch="false"/>
356                      <line number="19" hits="1" branch="false"/>
357                    </lines>
358                  </class>
359                </classes>
360              </package>
361            </packages>
362          </coverage>
363
364       This XML format is in the Cobertura XML format suitable for import  and
365       display  within  the  Jenkins and Hudson continuous integration servers
366       using the Cobertura Plugin.  Gcovr also supports a Sonarqube XML Output
367
368       The -x/--xml option generates a denser XML output, and the --xml-pretty
369       option  generates  an  indented XML output that is easier to read. Note
370       that the XML output contains more information than the tabular summary.
371       The  tabular  summary  shows the percentage of covered lines, while the
372       XML output includes branch statistics and the number of times that each
373       line was covered.  Consequently, XML output can be used to support per‐
374       formance optimization in the same manner that gcov does.
375
376   HTML Output
377       The gcovr command can also generate a  simple  HTML  output  using  the
378       --html option:
379
380          gcovr -r . --html -o example-html.html
381
382       This  generates a HTML summary of the lines executed.  In this example,
383       the file example1.html is generated, which has  the  following  output:
384       [image]
385
386       The  default  behavior  of  the --html option is to generate HTML for a
387       single webpage that summarizes the coverage for all files.  The HTML is
388       printed to standard output, but the -o/--output option is used to spec‐
389       ify a file that stores the HTML output.
390
391       The --html-details option is used to create a  separate  web  page  for
392       each  file.  Each of these web pages includes the contents of file with
393       annotations that summarize code coverage.  Consider the following  com‐
394       mand:
395
396          gcovr -r . --html --html-details -o example-html-details.html
397
398       This  generates the following HTML page for the file example1.cpp: [im‐
399       age]
400
401       Note that the --html-details option needs a named output, e.g. via  the
402       the  -o/--output  option.   For  example, if the output is named cover‐
403       age.html, then the web pages generated for each file will have names of
404       the form coverage.<filename>.html.
405
406       The  --html-self-contained  option  controls  whether  assets  like CSS
407       styles are bundled into the HTML file.  The --html report  defaults  to
408       self-contained     mode.      but     --html-details     defaults    to
409       --no-html-self-contained in order to avoid problems  with  the  Content
410       Security Policy of some servers, especially Jenkins.
411
412       New     in     version    5.0:    Added    --html-self-contained    and
413       --no-html-self-contained.
414
415
416       Changed  in  version  5.0:   Default   to   external   CSS   file   for
417       --html-details.
418
419
420   Sonarqube XML Output
421       If you are using Sonarqube, you can get a coverage report in a suitable
422       XML format via the --sonarqube option:
423
424          gcovr --sonarqube coverage.xml
425
426       The      Sonarqube      XML      format      is      documented      at
427       https://docs.sonarqube.org/latest/analysis/generic-test/.
428
429   JSON Output
430       The  gcovr command can also generate a JSON output using the --json and
431       --json-pretty options:
432
433          gcovr --json coverage.json
434
435       The --json-pretty option generates an indented JSON output that is eas‐
436       ier to read.
437
438       Structure  of file is based on gcov JSON intermediate format with addi‐
439       tional key names specific to gcovr.
440
441       Structure of the JSON is following:
442
443          {
444              "gcovr/format_version": gcovr_json_version
445              "files": [file]
446          }
447
448       gcovr_json_version: version of gcovr JSON format
449
450       Each file has the following form:
451
452          {
453              "file": file
454              "lines": [line]
455          }
456
457       file: path to source code file, relative to gcovr root directory.
458
459       Each line has the following form:
460
461          {
462              "branches": [branch]
463              "count": count
464              "line_number": line_number
465              "gcovr/noncode": gcovr_noncode
466          }
467
468       gcovr_noncode: if True coverage info on this line should be ignored
469
470       Each branch has the following form:
471
472          {
473            "count": count
474            "fallthrough": fallthrough
475            "throw": throw
476          }
477
478       file, line and branch have the structure defined in  gcov  intermediate
479       format.        This        format        is        documented        at
480       https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov.
481
482       If you just need a summary of the coverage information, similar to  the
483       tabulated text based output, you can use --json-summary instead.
484
485       Multiple  JSON  files  can be merged into the coverage data with sum of
486       lines and branches execution.
487
488   JSON Summary Output
489       The --json-summary option output coverage summary in a machine-readable
490       format for additional post processing.  The format is identical to JSON
491       output  --json  option  without  detailed   lines   information.    The
492       --json-summary-pretty  option generates an indented JSON summary output
493       that is easier to read.  Consider the following command:
494
495          gcovr -r . --json-summary-pretty --json-summary
496
497       This generates an indented JSON summary:
498
499          {
500              "branch_covered": 1,
501              "branch_percent": 50.0,
502              "branch_total": 2,
503              "files": [
504                  {
505                      "branch_covered": 1,
506                      "branch_percent": 0.5,
507                      "branch_total": 2,
508                      "filename": "example.cpp",
509                      "line_covered": 6,
510                      "line_percent": 0.857,
511                      "line_total": 7
512                  }
513              ],
514              "gcovr/summary_format_version": 0.2,
515              "line_covered": 6,
516              "line_percent": 85.7,
517              "line_total": 7,
518              "root": ".."
519          }
520
521       New in version 5.0: Added --json-summary and --json-summary-pretty.
522
523
524   CSV Output
525       The --csv option output comma-separated values summarizing the coverage
526       of each file. Consider the following command:
527
528          gcovr -r . --csv
529
530       This generates an CSV:
531
532          filename,line_total,line_covered,line_percent,branch_total,branch_covered,branch_percent
533          example.cpp,7,6,0.857,2,1,0.5
534
535
536       New in version 5.0: Added --csv.
537
538
539   Coveralls JSON Output
540       If you are using Coveralls, you can get a coverage report in a suitable
541       JSON format via the --coveralls option:
542
543          gcovr --coveralls coverage.json
544
545       The --coveralls-pretty option generates an indented JSON output that is
546       easier to read.
547
548       Keep  in  mind  that  the  output  contains the checksums of the source
549       files. If you are using different OSes, the line endings shall  be  the
550       same.
551
552       If  available,  environment  variable COVERALLS_REPO_TOKEN will be con‐
553       sumed and baked into the JSON output.
554
555       If running in a CI additional variables are used:
556
557       • In Travis CI:
558
559         • TRAVIS_JOB_ID
560
561         • TRAVIS_BUILD_NUMBER
562
563         • TRAVIS_PULL_REQUEST
564
565         • TRAVIS_COMMIT
566
567         • TRAVIS_BRANCH
568
569       • In Appveyor:
570
571         • APPVEYOR_JOB_ID
572
573         • APPVEYOR_JOB_NUMBER
574
575         • APPVEYOR_PULL_REQUEST_NUMBER
576
577         • APPVEYOR_REPO_COMMIT
578
579         • APPVEYOR_REPO_BRANCH
580
581       • In Jenkins CI:
582
583         • JOB_NAME
584
585         • BUILD_ID
586
587         • CHANGE_ID
588
589         • GIT_COMMIT (if available)
590
591         • BRANCH_NAME
592
593       • In GitHub Actions:
594
595         • GITHUB_WORKFLOW
596
597         • GITHUB_RUN_ID
598
599         • GITHUB_SHA
600
601         • GITHUB_HEAD_REF (if available)
602
603         • GITHUB_REF
604
605       The     Coveralls      JSON      format      is      documented      at
606       https://docs.coveralls.io/api-introduction.
607
608       New in version 5.0: Added --coveralls and --coveralls-pretty.
609
610
611   Multiple Output Formats
612       You  can  write  multiple  report  formats with one gcovr invocation by
613       passing the output filename directly to the report format flag.  If  no
614       filename  is  specified  for  the format, the value from -o/--output is
615       used by default, which itself defaults to stdout.
616
617       The following report format flags can  take  an  optional  output  file
618       name:
619
620gcovr --csv
621
622gcovr --txt
623
624gcovr --xml
625
626gcovr --html
627
628gcovr --html-details
629
630gcovr --sonarqube
631
632gcovr --json
633
634gcovr --json-summary
635
636gcovr --coveralls
637
638       If  the  value given to the output option ends with a path seperator (/
639       or \) it is used a directory which is created first and a default file‐
640       name depending on the format is used.
641
642       Note  that  --html-details  overrides  any  value  of  --html  if it is
643       present.
644
645   Combining Tracefiles
646       You can merge coverage data from multiple runs with -a/--add-tracefile.
647
648       For each run, generate JSON output:
649
650          ...  # compile and run first test case
651          gcovr ... --json run-1.json
652          ...  # compile and run second test case
653          gcovr ... --json run-2.json
654
655       Next, merge the json files and generate the desired report:
656
657          gcovr --add-tracefile run-1.json --add-tracefile run-2.json --html-details coverage.html
658
659       You can also use unix style wildcards to merge the json  files  without
660       duplicating -a/--add-tracefile. With this option you have to place your
661       pathnames with wildcards in double quotation marks:
662
663          gcovr --add-tracefile "run-*.json" --html-details coverage.html
664
665   The gcovr Command
666       The gcovr command recursively searches a directory tree  to  find  gcov
667       coverage files, and generates a text summary of the code coverage.  The
668       -h/--help option generates the following summary of the  gcovr  command
669       line options:
670
671   gcovr
672       A utility to run gcov and summarize the coverage in simple reports.
673
674          usage: gcovr [options] [search_paths...]
675
676       See <http://gcovr.com/> for the full manual.
677
678   Options
679       search_paths
680              Search  these directories for coverage files. Defaults to --root
681              and --object-directory. Config key: search-path.
682
683       -h, --help
684              Show this help message, then exit.
685
686       --version
687              Print the version number, then exit.
688
689       -v, --verbose
690              Print progress messages. Please include this output in  bug  re‐
691              ports.
692
693       -r <root>, --root <root>
694              The  root  directory  of your source files. Defaults to '.', the
695              current directory. File names  are  reported  relative  to  this
696              root. The --root is the default --filter.
697
698       -a <add_tracefile>, --add-tracefile <add_tracefile>
699              Combine  the  coverage data from JSON files. Coverage files con‐
700              tains source files structure relative to root  directory.  Those
701              structures  are  combined  in the output relative to the current
702              root directory. Unix style wildcards can  be  used  to  add  the
703              pathnames  matching  a  specified  pattern. In this case pattern
704              must be set in double quotation marks. Option can  be  specified
705              multiple  times.  When option is used gcov is not run to collect
706              the new coverage data.
707
708       --config <config>
709              Load that configuration  file.  Defaults  to  gcovr.cfg  in  the
710              --root directory.
711
712       --fail-under-line <min>
713              Exit  with a status of 2 if the total line coverage is less than
714              MIN. Can be ORed with exit status of  '--fail-under-branch'  op‐
715              tion.
716
717       --fail-under-branch <min>
718              Exit  with  a  status  of 4 if the total branch coverage is less
719              than MIN. Can be ORed with exit  status  of  '--fail-under-line'
720              option.
721
722       --source-encoding <source_encoding>
723              Select  the source file encoding. Defaults to the system default
724              encoding (UTF-8).
725
726   Output Options
727       Gcovr prints a text report by default, but can switch to XML or HTML.
728
729       -o <output>, --output <output>
730              Print output to this filename. Defaults  to  stdout.  Individual
731              output formats can override this.
732
733       -b, --branches
734              Report  the  branch  coverage  instead of the line coverage. For
735              text report only. Config key: txt-branch.
736
737       -u, --sort-uncovered
738              Sort entries by increasing number of uncovered lines.  For  text
739              and HTML report.
740
741       -p, --sort-percentage
742              Sort  entries  by  increasing percentage of uncovered lines. For
743              text and HTML report.
744
745       --txt <output>
746              Generate a text report.  OUTPUT  is  optional  and  defaults  to
747              --output.
748
749       -x <output>, --xml <output>
750              Generate a Cobertura XML report. OUTPUT is optional and defaults
751              to --output.
752
753       --xml-pretty
754              Pretty-print the XML report. Implies --xml. Default: False.
755
756       --html <output>
757              Generate a HTML report.  OUTPUT  is  optional  and  defaults  to
758              --output.
759
760       --html-details <output>
761              Add  annotated  source  code reports to the HTML report. Implies
762              --html. OUTPUT is optional and defaults to --output.
763
764       --html-details-syntax-highlighting
765              Use syntax highlighting in HTML details  page.  Enabled  by  de‐
766              fault. Negation: --no-html-details-syntax-highlighting.
767
768       --html-theme {green,blue}
769              Override the default color theme for the HTML report. Default is
770              green.
771
772       --html-css <css>
773              Override the default style sheet for the HTML report.
774
775       --html-title <title>
776              Use TITLE as title for the HTML report.  Default  is  'GCC  Code
777              Coverage Report'.
778
779       --html-medium-threshold <medium>
780              If the coverage is below MEDIUM, the value is marked as low cov‐
781              erage in the HTML report. MEDIUM has to be lower than  or  equal
782              to  value of --html-high-threshold and greater than 0. If MEDIUM
783              is equal to value of --html-high-threshold the report  has  only
784              high and low coverage. Default is 75.0.
785
786       --html-high-threshold <high>
787              If  the  coverage  is  below HIGH, the value is marked as medium
788              coverage in the HTML report. HIGH has  to  be  greater  than  or
789              equal  to  value of --html-medium-threshold. If HIGH is equal to
790              value of --html-medium-threshold the report has  only  high  and
791              low coverage. Default is 90.0.
792
793       --html-tab-size <html_tab_size>
794              Used spaces for a tab in a source file. Default is 4
795
796       --html-absolute-paths
797              Use  absolute paths to link the --html-details reports. Defaults
798              to relative links.
799
800       --html-encoding <html_encoding>
801              Override the declared HTML report encoding. Defaults  to  UTF-8.
802              See also --source-encoding.
803
804       --html-self-contained
805              Control  whether  the  HTML  report  bundles  resources like CSS
806              styles. Self-contained reports can be sent via email,  but  con‐
807              flict  with the Content Security Policy of some web servers. De‐
808              faults to self-contained reports unless --html-details is  used.
809              Negation: --no-html-self-contained.
810
811       -s, --print-summary
812              Print  a  small  report  to stdout with line & branch percentage
813              coverage. This is in addition to other reports. Default: False.
814
815       --sonarqube <output>
816              Generate sonarqube generic coverage report in  this  file  name.
817              OUTPUT is optional and defaults to --output.
818
819       --json <output>
820              Generate  a  JSON  report.  OUTPUT  is  optional and defaults to
821              --output.
822
823       --json-pretty
824              Pretty-print the JSON report. Implies --json. Default: False.
825
826       --json-summary <output>
827              Generate a JSON summary report. OUTPUT is optional and  defaults
828              to --output.
829
830       --json-summary-pretty
831              Pretty-print  the  JSON  SUMMARY report. Implies --json-summary.
832              Default: False.
833
834       --csv <output>
835              Generate a CSV summary report. OUTPUT is optional  and  defaults
836              to --output.
837
838       --coveralls <output>
839              Generate Coveralls API coverage report in this file name. OUTPUT
840              is optional and defaults to --output.
841
842       --coveralls-pretty
843              Pretty-print the coveralls report. Implies --coveralls. Default:
844              False.
845
846   Filter Options
847       Filters  decide which files are included in the report. Any filter must
848       match, and no exclude filter must match. A filter is a regular  expres‐
849       sion  that  matches  a  path. Filter paths use forward slashes, even on
850       Windows. If the filter looks  like  an  absolute  path  it  is  matched
851       against  an  absolute  path. Otherwise, the filter is matched against a
852       relative path, where that path is relative to the current directory  or
853       if defined in a configuration file to the directory of the file.
854
855       -f <filter>, --filter <filter>
856              Keep  only source files that match this filter. Can be specified
857              multiple times. Relative filters are  relative  to  the  current
858              working  directory  or if defined in a configuration file. If no
859              filters are provided, defaults to --root.
860
861       -e <exclude>, --exclude <exclude>
862              Exclude source files that match this filter.  Can  be  specified
863              multiple times.
864
865       --gcov-filter <gcov_filter>
866              Keep  only gcov data files that match this filter. Can be speci‐
867              fied multiple times.
868
869       --gcov-exclude <gcov_exclude>
870              Exclude gcov data files that match this filter. Can be specified
871              multiple times.
872
873       --exclude-directories <exclude_dirs>
874              Exclude  directories  that  match this regex while searching raw
875              coverage files. Can be specified multiple times.
876
877   GCOV Options
878       The 'gcov' tool turns raw coverage files (.gcda and .gcno)  into  .gcov
879       files that are then processed by gcovr. The gcno files are generated by
880       the compiler. The gcda files are generated when the  instrumented  pro‐
881       gram is executed.
882
883       --gcov-executable <gcov_cmd>
884              Use  a  particular  gcov executable. Must match the compiler you
885              are using, e.g. 'llvm-cov gcov' for  Clang.  Can  include  addi‐
886              tional  arguments. Defaults to the GCOV environment variable, or
887              'gcov': 'gcov'.
888
889       --exclude-unreachable-branches
890              Exclude branch coverage from lines without  useful  source  code
891              (often, compiler-generated "dead" code). Default: False.
892
893       --exclude-function-lines
894              Exclude coverage from lines defining a function Default: False.
895
896       --exclude-throw-branches
897              For  branch  coverage, exclude branches that the compiler gener‐
898              ates for exception handling. This often leads to more "sensible"
899              coverage reports. Default: False.
900
901       --exclude-lines-by-pattern <exclude_lines_by_pattern>
902              Exclude lines that match this regex.
903
904       -g, --use-gcov-files
905              Use existing gcov files for analysis. Default: False.
906
907       --gcov-ignore-parse-errors
908              Skip  lines  with  parse errors in GCOV files instead of exiting
909              with an error. A report will be shown on stderr. Default: False.
910
911       --object-directory <objdir>
912              Override normal working  directory  detection.  Gcovr  needs  to
913              identify the path between gcda files and the directory where the
914              compiler was originally run.  Normally,  gcovr  can  guess  cor‐
915              rectly.  This  option  specifies either the path from gcc to the
916              gcda file (i.e. gcc's '-o' option), or the path  from  the  gcda
917              file to gcc's working directory.
918
919       -k, --keep
920              Keep  gcov  files  after  processing. This applies both to files
921              that  were  generated  by  gcovr,  or  were  supplied  via   the
922              --use-gcov-files    option.    Default:   False.   Config   key:
923              keep-gcov-files.
924
925       -d, --delete
926              Delete gcda files after processing. Default: False. Config  key:
927              delete-gcov-files.
928
929       -j <gcov_parallel>
930              Set  the  number  of  threads  to  use  in parallel. Config key:
931              gcov-parallel.
932
933       The above Getting Started guide illustrates the  use  of  some  command
934       line options.  Using Filters is discussed below.
935
936   Using Filters
937       Gcovr  tries to only report coverage for files within your project, not
938       for your libraries. This is influenced by the following options:
939
940-r, --root
941
942-f, --filter
943
944-e, --exclude
945
946--gcov-filter
947
948--gcov-exclude
949
950--exclude-directories
951
952       • (the current working directory where gcovr is invoked)
953
954       These options take filters.  A filter  is  a  regular  expression  that
955       matches a file path.  Because filters are regexes, you will have to es‐
956       cape “special” characters with a backslash \.
957
958       Always use forward slashes / as path separators, even on Windows:
959
960       • wrong:   --filter C:\project\src\
961
962       • correct: --filter C:/project/src/
963
964       If the filter looks like an absolute path, it is matched against an ab‐
965       solute path.  Otherwise, the filter is matched against a relative path,
966       where that path is relative to the current directory or if defined in a
967       configuration file to the directory of the file.
968
969       Examples of relative filters:
970
971--filter subdir/ matches only that subdirectory
972
973--filter '\.\./src/' matches a sibling directory ../src.  But because
974         a dot . matches any character in a regex, we have to escape it.   You
975         have  to  use  additional  shell  escaping.  This example uses single
976         quotes for Bash or POSIX shell.
977
978--filter '(.+/)?foo\.c$' matches only files called foo.c.  The  regex
979         must  match  from  the  start  of the relative path, so we ignore any
980         leading directory parts with (.+/)?.  The $ at the end  ensures  that
981         the path ends here.
982
983       If  no  -f/--filter is provided, the -r/--root is turned into a default
984       filter.  Therefore, files outside of the -r/--root  directory  are  ex‐
985       cluded.
986
987       To be included in a report, the source file must match any -f/--filter,
988       and must not match any -e/--exclude filter.
989
990       The --gcov-filter and --gcov-exclude filters apply to the  .gcov  files
991       created by gcov.  This is useful mostly when running gcov yourself, and
992       then invoking gcovr with -g/--use-gcov-files.  But these  filters  also
993       apply when gcov is launched by gcovr.
994
995   Speeding up coverage data search
996       The --exclude-directories filter is used while searching for raw cover‐
997       age data (or for existing .gcov files when -g/--use-gcov-files  is  ac‐
998       tive).  This filter is matched against directory paths, not file paths.
999       If a directory matches, all its  contents  (files  and  subdirectories)
1000       will be excluded from the search.  For example, consider this build di‐
1001       rectory:
1002
1003          build/
1004          ├─ main.o
1005          ├─ main.gcda
1006          ├─ main.gcno
1007          ├─ a/
1008          │  ├─ awesome_code.o
1009          │  ├─ awesome_code.gcda
1010          │  └─ awesome_code.gcno
1011          └─ b/
1012             ├─ better_code.o
1013             ├─ better_code.gcda
1014             └─ better_code.gcno
1015
1016       If we run gcovr --exclude-directories  'build/a$',  this  will  exclude
1017       anything  in  the  build/a directory but will use the coverage data for
1018       better_code.o and main.o.
1019
1020       This can speed up gcovr when you have  a  complicated  build  directory
1021       structure.   Consider also using the search_paths or --object-directory
1022       arguments to specify where gcovr starts searching.  If you  are  unsure
1023       which directories are being searched, run gcovr in -v/--verbose mode.
1024
1025       For  each  found  coverage  data  file gcovr will invoke the gcov tool.
1026       This is typically the slowest part, and other filters can only  be  ap‐
1027       plied  after  this step.  In some cases, parallel execution with the -j
1028       option might be helpful to speed up processing.
1029
1030   Filters for symlinks
1031       Gcovr matches filters against real paths that have all  their  symlinks
1032       resolved.  E.g. consider this project layout:
1033
1034          /home/you/
1035          ├─ project/  (pwd)
1036          │  ├─ src/
1037          │  ├─ relevant-library/ -> ../external-library/
1038          │  └─ ignore-this/
1039          └─ external-library/
1040             └─ src/
1041
1042       Here,  the  relevant-library  has  the real path /home/you/external-li‐
1043       brary.
1044
1045       To write a filter that includes both src/ and relevant-library/src/, we
1046       cannot  use --filter relevant-library/src/ because that contains a sym‐
1047       link.  Instead, we have to use an absolute path to the real name:
1048
1049          gcovr --filter src/ --filter /home/you/external-library/src/
1050
1051       or a relative path to the real path:
1052
1053          gcovr --filter src/ --filter '\.\./external-library/src/'
1054
1055       NOTE:
1056          This section discusses symlinks on Unix systems.  The behavior under
1057          Windows  is  unclear.   If you have more insight, please update this
1058          section by submitting a pull request (see our contributing guide).
1059
1060   Configuration Files
1061       WARNING:
1062          Config files are an experimental  feature  and  may  be  subject  to
1063          change without prior notice.
1064
1065       Defaults  for  the  command  line options can be set in a configuration
1066       file.  Example:
1067
1068          filter = src/
1069          html-details = yes  # info about each source file
1070          output = build/coverage.html
1071
1072       How the configuration file is found: If a --config option is  provided,
1073       that file is used.  Otherwise, a gcovr.cfg file in the -r/--root direc‐
1074       tory is used, if that file exists.
1075
1076       Each line contains a key = value pair.  Space around the = is optional.
1077       The  value  may  be empty.  Comments start with a hash # and ignore the
1078       rest of the line, but cannot start within a word.  Empty lines are also
1079       ignored.
1080
1081       The  available  config  keys correspond closely to the command line op‐
1082       tions, and are parsed similarly.  In most cases, the  name  of  a  long
1083       command line option can be used as a config key.  If not, this is docu‐
1084       mented in the option's help message.   For  example,  --gcov-executable
1085       can  be  set  via the gcov-executable config key.  But -b/--branches is
1086       set via txt-branch.
1087
1088       Just like command line options, the config keys can be specified multi‐
1089       ple times.  Depending on the option the last one wins or a list will be
1090       built.  For example, -f/--filter can be provided multiple times:
1091
1092          # Only show coverage for files in src/, lib/foo, or for main.cpp files.
1093          filter = src/
1094          filter = lib/foo/
1095          filter = *./main\.cpp
1096
1097       Note that relative filters specified in config  files  will  be  inter‐
1098       preted relative to the location of the config file itself.
1099
1100       Option arguments are parsed with the following precedence:
1101
1102       • First the config file is parsed, if any.
1103
1104       • Then, all command line arguments are added.
1105
1106       • Finally,  if  an option was specified neither in a config file nor on
1107         the command line, its documented default value is used.
1108
1109       Therefore, it doesn't matter whether a value is provided in the  config
1110       file or the command line.
1111
1112       Boolean  flags are treated specially.  When their config value is “yes”
1113       they are enabled, as if the flag had been provided on the command line.
1114       When  their  value  is  “no”, they are explicitly disabled by assigning
1115       their default value.  The -j flag is special as it  takes  an  optional
1116       argument.   In  the config file, gcov-parallel = yes would refer to the
1117       no-argument form, whereas gcov-parallel = 4 would provide  an  explicit
1118       argument.
1119
1120       Some  config  file syntax is explicitly reserved for future extensions:
1121       Semicolon comments, INI-style sections, multi-line values, quoted  val‐
1122       ues, variable substitutions, alternative key–value separators, …
1123
1124   Exclusion Markers
1125       You can exclude parts of your code from coverage metrics.
1126
1127       • If GCOVR_EXCL_LINE appears within a line, that line is ignored.
1128
1129       • If  GCOVR_EXCL_START  appears within a line, all following lines (in‐
1130         cluding the current line) are ignored until a GCOVR_EXCL_STOP  marker
1131         is encountered.
1132
1133       Instead  of  GCOVR_*, the markers may also start with GCOV_* or LCOV_*.
1134       However, start and stop markers must use the same style.   The  markers
1135       are not configurable.
1136
1137       In the excluded regions, any coverage is excluded.  It is not currently
1138       possible to exclude only branch coverage in that region.   In  particu‐
1139       lar, lcov's EXCL_BR markers are not supported (see issue #121).
1140
1141   Acknowledgements
1142       Gcovr is maintained by:
1143          William Hart, John Siirola, and Lukas Atkinson.
1144
1145       The following developers contributed to gcovr (ordered alphabetically):
1146          alex43dm, Andrew Stone, Antonio Quarta, Arvin Schnell, Attie Grande,
1147          Bernhard Breinbauer, Carlos Jenkins, Cary Converse, Cezary Gapiński,
1148          Christian  Taedcke,  Dave  George,  Dom Postorivo, Ensky Lin, goriy,
1149          ja11sop, James Reynolds, Jeremy  Fixemer,  Jessica  Levine,  Joachim
1150          Kuebart,   Joel   Klinghed,  John  Siirola,  Jörg  Kreuzberger,  Kai
1151          Blaschke, Kevin Broselge, Kevin Cai, Leon Ma, libPhipp, Lukas Atkin‐
1152          son,  Luke  Woydziak,  Marek  Kurdej, Martin Mraz, Matsumoto Taichi,
1153          Matthew Stadelman, Matthias Schmieder,  Matthieu  Darbois,  Matthieu
1154          Eyraud,  Michael Förderer, Michał Pszona, Mikael Salson, Mikk Leini,
1155          Nikolaj Schumacher, Oleksiy Pikalo, Phil Clapham,  Piotr  Dziwinski,
1156          Reto  Schneider,  Richard Kjerstadius, Robert Rosengren, Songmin Li,
1157          Steven Myint, Sylvestre Ledru, Tilo Wiedera, trapzero,  Will  Thomp‐
1158          son, William Hart, Zachary J. Fields, and possibly others.
1159
1160       The  development  of  Gcovr  has been partially supported by Sandia Na‐
1161       tional Laboratories.  Sandia National Laboratories is  a  multi-program
1162       laboratory  managed  and operated by Sandia Corporation, a wholly owned
1163       subsidiary of Lockheed Martin Corporation, for the U.S.  Department  of
1164       Energy's   National  Nuclear  Security  Administration  under  contract
1165       DE-AC04-94AL85000.
1166

GCOVR COOKBOOK

1168   How to collect coverage for C extensions in Python
1169       Collecting code coverage data on the C code that makes up a Python  ex‐
1170       tension module is not quite as straightforward as with a regular C pro‐
1171       gram.
1172
1173       As with a normal C project, we have to compile our code  with  coverage
1174       instrumentation.   Here,  we  export  CFLAGS="--coverage"  and then run
1175       python3 setup.py build_ext.
1176
1177       Unfortunately, build_ext can rebuild a source file even if the  current
1178       object  file  is  up  to date.  If multiple extension modules share the
1179       same source code file, gcov will get confused by  the  different  time‐
1180       stamps  and  report inaccurate coverage.  It is nontrivial to adapt the
1181       build_ext process to avoid this.
1182
1183       Instead, we can use the ccache utility to  make  the  compilation  lazy
1184       (works  best on Unix systems).  Before we invoke the build_ext step, we
1185       first export CC="ccache gcc".  Ccache works well but  isn't  absolutely
1186       perfect, see the ccache manual for caveats.
1187
1188       A shell session might look like this:
1189
1190          # Set required env vars
1191          export CFLAGS="--coverage"
1192          export CC="ccache gcc"
1193
1194          # clear out build files so we get a fresh compile
1195          rm -rf build/temp.*  # contains old .gcda, .gcno files
1196          rm -rf build/lib.*
1197
1198          # rebuild extensions
1199          python3 setup.py build_ext --inplace  # possibly --force
1200
1201          # run test command i.e. pytest
1202
1203          # run gcovr
1204          rm -rf coverage; mkdir coverage
1205          gcovr --filter src/ --print-summary --html-details -o coverage/index.html
1206
1207   Out-of-Source Builds with CMake
1208       Tools  such  as  cmake encourage the use of out-of-source builds, where
1209       the code is compiled in a directory other than the one  which  contains
1210       the  sources. This is an extra complication for gcov.  In order to pass
1211       the correct compiler and linker flags, the following commands  need  to
1212       be in CMakeLists.txt:
1213
1214          add_compile_options("--coverage")
1215
1216          add_executable(program example.cpp)
1217          target_link_libraries(program gcov)
1218
1219       The  --coverage  compiler  flag  is  an  alternative  to  fprofile-arcs
1220       -ftest-coverage for recent version of gcc.  In versions 3.13 and  later
1221       of   cmake,  the  target_link_libraries  command  can  be  removed  and
1222       add_link_options("--coverage") added after the add_compile_options com‐
1223       mand.
1224
1225       We then follow a normal cmake build process:
1226
1227          cd $BLD_DIR
1228          cmake $SRC_DIR
1229          make VERBOSE=1
1230
1231       and run the program:
1232
1233          cd $BLD_DIR
1234          ./program
1235
1236       However,  invocation  of gcovr itself has to change. The assorted .gcno
1237       and .gcda files will appear under the CMakeFiles directory in  BLD_DIR,
1238       rather than next to the sources. Since gcovr requires both, the command
1239       we need to run is:
1240
1241          cd $BLD_DIR
1242          gcovr -r $SRC_DIR .
1243

FREQUENTLY ASKED QUESTIONS

1245   What is the difference between lcov and gcovr?
1246       Both lcov and gcovr are tools to create coverage reports.
1247
1248       Gcovr was originally created as a simple script to provide a convenient
1249       command  line  interface  to  gcov that produced more easily digestible
1250       output similar to Python's coverage utilities.
1251
1252       Later, we added XML output that could be used with the Cobertura plugin
1253       of the Jenkins continuous integration server.  This gave us nice cover‐
1254       age reports for C/C++ code in Jenkins.
1255
1256       HTML output was added much later.  If all you need is HTML, pick which‐
1257       ever  one produces the output you like better or integrates easier with
1258       your existing workflow.
1259
1260       Lcov is a far older project that is part of the Linux Test Project.  It
1261       provides  some features that gcovr does not have: For example, lcov has
1262       explicit support for capturing Linux kernel coverage.  Lcov  also  sup‐
1263       ports  various  trace file manipulation functions such as merging trace
1264       files from different test runs.  You can learn more at the lcov website
1265       or the lcov GitHub repository.
1266
1267   Why does C++ code have so many uncovered branches?
1268       Gcovr's  branch  coverage reports are based on GCC's -profile-arcs fea‐
1269       ture, which uses the compiler's control flow graph (CFG) of each  func‐
1270       tion  to  determine branches.  This is a very low-level view: to under‐
1271       stand the branches in a given function, it can help to view  the  func‐
1272       tion's assembly, e.g. via the Godbolt Compiler Explorer.
1273
1274       What gcovr calls a branch is in fact an arc between basic blocks in the
1275       CFG.  This means gcovr's reports have many branches that are not caused
1276       by if statements!  For example:
1277
1278       • Arcs  are  caused  by  C/C++  branching  operators:  for,  if, while,
1279         switch/case, &&, ||, ? :.  Note that switches are often compiled as a
1280         decision tree which introduces extra arcs, not just one per case.
1281
1282       • (Arcs into another function are not shown.)
1283
1284       • Arcs  are  caused  when a function that may throw returns: one arc to
1285         the next block or statement for normal returns, and one arc to an ex‐
1286         ception  handler  for exceptions, if this function contains an excep‐
1287         tion handler.  Every local variable with a destructor is an exception
1288         handler as well.
1289
1290       • Compiler-generated  code that deals with exceptions often needs extra
1291         branches: throw statements, catch clauses, and destructors.
1292
1293       • Extra arcs are created for static initialization and destruction.
1294
1295       • Arcs may be added or removed by compiler optimizations.  If you  com‐
1296         pile without optimizations, some arcs may even be unreachable!
1297
1298       Gcovr  is not able to remove any “unwanted” branches because GCC's gcov
1299       tool does not make the necessary  information  available,  and  because
1300       different projects are interested in different kinds of branches.  How‐
1301       ever, gcovr has the following options to reduce unwanted branches:
1302
1303       With the gcovr --exclude-unreachable-branches option, gcovr parses  the
1304       source  code  to  see whether that line even contains any code.  If the
1305       line is empty or only contains curly braces, this could be  an  indica‐
1306       tion  of  compiler-generated  code that was mis-attributed to that line
1307       (such as that for static destruction) and branch coverage will  be  ig‐
1308       nored on that line.
1309
1310       With the gcovr --exclude-throw-branches option, exception-only branches
1311       will be ignored.  These are typically arcs from a function call into an
1312       exception handler.
1313
1314       Compiling with optimizations will typically remove unreachable branches
1315       and remove superfluous branches, but makes the coverage report less ex‐
1316       act.   For  example,  branching operators might be optimized away.  See
1317       also: Gcov and Optimization in the GCC documentation.
1318
1319       Despite these approaches, 100% branch coverage will be  impossible  for
1320       most programs.
1321
1322   Why are uncovered files not reported?
1323       Gcovr  does  report  files  that have zero coverage, even when no .gcda
1324       file is available for that compilation unit.
1325
1326       However, the gcov tool in some versions of GCC refuses to generate out‐
1327       put for uncovered files.
1328
1329       To fix this, upgrade GCC to:
1330
1331       • version 5.5 or later,
1332
1333       • version 6.2 or later, or
1334
1335       • any version since 7.
1336
1337       Note that the compiler may ignore inline functions that are never used.
1338

CONTRIBUTING

1340       This document contains:
1341
1342       • our guidelines for bug reports
1343
1344general contribution guidelines
1345
1346       • a checklist for pull requests
1347
1348       • a  developer guide that explains the development environment, project
1349         structure, and test suite
1350
1351   How to report bugs
1352       When reporting a bug, first search our issues to avoid duplicates.   In
1353       your  bug  report,  please  describe what you expected gcovr to do, and
1354       what it actually did.  Also try to include the following details:
1355
1356       • how you invoked gcovr, i.e. the exact flags and from which directory
1357
1358       • your project layout
1359
1360       • your gcovr version
1361
1362       • your compiler version
1363
1364       • your operating system
1365
1366       • and any other relevant details.
1367
1368       Ideally, you can provide a  short  script  and  the  smallest  possible
1369       source file to reproduce the problem.
1370
1371   How to help
1372       If  you  would  like to help out, please take a look at our open issues
1373       and pull requests.  The issues labeled help  wanted  and  needs  review
1374       would have the greatest impact.
1375
1376       There are many ways how you can help:
1377
1378       • assist other users with their problems
1379
1380       • share your perspective as a gcovr user in discussions
1381
1382       • test proposed changes in your real-world projects
1383
1384       • improve our documentation
1385
1386       • submit pull requests with bug fixes and enhancements
1387
1388   How to submit a Pull Request
1389       Thank  you  for  helping  with  gcovr  development!  Please follow this
1390       checklist for your pull request:
1391
1392Is this a good approach?  Fixing open issues is always  welcome!   If
1393         you  want  to  implement an enhancement, please discuss it first as a
1394         GitHub issue.
1395
1396Does it work?  Please run the tests locally:
1397
1398            make test
1399
1400         (see also: Test suite)
1401
1402         In any case, the tests will run automatically when you open the  pull
1403         request.   But  please prevent unnecessary build failures and run the
1404         tests yourself first.  If you cannot run the tests locally,  you  can
1405         activate  GitHub  for  your  fork,  or run the tests with Docker.  If
1406         there are differences the updated files will be available  for  down‐
1407         load from the CI system (one ZIP for each test environment).
1408
1409         If you add new features, please try to add a test case.
1410
1411Does  it  conform to the style guide?  The source code should conform
1412         to the PEP 8 standard.  Please check your code:
1413
1414            make lint
1415
1416            # or:
1417
1418            python3 -m flake8 doc gcovr --ignore E501,W503
1419
1420         The command make qa will run the linter, run  the  tests,  and  check
1421         that the docs can be built.
1422
1423Add  yourself  as  an  author.  If this is your first contribution to
1424         gcovr, please add yourself to the AUTHORS.txt file.
1425
1426One change at a time.  Please keep your commits and your  whole  pull
1427         request  fairly  small, so that the changes are easy to review.  Each
1428         commit should only contain one kind of change,  e.g.  refactoring  or
1429         new functionality.
1430
1431Why  is  this change necessary?  When you open the PR, please explain
1432         why we need this change and what your PR does.  If this PR  fixes  an
1433         open  issue,  reference  that  issue in the pull request description.
1434         Add a reference to the issue in  the  CHANGELOG.rst,  if  the  change
1435         should  not  be  visible in the changelog (minor or not of interest),
1436         add the following string to a single line in the PR body:
1437            [no changelog]
1438
1439       Once you submit the PR, it will be automatically tested on Windows  and
1440       Linux,  and  code  coverage  will  be collected.  Your code will be re‐
1441       viewed.  This can take a week.  Please fix any issues that are  discov‐
1442       ered  during this process.  Feel free to force-push your updates to the
1443       pull request branch.
1444
1445       If you need assistance for your pull request, you can
1446
1447          • chat in our Gitter room
1448
1449          • discuss your problem in an issue
1450
1451          • open an unfinished pull request as a work in progress  (WIP),  and
1452            explain what you've like to get reviewed
1453
1454   How to set up a development environment
1455       For  working  on  gcovr, you will need a supported version of Python 3,
1456       GCC version 5, 6 or 8 (other GCC versions are supported by  gcovr,  but
1457       will cause spurious test failures), make, cmake and ninja.  Please make
1458       sure that the tools are in the system PATH.  On Windows, you will  need
1459       to install a GCC toolchain as the tests expect a Unix-like environment.
1460       You can use MinGW-W64 or MinGW.  An easier way is  to  run  tests  with
1461       Docker,  on  Windows  a  Pro  license or the WSL (Windows subsystem for
1462       Linux) is needed.
1463
1464       • Check your GCC installation, the binary directory must  be  added  to
1465         the    PATH   environment.   If   the   command   gcc-5/g++-5/gcov-5,
1466         gcc-6/g++-6/gcov-6 or gcc-8/g++-8/gcov-8 are available everything  is
1467         OK. For gcc-6 and gcc-8 you should use the option CC=...` see run and
1468         filter tests. If this isn't OK you have to create  symlinks  for  the
1469         gcc executables with the following steps.  You can check the GCC ver‐
1470         sion with gcc --version. If the output says  version  8,  you  should
1471         also  be  able to run gcc-8 --version. Your Linux distribution should
1472         have set all of this up already.  If you don't  have  an  alias  like
1473         gcc-8,  perform  the following steps to create an alias for gcc, this
1474         should also work in the MSYS shell under Windows:
1475
1476         1. Create a directory somewhere, e.g. in your home  directory:  mkdir
1477            ~/bin
1478
1479         2. Create  a  symlink  in  that  directory which points to GCC: ln -s
1480            $(which gcc) ~/bin/gcc-8
1481
1482         3. Add this directory to your PATH: export PATH="$HOME/bin:$PATH"
1483
1484         4. Re-test gcc-8 --version to ensure everything worked.
1485
1486         5. Create additional symlinks for g++ -> g++-8 and gcov -> gcov-8.
1487
1488       • (Optional) Fork the project on GitHub.
1489
1490       • Clone the git repository.
1491
1492       • (Optional) Set up a virtualenv (e.g. with python3 -m venv my-venv)
1493
1494       • Install gcovr in development mode, and install the test requirements:
1495
1496            make setup-dev  # install all test + doc dependencies
1497
1498            # or:
1499
1500            pip install -e .
1501            pip install -r requirements.txt
1502
1503         You can then run gcovr as gcovr or python3 -m gcovr.
1504
1505         Run the tests to verify that everything works (see Test suite).
1506
1507       • (Optional) Install documentation requirements:
1508
1509            # would be already done by `make setup-dev`
1510            pip install -r doc/requirements.txt
1511
1512         See doc/README.txt for details on working with the documentation.
1513
1514       • (Optional) Activate GitHub Actions for  your  forked  repository,  so
1515         that the cross-platform compatibility tests get run whenever you push
1516         your work to your repository.  These tests will also be run when  you
1517         open a pull request to the main gcovr repository.
1518
1519       Tip:  If  you have problems getting everything set up, consider looking
1520       at these files:
1521
1522       • for Linux: .github/workflows/test.yml and admin/Dockerfile.qa
1523
1524       • for Windows: .github/workflows/test.yml
1525
1526   Project Structure
1527                  ┌───────────────────┬────────────────────────────┐
1528                  │Path               │ Description                │
1529                  ├───────────────────┼────────────────────────────┤
1530/                  │ project root               │
1531                  ├───────────────────┼────────────────────────────┤
1532/gcovr/            │ the  gcovr   source   code │
1533                  │                   │ (Python module)            │
1534                  ├───────────────────┼────────────────────────────┤
1535/gcovr/__main__.py │ command  line  interface + │
1536                  │                   │ top-level behaviour        │
1537                  ├───────────────────┼────────────────────────────┤
1538/gcovr/templates/  │ HTML report templates      │
1539                  ├───────────────────┼────────────────────────────┤
1540/gcovr/tests/      │ unit tests  +  integration │
1541                  │                   │ test corpus                │
1542                  ├───────────────────┼────────────────────────────┤
1543/setup.py          │ Python  package configura‐ │
1544                  │                   │ tion                       │
1545                  ├───────────────────┼────────────────────────────┤
1546/doc/              │ documentation              │
1547                  ├───────────────────┼────────────────────────────┤
1548/doc/sources/      │ user guide + website       │
1549                  ├───────────────────┼────────────────────────────┤
1550/doc/examples/     │ runnable examples for  the │
1551                  │                   │ user guide                 │
1552                  └───────────────────┴────────────────────────────┘
1553
1554       The   program   entrypoint   and   command   line   interface   is   in
1555       gcovr/__main__.py.  The coverage data is parsed in the gcovr.gcov  mod‐
1556       ule.   The  HTML,  XML,  text, and summary reports are in gcovr.genera‐
1557       tor.html and respective modules.
1558
1559   Test suite
1560       The QA process (make qa) consists of multiple parts:
1561
1562       • linting (make lint)
1563
1564       • checking format (make check-format)
1565
1566       • tests (make test)
1567
1568            • unit tests in gcovr/tests
1569
1570            • integration tests in gcovr/tests
1571
1572            • documentation examples in doc/examples
1573
1574       • documentation build (make doc)
1575
1576       The tests are in the gcovr/tests directory.  You can run the tests with
1577       make test or python3 -m pytest gcovr.
1578
1579       There  are unit tests for some parts of gcovr, and a comprehensive cor‐
1580       pus of example projects that are executed as the test_gcovr.py integra‐
1581       tion test.  Each gcovr/tests/* directory is one such example project.
1582
1583       The  next  sections  discuss the structure of integration tests, how to
1584       run and filter tests, and how to run tests with Docker.
1585
1586   Structure of integration tests
1587       Each project in the corpus contains a Makefile and a  reference  direc‐
1588       tory:
1589
1590          gcovr/tests/sometest/
1591            reference/
1592            Makefile
1593            README
1594            example.cpp
1595
1596       The Makefile controls how the project is built, and how gcovr should be
1597       invoked.  The reference directory contains baseline files against which
1598       the gcovr output is compared.  Tests can be executed even without base‐
1599       line files.
1600
1601       Each Makefile contains the following targets:
1602
1603all: builds the example project. Can be shared between gcovr  invoca‐
1604         tions.
1605
1606run:  lists available targets which must be a subset of the available
1607         output formats.
1608
1609clean: remove any generated files after all  tests  of  the  scenario
1610         have finished.
1611
1612       • output  formats  (txt,  html,  json, sonarqube, ...): invoke gcovr to
1613         produce output files of the correct format.  The test runner automat‐
1614         ically  finds  the  generated files (if any) and compares them to the
1615         baseline files in the reference directory.  All formats are optional,
1616         but using at least JSON is recommended.
1617
1618clean-each:  if  provided,  will  be invoked by the test runner after
1619         testing each format.
1620
1621   Run and filter tests
1622       To run all tests, use make test or make qa.  The tests currently assume
1623       that  you  are  using  GCC 5 and have set up a development environment.
1624       You can select a different GCC version  by  setting  the  CC  argument.
1625       Supported versions are CC=gcc-5, CC=gcc-6 and CC=gcc-8.
1626
1627       You  can  run  the  tests  with additional options by setting TEST_OPTS
1628       variable.  Run all tests after each change is a bit slow, therefore you
1629       can limit the tests to a specific test file, example project, or output
1630       format.  For example:
1631
1632          # run only XML tests
1633          make test TEST_OPTS="-k 'xml'"
1634
1635          # run the simple1 tests
1636          make test TEST_OPTS="-k 'simple1'"
1637
1638          # run the simple1 tests only for XML
1639          make test TEST_OPTS="-k 'xml and simple1'"
1640
1641       To see which tests would be run, add the --collect-only option:
1642
1643          #see which tests would be run
1644          make test TEST_OPTS="--collect-only"
1645
1646       Sometimes during development you need to create reference files for new
1647       test  or update the current reference files. To do this you have to add
1648       --generate_reference or  --update-reference  option  to  the  TEST_OPTS
1649       variable.   By default generated output files are automatically removed
1650       after test run.  To skip this process you can add  --skip_clean  option
1651       the TEST_OPTS.  For example:
1652
1653          # run tests and generate references for simple1 example
1654          make test TEST_OPTS="-k 'simple1' --generate_reference"
1655
1656          # run tests and update xml references for simple1 example
1657          make test TEST_OPTS="-k 'xml and simple1' --update_reference"
1658
1659          # run only XML tests and do not remove generated files
1660          make test TEST_OPTS="-k 'xml' --skip_clean"
1661
1662       When  the  currently  generated  output reports differ to the reference
1663       files you can create a ZIP archive named diff.zip in the  tests  direc‐
1664       tory  by  using --archive_differences option.  Currently in gcovr it is
1665       used by GitHub CI to create a ZIP file with the differences as an arti‐
1666       fact.
1667
1668          # run tests and generate a ZIP archive when there were differences
1669          make test TEST_OPTS="--archive_differences"
1670
1671       New  in  version  5.0:  Added  test options --generate_reference, --up‐
1672       date_reference, --skip_clean, '--archive_differences' and  changed  way
1673       to call tests only by make test.
1674
1675
1676   Run tests with Docker
1677       If you can't set up a toolchain locally, you can run the QA process via
1678       Docker.  First, build the container image:
1679
1680          make docker-qa-build
1681
1682       Then, run the container, which executes make qa within the container:
1683
1684          make docker-qa
1685
1686       You can select the gcc version to use inside the docker by setting  the
1687       make variable CC to gcc-5 (default), gcc-6 or gcc-8
1688
1689   Become a gcovr developer
1690       After  you've  contributed  a bit (whether with discussions, documenta‐
1691       tion, or code), consider becoming a gcovr developer.  As  a  developer,
1692       you can:
1693
1694       • manage issues and pull requests (label and close them)
1695
1696       • review  pull requests (a developer must approve each PR before it can
1697         be merged)
1698
1699       • participate in votes
1700
1701       Just open an issue that you're interested, and we'll have a quick vote.
1702

CHANGE LOG

1704       gcovr Release History and Change Log
1705
1706   5.0 (11 June 2021)
1707       Breaking changes:
1708
1709          • Dropped support for Python 2 and Python 3.5.  From now  on,  gcovr
1710            will only support Python versions that enjoy upstream support.
1711
1712       Improvements and new features:
1713
1714          • Handles spaces in gcov path. (#385)
1715
1716          • Early fail when output cannot be created. (#382)
1717
1718          • Add --txt for text output. (#387)
1719
1720          • Add --csv for CSV output. (#376)
1721
1722          • Add --exclude-lines-by-pattern to filter out source lines by arbi‐
1723            trary regex. (#356)
1724
1725          • Add --json-summary to generate a JSON Summary report. (#366)
1726
1727          • Add --coveralls to generate a Coveralls compatible JSON report. (‐
1728            #328)
1729
1730          • Add support for output directories. If the output ends with a / or
1731            \ it is used as a directory. (#416)
1732
1733          • Compare paths case insensitive if file system of working directory
1734            is case insensitive. (#329)
1735
1736          • Add wildcard pattern to json --add-tracefile. (#351)
1737
1738          • Enable --filter and --exclude for Combining tracefiles. (#373)
1739
1740          • Only  output 100.0% in text and HTML output if really 100.0%, else
1741            use 99.9%. (#389)
1742
1743          • Support relative source location for shadow builds. (#410)
1744
1745          • Incorrect path for header now can still generate html-details  re‐
1746            ports (#271)
1747
1748          • Change format version in JSON output from number to string and up‐
1749            date it to "0.2".  (#418, #463)
1750
1751          • Only remove --root path at the start of file paths. (#452)
1752
1753          • Fix coverage report for cmake ninja builds  with  given  in-source
1754            object-directory. (#453)
1755
1756          • Add issue templates. (#461)
1757
1758          • Add  --exclude-function-lines  to exclude the line of the function
1759            definition in the coverage report. (#430)
1760
1761          • Changes for HTML output format:
1762
1763            • Redesign HTML generation. Add --html-self-contained  to  control
1764              externeal or internal CSS. (#367)
1765
1766            • Change legend for threshold in html report. (#371)
1767
1768            • Use  HTML  title  also  for  report  heading.  Default value for
1769              --html-title changed. (#378)
1770
1771            • Add --html-tab-size to configure tab size in  HTML  details.  (‐
1772              #377)
1773
1774            • Add option --html-css for user defined styling. (#380)
1775
1776            • Create details html filename independent from OS. (#375)
1777
1778            • Add --html-theme to change the color theme. (#393)
1779
1780            • Add linkable lines in HTML details. (#401)
1781
1782            • Add  syntax highlighting in the details HTML report. This can be
1783              turned off  with  --no-html-details-syntax-highlighting.  (#402,
1784              #415)
1785
1786       Documentation:
1787
1788          • Cookbook: oos cmake (#340, #341)
1789
1790       Internal changes:
1791
1792          • Add makefile + dockerfile for simpler testing.
1793
1794          • Add .gitbugtraq to link comments to issue tracker in GUIs. (#429)
1795
1796          • Add GitHub actions to test PRs and master branch. (#404)
1797
1798          • Remove Travis CI. (#419)
1799
1800          • Remove  Appveyor  CI  and  upload coverage report from Windows and
1801            Ubuntu from the GitHub actions. (#455)
1802
1803          • Add check if commit is mentioned in the CHANGELOG.rst. (#457)
1804
1805          • Move flake8 config to setup.cfg and add black code  formatter.  (‐
1806            #444)
1807
1808          • Fix filter/exclude relative path issue in Windows. (#320, #479)
1809
1810          • Extend test framework for CI:
1811
1812            • Set  make  variable  TEST_OPTS  as  environment  variable inside
1813              docker. (#372)
1814
1815            • Add make variable USE_COVERAGE to extend flags for coverage  re‐
1816              port in GitHub actions. (#404)
1817
1818            • Extend  tests to use an unified diff in the assert. Add test op‐
1819              tions --generate_reference, --update_reference and --skip_clean.
1820              (#379)
1821
1822            • Support multiple output patterns in integration tests. (#383)
1823
1824            • New  option --archive_differences to save the different files as
1825              ZIP.  Use this ZIP as artifact in AppVeyor. (#392)
1826
1827            • Add support for gcc-8 to test suite and docker tests. (#423)
1828
1829            • Run as limited user inside docker container and  add  test  with
1830              read only directory. (#445)
1831
1832   4.2 (6 November 2019)
1833       Breaking changes:
1834
1835          • Dropped support for Python 3.4.
1836
1837          • Format  flag  parameters like --xml or --html now take an optional
1838            output file name.  This potentially changes the interpretation  of
1839            search  paths.   In gcovr --xml foo, previous gcovr versions would
1840            search the foo directory for coverage data.  Now, gcovr  will  try
1841            to  write  the  Cobertura report to the foo file.  To keep the old
1842            meaning, separate positional arguments like gcovr --xml -- foo.
1843
1844       Improvements and new features:
1845
1846          • Configuration file support  (experimental).   (#167,  #229,  #279,
1847            #281, #293, #300, #304)
1848
1849          • JSON output. (#301, #321, #326)
1850
1851          • Combining tracefiles with gcovr --add-tracefile.  (#10, #326)
1852
1853          • SonarQube XML Output. (#308)
1854
1855          • Handle  cyclic symlinks correctly during coverage data search.  (‐
1856            #284)
1857
1858          • Simplification  of  --object-directory  heuristics.   (#18,  #273,
1859            #280)
1860
1861          • Exception-only code like a catch clause is now shown as uncovered.
1862            (#283)
1863
1864          • New --exclude-throw-branches option to exclude  exception  handler
1865            branches. (#283)
1866
1867          • Support --root .. style invocation, which might fix some CMake-re‐
1868            lated problems. (#294)
1869
1870          • Fix wrong names in report when source and build  directories  have
1871            similar names. (#299)
1872
1873          • Stricter argument handling. (#267)
1874
1875          • Reduce XML memory usage by moving to lxml.  (#1, #118, #307)
1876
1877          • Can  write  multiple reports at the same time by giving the output
1878            file name to the report format parameter.  Now,  gcovr  --html  -o
1879            cov.html and gcovr --html cov.html are equivalent. (#291)
1880
1881          • Override gcov locale properly. (#334)
1882
1883          • Make gcov parser more robust when used with GCC 8. (#315)
1884
1885       Known issues:
1886
1887          • The  --keep  option only works when using existing gcov files with
1888            -g/--use-gcov-files.  (#285, #286)
1889
1890          • Gcovr may get confused when header files in different  directories
1891            have the same name.  (#271)
1892
1893          • Gcovr may not work when no en_US locale is available.  (#166)
1894
1895       Documentation:
1896
1897          • Exclusion marker documentation.
1898
1899          • FAQ: exception branches (#283)
1900
1901          • FAQ: uncovered files not shown (#33, #100, #154, #290, #298)
1902
1903       Internal changes:
1904
1905          • More tests. (#269, #268, #269)
1906
1907          • Refactoring and removal of dead code. (#280)
1908
1909          • New internal data model.
1910
1911   4.1 (2 July 2018)
1912          • Fixed/improved --exclude-directories option. (#266)
1913
1914          • New "Cookbook" section in the documentation. (#265)
1915
1916   4.0 (17 June 2018)
1917       Breaking changes:
1918
1919          • This release drops support for Python 2.6. (#250)
1920
1921          • PIP is the only supported installation method.
1922
1923          • No  longer  encoding-agnostic  under  Python  2.7.  If your source
1924            files do not use the system encoding (probably  UTF-8),  you  will
1925            have to specify a --source-encoding.  (#148, #156, #256)
1926
1927          • Filters  now  use forward slashes as path separators, even on Win‐
1928            dows.  (#191, #257)
1929
1930          • Filters are no longer normalized into  pseudo-paths.   This  could
1931            change the interpretation of filters in some edge cases.
1932
1933       Improvements and new features:
1934
1935          • Improved --help output. (#236)
1936
1937          • Parse the GCC 8 gcov format. (#226, #228)
1938
1939          • New --source-encoding option, which fixes decoding under Python 3.
1940            (#256)
1941
1942          • New --gcov-ignore-parse-errors flag.  By default, gcovr  will  now
1943            abort upon parse errors. (#228)
1944
1945          • Detect  the  error when gcov cannot create its output files (#243,
1946            #244)
1947
1948          • Add -j flag to run gcov processes in parallel. (#3, #36, #239)
1949
1950          • The --html-details flag now implies --html. (#93, #211)
1951
1952          • The --html output can now be used without an --output filename  (‐
1953            #223)
1954
1955          • The  docs  are  now managed with Sphinx.  (#235, #248, #249, #252,
1956            #253)
1957
1958          • New --html-title option to change the title of  the  HTML  report.
1959            (#261, #263)
1960
1961          • New  options  --html-medium-threshold and --html-high-threshold to
1962            customize the color legend. (#261, #264)
1963
1964       Internal changes:
1965
1966          • Huge refactoring. (#214, #215, #221 #225, #228, #237, #246)
1967
1968          • Various testing improvements. (#213, #214, #216, #217, #218, #222,
1969            #223, #224, #227, #240, #241, #245)
1970
1971          • HTML reports are now rendered with Jinja2 templates. (#234)
1972
1973          • New contributing guide. (#253)
1974
1975   3.4 (12 February 2018)
1976          • Added --html-encoding command line option (#139).
1977
1978          • Added  --fail-under-line  and  --fail-under-branch  options, which
1979            will error under a given minimum coverage. (#173, #116)
1980
1981          • Better pathname resolution heuristics for --use-gcov-file. (#146)
1982
1983          • The --root option defaults to current directory '.'.
1984
1985          • Improved reports for "(", ")", ";" lines.
1986
1987          • HTML reports show full timestamp, not just date. (#165)
1988
1989          • HTML reports treat 0/0 coverage as NaN, not  100%  or  0%.  (#105,
1990            #149, #196)
1991
1992          • Add support for coverage-04.dtd Cobertura XML format (#164, #186)
1993
1994          • Only  Python  2.6+ is supported, with 2.7+ or 3.4+ recommended. (‐
1995            #195)
1996
1997          • Added CI testing for Windows using Appveyor. (#189, #200)
1998
1999          • Reports use forward slashes in paths, even on Windows. (#200)
2000
2001          • Fix to support filtering with absolute paths.
2002
2003          • Fix HTML generation with Python 3. (#168, #182, #163)
2004
2005          • Fix --html-details under Windows. (#157)
2006
2007          • Fix filters under Windows. (#158)
2008
2009          • Fix verbose output when using existing gcov files (#143, #144)
2010
2011   3.3 (6 August 2016)
2012          • Added CI testing using TravisCI
2013
2014          • Added more tests for out of source builds and other nested builds
2015
2016          • Avoid common file prefixes in HTML output (#103)
2017
2018          • Added the --execlude-directories argument to  exclude  directories
2019            from the search for symlinks (#87)
2020
2021          • Added branches taken/not taken to HTML (#75)
2022
2023          • Use --object-directory to scan for gcov data files (#72)
2024
2025          • Improved logic for nested makefiles (#135)
2026
2027          • Fixed unexpected semantics with --root argument (#108)
2028
2029          • More careful checks for covered lines (#109)
2030
2031   3.2 (5 July 2014)
2032          • Adding a test for out of source builds
2033
2034          • Using  the  starting directory when processing gcov filenames.  (‐
2035            #42)
2036
2037          • Making relative paths the default in html output.
2038
2039          • Simplify html bar with coverage is zero.
2040
2041          • Add option for using existing gcov files (#35)
2042
2043          • Fixing --root argument processing (#27)
2044
2045          • Adding logic to cover branches that are ignored (#28)
2046
2047   3.1 (6 December 2013)
2048          • Change to make the -r/--root options define the root directory for
2049            source files.
2050
2051          • Fix to apply the -p option when the --html option is used.
2052
2053          • Adding  new option, '--exclude-unreachable-branches' that will ex‐
2054            clude branches in certain lines from coverage report.
2055
2056          • Simplifying and standardizing the processing of linked files.
2057
2058          • Adding tests for deeply nested code, and symbolic links.
2059
2060          • Add support for multiple —filter options in same  manner  as  —ex‐
2061            clude option.
2062
2063   3.0 (10 August 2013)
2064          • Adding the '--gcov-executable' option to specify the name/location
2065            of the gcov executable. The command line option overrides the  en‐
2066            vironment variable, which overrides the default 'gcov'.
2067
2068          • Adding  an  empty "<methods/>" block to <classes/> in the XML out‐
2069            put: this makes out XML complient with the Cobertura DTD. (#3951)
2070
2071          • Allow the GCOV environment variable to override the default 'gcov'
2072            executable.   The  default is to search the PATH for 'gcov' if the
2073            GCOV environment variable is not set. (#3950)
2074
2075          • Adding support for LCOV-style flags for  excluding  certain  lines
2076            from coverage analysis. (#3942)
2077
2078          • Setup additional logic to test with Python 2.5.
2079
2080          • Added the --html and --html-details options to generate HTML.
2081
2082          • Sort output for XML to facilitate baseline tests.
2083
2084          • Added error when the --object-directory option specifies a bad di‐
2085            rectory.
2086
2087          • Added more flexible XML testing, which  can  ignore  XML  elements
2088            that frequently change (e.g. timestamps).
2089
2090          • Added  the  '—xml-pretty' option, which is used to generate pretty
2091            XML output for the user manual.
2092
2093          • Many documentation updates
2094
2095   2.4 (13 April 2012)
2096          • New approach to walking the directory tree that is more robust  to
2097            symbolic links (#3908)
2098
2099          • Normalize all reported path names
2100
2101            • Normalize using the full absolute path (#3921)
2102
2103            • Attempt to resolve files referenced through symlinks to a common
2104              project-relative path
2105
2106          • Process gcno files when there is no  corresponding  gcda  file  to
2107            provide coverage information for unexecuted modules (#3887)
2108
2109          • Windows compatibility fixes
2110
2111            • Fix for how we parse source: file names (#3913)
2112
2113            • Better handling od EOL indicators (#3920)
2114
2115          • Fix  so  that gcovr cleans up all .gcov files, even those filtered
2116            by command line arguments
2117
2118          • Added compatibility with GCC 4.8 (#3918)
2119
2120          • Added a check to warn users who specify  an  empty  --root  option
2121            (see #3917)
2122
2123          • Force  gcov  to  run  with en_US localization, so the gcovr parser
2124            runs correctly on systems with non-English locales (#3898, #3902).
2125
2126          • Segregate warning/error information onto the stderr stream (#3924)
2127
2128          • Miscellaneous (Python 3.x) portability fixes
2129
2130          • Added the master svn revision number as part of the verson identi‐
2131            fier
2132
2133   2.3.1 (6 January 2012)
2134          • Adding support for Python 3.x
2135
2136   2.3 (11 December 2011)
2137          • Adding the --gcov-filter and --gcov-exclude options.
2138
2139   2.2 (10 December 2011)
2140          • Added a test driver for gcovr.
2141
2142          • Improved estimation of the <sources> element when using gcovr with
2143            filters.
2144
2145          • Added revision and date keywords to gcovr so it is easier to iden‐
2146            tify  what  version of the script users are using (especially when
2147            they are running a snapshot from trunk).
2148
2149          • Addressed special case mentioned  in  [comment:ticket:3884:1]:  do
2150            not  truncate  the reported file name if the filter does not start
2151            matching at the beginning of the string.
2152
2153          • Overhaul of the --root / --filter logic. This should  resolve  the
2154            issue  raised  in  #3884, along with the more general filter issue
2155            raised in [comment:ticket:3884:1]
2156
2157          • Overhaul of gcovr's logic for determining gcc/g++'s original work‐
2158            ing directory. This resolves issues introduced in the original im‐
2159            plementation of --object-directory (#3872, #3883).
2160
2161          • Bugfix: gcovr was only including a <sources> element  in  the  XML
2162            report if the user specified -r (#3869)
2163
2164          • Adding  timestamp  and  version attributes to the gcovr XML report
2165            (see #3877).  It looks like the standard Cobertura output  reports
2166            number  of  seconds  since the epoch for the timestamp and a doted
2167            decimal version string.  Now,  gcovr  reports  seconds  since  the
2168            epoch and "gcovr ``"+``__version__ (e.g. "gcovr 2.2") to differen‐
2169            tiate it from a pure Cobertura report.
2170
2171   2.1 (26 November 2010)
2172          • Added the --object-directory option, which allows for  a  flexible
2173            specification of the directory that contains the objects generated
2174            by gcov.
2175
2176          • Adding fix to compare the absolute path of a filename to an exclu‐
2177            sion pattern.
2178
2179          • Adding error checking when no coverage results are found. The line
2180            and branch counts can be zero.
2181
2182          • Adding logic to process the -o/--output option (#3870).
2183
2184          • Adding patch to scan for lines that look like:
2185
2186                creating `foo'
2187
2188            as well as
2189
2190                creating 'foo'
2191
2192          • Changing the semantics for EOL to be portable for MS Windows.
2193
2194          • Add attributes to xml format so that it  could  be  used  by  hud‐
2195            son/bamboo with cobertura plug-in.
2196
2197   2.0 (22 August 2010)
2198          • Initial  release as a separate package.  Earlier versions of gcovr
2199            were managed within the 'fast' Python package.
2200

LICENSE

2202       Copyright 2013-2021 the gcovr authors
2203
2204       Copyright  2013  Sandia  Corporation.   Under  the  terms  of  Contract
2205       DE-AC04-94AL85000  with Sandia Corporation, the U.S. Government retains
2206       certain rights in this software.
2207
2208       Gcovr is available under the 3-clause BSD License.  See LICENSE.txt for
2209       full details.  See AUTHORS.txt for the full list of contributors.
2210
2211       Gcovr development moved to this repository in September, 2013 from San‐
2212       dia National Laboratories.
2213

AUTHOR

2215       the gcovr authors
2216
2218       2022, the gcovr authors
2219
2220
2221
2222
22235.0                              Jan 20, 2022                         GCOVR(1)
Impressum