kcov.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH KCOV 1 "November  24, 2011"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
kcov \- Code coverage analysis for compiled programs and Python scripts
.SH SYNOPSIS
.B kcov
.RI [ options ] " outdir executable [args-for-executable...]
.PP
.B kcov
.RI --merge " outdir <path-to-coverage> [path-to-more-coverage...]
.SH DESCRIPTION
.PP
This manual page documents briefly the \fBkcov\fP command. \fBkcov\fP 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.
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invoke bold face and italics,
.\" respectively.
.SH OPTIONS
.TP
\fB\-p\fP, \fB\-\-pid\fP=\fIPID\fP
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.
.TP
\fB\-l\fP, \fB\-\-limits\fP=\fIlow,high\fP
Setup limits for low/high coverage (default: 16,50).
.TP
\fB\-\-include\-path\fP=\fIP1\fP[\fI,P2\fP...]
Comma-separated list of paths to include in the report.
.TP
\fB\-\-exclude\-path\fP=\fIP1\fP[\fI,P2\fP...]
Comma-separated list of paths to exclude from the report.
.TP
\fB\-\-include\-pattern\fP=\fIP1\fP[\fI,P2\fP...]
Comma-separated list of path patterns to include in the report.
.TP
\fB\-\-exclude\-pattern\fP=\fIP1\fP[\fI,P2\fP...]
Comma-separated list of path patterns to exclude from the report.
.TP
\fB\-\-exclude\-line\fP=\fIP1\fP[\fI,P2\fP...]
Comma-separated list of line patterns to exclude (mark as non-code)
.TP
\fB\-\-exclude\-region\fP=\fISTART:END\fP[\fI,START1:END1\fP...]
Comma-separated list of regions of lines patterns to exclude (mark as non-code). The region begins with START and ends with END.
.TP
\fB\-\-collect\-only
Only collect coverage data, don't produce HTML/Cobertura output.
.TP
\fB\-\-report\-only
Only report HTML/Cobertura output, don't collect data.
.TP
\fB\-\-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.
.TP
\fB\-\-coveralls\-id\fP=\fIid\fP
Upload data to coveralls.io using secret repo_token or Travis CI service job ID \fIid\fP.
The ID is taken as a repo_token if it's longer or equal to 32 characters.
.SH UNCOMMON OPTIONS
.TP
\fB\-\-path\-strip\-level\fP=\fIN\fP
Number of path levels to show for common paths (default: 2).
.TP
\fB\-\-skip\-solibs
Skip coverage collection for shared libraries (improves performance)
.TP
\fB\-\-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.
.TP
\fB\-\-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.
.TP
\fB\-\-python\-parser\fP=\fIPARSER\fP
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.
.TP
\fB\-\-bash\-parser\fP=\fIPARSER\fP
Set the bash parser to use for shell scripts (the default is /bin/bash).
.TP
\fB\-\-bash\-method\fP=\fIMETHOD\fP
Use collection method \fIMETHOD\fP for bash scripts. The method can be either PS4, for use of
the PS4 environment variable, or DEBUG for use of the DEBUG trap.
.TP
\fB\-\-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.
.TP
\fB\-\-replace\-src\-path\fP=\fIP1\fP:\fIP2\fP
Replace source file path P1 with P2, if found.
.TP
\fB\-\-system\-record
Perform full-system instrumentation on a sysroot, outputting patched binaries which collect coverage data
.TP
\fB\-\-system\-report
Produce coverage output for a full-system coverage run.
.RE
.SH EXAMPLES
.PP
Check coverage for ./frodo and generate HTML output in /tmp/kcov and cobertura output in /tmp/kcov/frodo/cobertura.xml
.PP
.RS
kcov /tmp/kcov ./frodo
.RE
.PP
Check coverage for ./frodo but only include source files names with the string src/frodo
.PP
.RS
kcov \-\-include\-pattern=src/frodo /tmp/kcov ./frodo
.RE
.PP
Same as above but split collecting and reporting (perhaps on two different computers)
.PP
.RS
kcov --collect-only /tmp/kcov ./frodo
.PP
kcov --report-only \-\-include\-pattern=src/frodo /tmp/kcov ./frodo
.RE
.SH HTML OUTPUT
.PP
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.
.PP
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.
.SH COBERTURA OUTPUT
.PP
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).
.PP
The Cobertura output is placed in a file named out-path/exec-filename/cobertura.xml.
.SH JSON OUTPUT
.PP
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).
.PP
The JSON output is placed in a file named out-path/exec-filename/coverage.json.
.SH AUTHOR
.PP
Kcov was written by Simon Kagstrom, building upon bcov by Thomas Neumann.
.PP
This manual page was written by Michael Tautschnig <mt@debian.org>,
for the Debian project (but may be used by others).