kcov - Code coverage analysis for compiled programs and Python
scripts
kcov [options] out-dir in-file
[args-for-executable...]
kcov --merge outdir <path-to-coverage>
[path-to-more-coverage...]
This manual page documents briefly the kcov command.
kcov is a code coverage tester for ELF binaries, Python scripts and
shell scripts. It allows collecting code coverage information from
executables without special compiler directives, and continuously produces
output from long-running applications.
See the GitHub page, https://github.com/SimonKagstrom/kcov, for
more documentation.
- -p,
--pid=PID
- Trace PID instead of executing executable (passing the executable is
optional for this case). Under this mode, coverage collection for shared
libraries will not work.
- -l,
--limits=low,high
- Setup limits for low/high coverage (default: 25,75).
- --include-path=P1[,P2...]
- Comma-separated list of paths to include in the report.
- --exclude-path=P1[,P2...]
- Comma-separated list of paths to exclude from the report.
- --include-pattern=P1[,P2...]
- Comma-separated list of path patterns to include in the report.
- --exclude-pattern=P1[,P2...]
- Comma-separated list of path patterns to exclude from the report.
- --exclude-line=P1[,P2...]
- Comma-separated list of line patterns to exclude (mark as non-code)
- --exclude-region=START:END[,START1:END1...]
- Comma-separated list of regions of lines patterns to exclude (mark as
non-code). The region begins with START and ends with END.
- --clean
- Don't accumulate data from multiple runs.
- --collect-only
- Only collect coverage data, don't produce HTML/Cobertura output.
- --dump-summary
- Dump a brief coverage summary on stdout after execution
- --report-only
- Only report HTML/Cobertura output, don't collect data.
- --merge
- Merge the result of multiple kcov runs. Instead of a program to test, the
output paths from previous runs should be given on the command line, or
through a wildcard (*)
- --coveralls-id=id
- Upload data to coveralls.io using secret repo_token or Travis CI service
job ID id. The ID is taken as a repo_token if it's longer or equal
to 32 characters.
- --strip-path=path
- If not set, max common path will be stripped away.
- --path-strip-level=N
- Number of path levels to show for common paths (default: 2).
- --skip-solibs
- Skip coverage collection for shared libraries (improves performance)
- --verify
- Verify that breakpoints are setup on instruction boundaries. This will
slow down execution greatly, but can catch problems where the compiler
generates bad DWARF data.
- --exit-first-process
- exit when the first process exits, i.e., honor the behavior of daemons.
The default behavior is to return to the console when the last process
exits.
- --cobertura-only
- Generate only cobertura output, as cov.xml, in the output directory. The
intended usage is for e.g., vscode coverage gutters, where the output
directory can then be pointed to somewhere in the project directory to get
coverage with little droppings.
- --python-parser=PARSER
- Set the python parser to use for Python programs (the default is python).
Can be used to run with Python 3 on systems where Python 2 is the
default.
- --bash-parser=PARSER
- Set the bash parser to use for shell scripts (the default is
/bin/bash).
- --bash-method=METHOD
- Use collection method METHOD for bash scripts. The method can be
either PS4, for use of the PS4 environment variable, or DEBUG for use of
the DEBUG trap.
- --bash-handle-sh-invocation
- Handle invocations of /bin/sh scripts via using a LD_PRELOADed library
that replaces execve (i.e., /bin/sh is executed as /bin/bash). Does not
work well on some systems, so the default is not to use this.
- --bash-dont-parse-binary-dir
- Kcov parses the directory of the binary for other scripts and add these to
the report. If you don't want this behavior, this option turns that
off.
- --bash-parse-files-in-dir=P1[,P2...]
- Parse directories for bash scripts.
- --bash-tracefd-closeexec
- Force children to not be traced by configuring the trace fd as
non-cloneable with LD_PRELOAD. Buggy on some systems.
- --replace-src-path=P1:P2
- Replace source file path P1 with P2, if found.
- --system-record
- Perform full-system instrumentation on a sysroot, outputting patched
binaries which collect coverage data. See
doc/full-system-instrumentation.md for more information on full-system
instrumentation.
- --system-report
- Produce coverage output for a full-system coverage run.
- --debug=level
- Set the debug level, 0...31 (as a mask). Default is 0 for no debug
output.
- --output-interval=MS
- Set the output writing interval in milliseconds. The default is 5000.
- --configure=KEY=VAL
- Configure key/value pairs of internal options. See --help
--uncommon-options for possible configuration options.
- --patchelf=CMD
- For system mode, set the patchelf command (default patchelf).
Check coverage for ./frodo and generate HTML output in /tmp/kcov
and cobertura output in /tmp/kcov/frodo/cobertura.xml
kcov /tmp/kcov ./frodo
Check coverage for ./frodo but only include source files names
with the string src/frodo
kcov --include-pattern=src/frodo /tmp/kcov ./frodo
Same as above but split collecting and reporting (perhaps on two
different computers)
kcov --collect-only /tmp/kcov ./frodo
kcov --report-only --include-pattern=src/frodo /tmp/kcov
./frodo
The HTML output shows executed and non-executed lines of the
source code. Some lines can map to multiple instrumentation points, for
example for inlined functions (where every inlining of them will generate a
separate instrumentation point). This is shown in the left column as 1/3 for
example, which means that one of the three instrumentation points has been
executed.
A special output link is [merged], which shows the union of all
covered programs. This can be useful for example when you have unit tests in
multiple binaries which share a subset of source files.
Kcov also outputs data in the Cobertura XML format, which allows
integrating kcov output in Jenkins (see
https://cobertura.github.io/cobertura/ and https://www.jenkins.io/).
The Cobertura output is placed in a file named
out-path/exec-filename/cobertura.xml.
Kcov generates a very generic json file which includes the overall
percent covered for a single command and the count of lines instrumented and
covered. It also includes a summary of each source file with a percentage
and line counts. This allows easy integration with GitlabCI (see
https://docs.gitlab.com/ce/user/project/pipelines/settings.html).
The JSON output is placed in a file named
out-path/exec-filename/coverage.json.
Kcov was written by Simon Kagstrom, building upon bcov by Thomas
Neumann.
This manual page was written by Michael Tautschnig
<mt@debian.org>, for the Debian project (but may be used by
others).