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

FreeBSD Manual Pages


home | help
KCOV(1)			    General Commands Manual		       KCOV(1)

       kcov - Code coverage analysis for compiled programs and Python scripts

       kcov [options] outdir executable	[args-for-executable...]

       kcov --merge outdir _path-to-coverage_ [path-to-more-coverage...]

       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,, for more

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

	      Comma-separated list of paths to include in the report.

	      Comma-separated list of paths to exclude from the	report.

	      Comma-separated list of path patterns to include in the report.

	      Comma-separated list of path patterns to exclude	from  the  re-

	      Comma-separated  list  of	line patterns to exclude (mark as non-

	      Comma-separated list of regions of  lines	 patterns  to  exclude
	      (mark  as	 non-code). The	region begins with START and ends with

	      Only collect coverage data, don't	produce	HTML/Cobertura output.

	      Only report HTML/Cobertura output, don't collect data.

	      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.

	      Upload data to 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.

	      Number of	path levels to show for	common paths (default: 2).

	      Skip coverage collection for shared libraries (improves  perfor-

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

	      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.

	      Set  the	bash  parser  to use for shell scripts (the default is

	      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.

	      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.

	      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.

	      Parse directories	for bash scripts.

	      Replace source file path P1 with P2, if found.

	      Perform  full-system  instrumentation  on	 a sysroot, outputting
	      patched binaries which collect coverage data. See	 doc/full-sys-  for  more	information on full-system in-

	      Produce coverage output for a full-system	coverage run.

       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

       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.

       Kcov also outputs data in the Cobertura XML format, which allows	 inte-
       grating	 kcov  output  in  Jenkins  (see  and

       The Cobertura output is placed  in  a  file  named  out-path/exec-file-

       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

       The JSON	output is placed in a file named out-path/exec-filename/cover-

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

       This manual page	was written by Michael Tautschnig <>, for
       the Debian project (but may be used by others).

			      November	24, 2011		       KCOV(1)


Want to link to this manual page? Use this URL:

home | help