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
43 report.
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.
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 --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 --bash-parser=PARSER
94 Set the bash parser to use for shell scripts (the default is
95 /bin/bash).
96 --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 --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 --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 --bash-parse-files-in-dir=P1[,P2...]
114 Parse directories for bash scripts.
115 --replace-src-path=P1:P2
117 Replace source file path P1 with P2, if found.
118 --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
123 instrumentation.
124 --system-report
126 Produce coverage output for a full-system coverage run.
127
129 Check coverage for ./frodo and generate HTML output in /tmp/kcov and
130 cobertura output in /tmp/kcov/frodo/cobertura.xml
131 kcov /tmp/kcov ./frodo
133 Check coverage for ./frodo but only include source files names with the
135 string src/frodo
136 kcov --include-pattern=src/frodo /tmp/kcov ./frodo
138 Same as above but split collecting and reporting (perhaps on two dif‐
140 ferent computers)
141 kcov --collect-only /tmp/kcov ./frodo
143 kcov --report-only --include-pattern=src/frodo /tmp/kcov ./frodo
145
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 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
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 The Cobertura output is placed in a file named out-path/exec-file‐
164 name/cobertura.xml.
165
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 The JSON output is placed in a file named out-path/exec-filename/cover‐
174 age.json.
175
177 Kcov was written by Simon Kagstrom, building upon bcov by Thomas Neu‐
178 mann.
179 This manual page was written by Michael Tautschnig <mt@debian.org>, for
181 the Debian project (but may be used by others).
182 November 24, 2011 KCOV(1)