Ubuntu Manpage: kcov - Code coverage analysis for compiled programs and Python scripts

NAME

       kcov - Code coverage analysis for compiled programs and Python scripts

SYNOPSIS

       kcov [options] out-dir in-file [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: 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.

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.

--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).

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 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.

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).

                                          July  8, 2024                                   KCOV(1)