kcov

KCOV(1)                     General Commands Manual                    KCOV(1)



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)