Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  exe-
	      cutable  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  re-
	      port.

       --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  perfor-
	      mance)

       --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-sys-
	      tem-instrumentation.md  for  more	information on full-system in-
	      strumentation.

       --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  dif-
       ferent 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	 exam-
       ple 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	 inte-
       grating	 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-file-
       name/cobertura.xml.

JSON OUTPUT
       Kcov generates a	very generic json file which includes the overall per-
       cent covered for	a single command and the count of  lines  instrumented
       and covered. It also includes a summary of each source file with	a per-
       centage 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/cover-
       age.json.

AUTHOR
       Kcov was	written	by Simon Kagstrom, building upon bcov by  Thomas  Neu-
       mann.

       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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | UNCOMMON OPTIONS | EXAMPLES | HTML OUTPUT | COBERTURA OUTPUT | JSON OUTPUT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=kcov&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help