1KCOV(1) General Commands Manual KCOV(1)
2
6 kcov - Code coverage analysis for compiled programs and Python scripts
7
9 kcov [options] outdir executable [args-for-executable...]
10 kcov --merge outdir <path-to-coverage> [path-to-more-coverage...]
12
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 See the GitHub page, https://github.com/SimonKagstrom/kcov, for more
21 documentation.
22
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 -l, --limits=low,high
30 Setup limits for low/high coverage (default: 16,50).
31 --include-path=P1[,P2...]
33 Comma-separated list of paths to include in the report.
34 --exclude-path=P1[,P2...]
36 Comma-separated list of paths to exclude from the report.
37 --include-pattern=P1[,P2...]
39 Comma-separated list of path patterns to include in the report.
40 --exclude-pattern=P1[,P2...]
42 Comma-separated list of path patterns to exclude from the re‐
43 port.
44 --exclude-line=P1[,P2...]
46 Comma-separated list of line patterns to exclude (mark as non-
47 code)
48 --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 --collect-only
55 Only collect coverage data, don't produce HTML/Cobertura output.
56 --report-only
58 Only report HTML/Cobertura output, don't collect data.
59 --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 --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
71 --path-strip-level=N
72 Number of path levels to show for common paths (default: 2).
73 --skip-solibs
75 Skip coverage collection for shared libraries (improves perfor‐
76 mance)
77 --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 --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 --cobertura-only
89 Generate only cobertura output, as cov.xml, in the output direc‐
90 tory. The intended usage is for e.g., vscode coverage gutters,
91 where the output directory can then be pointed to somewhere in
92 the project directory to get coverage with little droppings.
93 --python-parser=PARSER
95 Set the python parser to use for Python programs (the default is
96 python). Can be used to run with Python 3 on systems where
97 Python 2 is the default.
98 --bash-parser=PARSER
100 Set the bash parser to use for shell scripts (the default is
101 /bin/bash).
102 --bash-method=METHOD
104 Use collection method METHOD for bash scripts. The method can be
105 either PS4, for use of the PS4 environment variable, or DEBUG
106 for use of the DEBUG trap.
107 --bash-handle-sh-invocation
109 Handle invocations of /bin/sh scripts via using a LD_PRELOADed
110 library that replaces execve (i.e., /bin/sh is executed as
111 /bin/bash). Does not work well on some systems, so the default
112 is not to use this.
113 --bash-dont-parse-binary-dir
115 Kcov parses the directory of the binary for other scripts and
116 add these to the report. If you don't want this behavior, this
117 option turns that off.
118 --bash-parse-files-in-dir=P1[,P2...]
120 Parse directories for bash scripts.
121 --replace-src-path=P1:P2
123 Replace source file path P1 with P2, if found.
124 --system-record
126 Perform full-system instrumentation on a sysroot, outputting
127 patched binaries which collect coverage data. See doc/full-sys‐
128 tem-instrumentation.md for more information on full-system in‐
129 strumentation.
130 --system-report
132 Produce coverage output for a full-system coverage run.
133
135 Check coverage for ./frodo and generate HTML output in /tmp/kcov and
136 cobertura output in /tmp/kcov/frodo/cobertura.xml
137 kcov /tmp/kcov ./frodo
139 Check coverage for ./frodo but only include source files names with the
141 string src/frodo
142 kcov --include-pattern=src/frodo /tmp/kcov ./frodo
144 Same as above but split collecting and reporting (perhaps on two dif‐
146 ferent computers)
147 kcov --collect-only /tmp/kcov ./frodo
149 kcov --report-only --include-pattern=src/frodo /tmp/kcov ./frodo
151
153 The HTML output shows executed and non-executed lines of the source
154 code. Some lines can map to multiple instrumentation points, for exam‐
155 ple for inlined functions (where every inlining of them will generate a
156 separate instrumentation point). This is shown in the left column as
157 1/3 for example, which means that one of the three instrumentation
158 points has been executed.
159 A special output link is [merged], which shows the union of all covered
161 programs. This can be useful for example when you have unit tests in
162 multiple binaries which share a subset of source files.
163
165 Kcov also outputs data in the Cobertura XML format, which allows inte‐
166 grating kcov output in Jenkins (see http://cobertura.sf.net and
167 http://jenkins-ci.org).
168 The Cobertura output is placed in a file named out-path/exec-file‐
170 name/cobertura.xml.
171
173 Kcov generates a very generic json file which includes the overall per‐
174 cent covered for a single command and the count of lines instrumented
175 and covered. It also includes a summary of each source file with a per‐
176 centage and line counts. This allows easy integration with GitlabCI
177 (see https://docs.gitlab.com/ce/user/project/pipelines/settings.html).
178 The JSON output is placed in a file named out-path/exec-filename/cover‐
180 age.json.
181
183 Kcov was written by Simon Kagstrom, building upon bcov by Thomas Neu‐
184 mann.
185 This manual page was written by Michael Tautschnig <mt@debian.org>, for
187 the Debian project (but may be used by others).
188 November 24, 2011 KCOV(1)