Provided by: kcov_38+dfsg-1_amd64 
NAME
kcov - Code coverage analysis for compiled programs and Python scripts
SYNOPSIS
kcov [options] outdir executable [args-for-executable...]
kcov --merge outdir <path-to-coverage> [path-to-more-coverage...]
DESCRIPTION
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.
OPTIONS
-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: 16,50).
--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.
--collect-only
Only collect coverage data, don't produce HTML/Cobertura output.
--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.
--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.
UNCOMMON OPTIONS
--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.
--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.
--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.
EXAMPLES
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
HTML OUTPUT
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.
COBERTURA OUTPUT
Kcov also outputs data in the Cobertura XML format, which allows integrating kcov output
in Jenkins (see http://cobertura.sf.net and http://jenkins-ci.org).
The Cobertura output is placed in a file named out-path/exec-filename/cobertura.xml.
JSON OUTPUT
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.
AUTHOR
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).
November 24, 2011 KCOV(1)