.\" 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, or through a wildcard (*) .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\-\-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. .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).