.\" 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 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-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. See the GitHub page, https://github.com/SimonKagstrom/kcov, for more documentation. .\" TeX users may be more comfortable with the \fB\fP and .\" \fI\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\-\-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. .TP \fB\-\-bash\-parse\-files\-in\-dir\fP=\fIP1\fP[\fI,P2\fP...] Parse directories for bash scripts. .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. See doc/full-system-instrumentation.md for more information on full-system instrumentation. .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 , for the Debian project (but may be used by others).