1KCOV(1)                     General Commands Manual                    KCOV(1)
2
3
4

NAME

6       kcov - Code coverage analysis for compiled programs and Python scripts
7

SYNOPSIS

9       kcov [options] outdir executable [args-for-executable...]
10
11       kcov --merge outdir <path-to-coverage> [path-to-more-coverage...]
12

DESCRIPTION

14       This  manual  page  documents  briefly the kcov command. kcov is a code
15       coverage tester for ELF binaries, Python scripts and shell scripts.  It
16       allows  collecting  code  coverage information from executables without
17       special compiler directives,  and  continuously  produces  output  from
18       long-running applications.
19
20       See  the  GitHub  page, https://github.com/SimonKagstrom/kcov, for more
21       documentation.
22

OPTIONS

24       -p, --pid=PID
25              Trace PID instead of  executing  executable  (passing  the  exe‐
26              cutable  is  optional  for this case). Under this mode, coverage
27              collection for shared libraries will not work.
28
29       -l, --limits=low,high
30              Setup limits for low/high coverage (default: 16,50).
31
32       --include-path=P1[,P2...]
33              Comma-separated list of paths to include in the report.
34
35       --exclude-path=P1[,P2...]
36              Comma-separated list of paths to exclude from the report.
37
38       --include-pattern=P1[,P2...]
39              Comma-separated list of path patterns to include in the report.
40
41       --exclude-pattern=P1[,P2...]
42              Comma-separated list of path patterns to exclude  from  the  re‐
43              port.
44
45       --exclude-line=P1[,P2...]
46              Comma-separated  list  of line patterns to exclude (mark as non-
47              code)
48
49       --exclude-region=START:END[,START1:END1...]
50              Comma-separated list of regions of  lines  patterns  to  exclude
51              (mark  as  non-code). The region begins with START and ends with
52              END.
53
54       --collect-only
55              Only collect coverage data, don't produce HTML/Cobertura output.
56
57       --report-only
58              Only report HTML/Cobertura output, don't collect data.
59
60       --merge
61              Merge the result of multiple kcov runs. Instead of a program  to
62              test, the output paths from previous runs should be given on the
63              command line, or through a wildcard (*)
64
65       --coveralls-id=id
66              Upload data to coveralls.io using secret repo_token or Travis CI
67              service  job  ID  id.   The  ID is taken as a repo_token if it's
68              longer or equal to 32 characters.
69

UNCOMMON OPTIONS

71       --path-strip-level=N
72              Number of path levels to show for common paths (default: 2).
73
74       --skip-solibs
75              Skip coverage collection for shared libraries (improves  perfor‐
76              mance)
77
78       --verify
79              Verify  that  breakpoints  are  setup on instruction boundaries.
80              This will slow down execution greatly, but  can  catch  problems
81              where the compiler generates bad DWARF data.
82
83       --exit-first-process
84              exit  when  the first process exits, i.e., honor the behavior of
85              daemons. The default behavior is to return to the  console  when
86              the last process exits.
87
88       --python-parser=PARSER
89              Set the python parser to use for Python programs (the default is
90              python). Can be used to run  with  Python  3  on  systems  where
91              Python 2 is the default.
92
93       --bash-parser=PARSER
94              Set  the  bash  parser  to use for shell scripts (the default is
95              /bin/bash).
96
97       --bash-method=METHOD
98              Use collection method METHOD for bash scripts. The method can be
99              either  PS4,  for  use of the PS4 environment variable, or DEBUG
100              for use of the DEBUG trap.
101
102       --bash-handle-sh-invocation
103              Handle invocations of /bin/sh scripts via using  a  LD_PRELOADed
104              library  that  replaces  execve  (i.e.,  /bin/sh  is executed as
105              /bin/bash). Does not work well on some systems, so  the  default
106              is not to use this.
107
108       --bash-dont-parse-binary-dir
109              Kcov  parses  the  directory of the binary for other scripts and
110              add these to the report. If you don't want this  behavior,  this
111              option turns that off.
112
113       --bash-parse-files-in-dir=P1[,P2...]
114              Parse directories for bash scripts.
115
116       --replace-src-path=P1:P2
117              Replace source file path P1 with P2, if found.
118
119       --system-record
120              Perform  full-system  instrumentation  on  a sysroot, outputting
121              patched binaries which collect coverage data. See  doc/full-sys‐
122              tem-instrumentation.md  for  more information on full-system in‐
123              strumentation.
124
125       --system-report
126              Produce coverage output for a full-system coverage run.
127

EXAMPLES

129       Check coverage for ./frodo and generate HTML output  in  /tmp/kcov  and
130       cobertura output in /tmp/kcov/frodo/cobertura.xml
131
132              kcov /tmp/kcov ./frodo
133
134       Check coverage for ./frodo but only include source files names with the
135       string src/frodo
136
137              kcov --include-pattern=src/frodo /tmp/kcov ./frodo
138
139       Same as above but split collecting and reporting (perhaps on  two  dif‐
140       ferent computers)
141
142              kcov --collect-only /tmp/kcov ./frodo
143
144              kcov --report-only --include-pattern=src/frodo /tmp/kcov ./frodo
145

HTML OUTPUT

147       The  HTML  output  shows  executed and non-executed lines of the source
148       code. Some lines can map to multiple instrumentation points, for  exam‐
149       ple for inlined functions (where every inlining of them will generate a
150       separate instrumentation point).  This is shown in the left  column  as
151       1/3  for  example,  which  means  that one of the three instrumentation
152       points has been executed.
153
154       A special output link is [merged], which shows the union of all covered
155       programs.   This  can be useful for example when you have unit tests in
156       multiple binaries which share a subset of source files.
157

COBERTURA OUTPUT

159       Kcov also outputs data in the Cobertura XML format, which allows  inte‐
160       grating   kcov  output  in  Jenkins  (see  http://cobertura.sf.net  and
161       http://jenkins-ci.org).
162
163       The Cobertura output is placed  in  a  file  named  out-path/exec-file‐
164       name/cobertura.xml.
165

JSON OUTPUT

167       Kcov generates a very generic json file which includes the overall per‐
168       cent covered for a single command and the count of  lines  instrumented
169       and covered. It also includes a summary of each source file with a per‐
170       centage and line counts. This allows  easy  integration  with  GitlabCI
171       (see https://docs.gitlab.com/ce/user/project/pipelines/settings.html).
172
173       The JSON output is placed in a file named out-path/exec-filename/cover‐
174       age.json.
175

AUTHOR

177       Kcov was written by Simon Kagstrom, building upon bcov by  Thomas  Neu‐
178       mann.
179
180       This manual page was written by Michael Tautschnig <mt@debian.org>, for
181       the Debian project (but may be used by others).
182
183
184
185                              November  24, 2011                       KCOV(1)
Impressum