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

FreeBSD Manual Pages

  
 
  

home | help
geninfo(1)			 User Manuals			    geninfo(1)

NAME
       geninfo - Generate tracefiles from .da files

SYNOPSIS
       geninfo [-h|--help] [-v|--version] [-q|--quiet]
	       [-i|--initial] [-t|--test-name test-name]
	       [-o|--output-filename filename] [-f|--follow]
	       [-b|--base-directory directory]
	       [--checksum] [--no-checksum]
	       [--compat-libtool] [--no-compat-libtool]
	       [--gcov-tool tool] [--ignore-errors errors]
	       [--no-recursion]	directory [--external] [--no-external]
	       [--config-file config-file] [--no-markers]
	       [--derive-func-data] [--compat mode=on|off|auto]
	       [--rc keyword=value]
	       [--include pattern] [--exclude pattern]

DESCRIPTION
       geninfo	converts  all GCOV coverage data files found in	directory into
       tracefiles, which the genhtml tool can convert to HTML output.

       Unless the --output-filename option is specified,  geninfo  writes  its
       output to one file per .da file,	the name of which is generated by sim-
       ply appending ".info" to	the respective .da file	name.

       Note that the current user needs	write access to	both directory as well
       as to the original source code location.	This is	necessary because some
       temporary files have to be created there	during the conversion process.

       Note also that geninfo is called	from within lcov,  so  that  there  is
       usually no need to call it directly.

       Exclusion markers

       To  exclude specific lines of code from a tracefile, you	can add	exclu-
       sion markers to the source code.	Additionally you can exclude  specific
       branches	from branch coverage without excluding the involved lines from
       line and	function coverage. Exclusion markers are  keywords  which  can
       for  example  be	 added in the form of a	comment.  See lcovrc(5)	how to
       override	some of	them.

       The following markers are recognized by geninfo:

       LCOV_EXCL_LINE
	      Lines containing this marker will	be excluded.
       LCOV_EXCL_START
	      Marks the	beginning of an	excluded section. The current line  is
	      part of this section.
       LCOV_EXCL_STOP
	      Marks  the end of	an excluded section. The current line not part
	      of this section.
       LCOV_EXCL_BR_LINE
	      Lines containing this marker will	be excluded from branch	cover-
	      age.
       LCOV_EXCL_BR_START
	      Marks  the  beginning of a section which is excluded from	branch
	      coverage.	The current line is part of this section.
       LCOV_EXCL_BR_STOP
	      Marks the	end of a section which is excluded from	branch	cover-
	      age. The current line not	part of	this section.

OPTIONS
       -b directory
       --base-directory	directory
	      Use directory as base directory for relative paths.

	      Use  this	 option	to specify the base directory of a build-envi-
	      ronment when geninfo produces error messages like:

		     ERROR: could not read source file /home/user/project/sub-
		     dir1/subdir2/subdir1/subdir2/file.c

	      In this example, use /home/user/project as base directory.

	      This  option  is	required  when using geninfo on	projects built
	      with libtool or similar build environments that work with	a base
	      directory,  i.e.	environments, where the	current	working	direc-
	      tory when	invoking the compiler is not  the  same	 directory  in
	      which the	source code file is located.

	      Note that	this option will not work in environments where	multi-
	      ple base directories are used. In	that  case  use	 configuration
	      file setting geninfo_auto_base=1 (see lcovrc(5)).

       --checksum
       --no-checksum
	      Specify  whether	to  generate checksum data when	writing	trace-
	      files.

	      Use --checksum to	enable checksum	generation or --no-checksum to
	      disable it. Checksum generation is disabled by default.

	      When  checksum  generation is enabled, a checksum	will be	gener-
	      ated for each source code	line and stored	along with the	cover-
	      age data.	This checksum will be used to prevent attempts to com-
	      bine coverage data from different	source code versions.

	      If you don't work	with different source code  versions,  disable
	      this  option  to speed up	coverage data processing and to	reduce
	      the size of tracefiles.

       --compat	mode=value[,mode=value,...]
	      Set compatibility	mode.

	      Use --compat to specify that geninfo should enable one  or  more
	      compatibility  modes  when capturing coverage data. You can pro-
	      vide a comma-separated list of mode=value	pairs to  specify  the
	      values for multiple modes.

	      Valid values are:

	      on
		     Enable compatibility mode.
	      off
		     Disable compatibility mode.
	      auto
		     Apply  auto-detection  to determine if compatibility mode
		     is	required. Note that auto-detection  is	not  available
		     for all compatibility modes.

	      If no value is specified,	'on' is	assumed	as default value.

	      Valid modes are:

	      libtool
		     Enable this mode if you are capturing coverage data for a
		     project that was built using the libtool  mechanism.  See
		     also --compat-libtool.

		     The default value for this	setting	is 'on'.

	      hammer
		     Enable this mode if you are capturing coverage data for a
		     project that was built using a version of	GCC  3.3  that
		     contains  a modification (hammer patch) of	later GCC ver-
		     sions. You	can identify a modified	GCC  3.3  by  checking
		     the  build	 directory of your project for files ending in
		     the extension '.bbg'. Unmodified versions of GCC 3.3 name
		     these files '.bb'.

		     The default value for this	setting	is 'auto'.

	      split_crc
		     Enable this mode if you are capturing coverage data for a
		     project that was built using a version of	GCC  4.6  that
		     contains  a  modification	(split	function checksums) of
		     later GCC versions. Typical error messages	 when  running
		     geninfo  on  coverage  data produced by such GCC versions
		     are 'out of memory' and 'reached unexpected end of	file'.

		     The default value for this	setting	is 'auto'

       --compat-libtool
       --no-compat-libtool
	      Specify whether to enable	libtool	compatibility mode.

	      Use --compat-libtool to enable  libtool  compatibility  mode  or
	      --no-compat-libtool  to  disable	it.  The libtool compatibility
	      mode is enabled by default.

	      When libtool compatibility mode is enabled, geninfo will	assume
	      that  the	source code relating to	a .da file located in a	direc-
	      tory named ".libs" can be	found in its parent directory.

	      If you have directories named ".libs" in your build  environment
	      but  don't  use libtool, disable this option to prevent problems
	      when capturing coverage data.

       --config-file config-file
	      Specify a	configuration file to use.

	      When this	option is specified, neither the system-wide  configu-
	      ration  file  /etc/lcovrc,  nor  the per-user configuration file
	      ~/.lcovrc	is read.

	      This option may be useful	when there is a	need  to  run  several
	      instances	 of  geninfo with different configuration file options
	      in parallel.

       --derive-func-data
	      Calculate	function coverage data from line coverage data.

	      Use this option to collect function coverage data, even  if  the
	      version  of  the gcov tool installed on the test system does not
	      provide this data. lcov will instead  derive  function  coverage
	      data  from  line coverage	data and information about which lines
	      belong to	a function.

       --exclude pattern
	      Exclude source files matching pattern.

	      Use this switch if you want to exclude coverage data for a  par-
	      ticular  set of source files matching any	of the given patterns.
	      Multiple patterns	can be specified by using  multiple  --exclude
	      command line switches. The patterns will be interpreted as shell
	      wildcard patterns	(note that they	may need to be escaped accord-
	      ingly to prevent the shell from expanding	them first).

	      Can  be  combined	 with  the --include command line switch. If a
	      given file matches both the include pattern and the exclude pat-
	      tern, the	exclude	pattern	will take precedence.

       --external
       --no-external
	      Specify  whether	to  capture  coverage data for external	source
	      files.

	      External source files are	files which are	not located in one  of
	      the  directories	specified  by --directory or --base-directory.
	      Use --external to	include	external source	files while  capturing
	      coverage data or --no-external to	ignore this data.

	      Data for external	source files is	included by default.

       -f
       --follow
	      Follow links when	searching .da files.

       --gcov-tool tool
	      Specify the location of the gcov tool.

       -h
       --help
	      Print a short help text, then exit.

       --include pattern
	      Include source files matching pattern.

	      Use  this	switch if you want to include coverage data for	only a
	      particular set of	source files matching any of  the  given  pat-
	      terns.  Multiple	patterns  can  be  specified by	using multiple
	      --include	command	line switches. The  patterns  will  be	inter-
	      preted as	shell wildcard patterns	(note that they	may need to be
	      escaped accordingly to prevent the  shell	 from  expanding  them
	      first).

       --ignore-errors errors
	      Specify a	list of	errors after which to continue processing.

	      Use  this	option to specify a list of one	or more	classes	of er-
	      rors after which geninfo should continue processing  instead  of
	      aborting.

	      errors can be a comma-separated list of the following keywords:

	      gcov: the	gcov tool returned with	a non-zero return code.

	      source: the source code file for a data set could	not be found.

       -i
       --initial
	      Capture initial zero coverage data.

	      Run  geninfo with	this option on the directories containing .bb,
	      .bbg or .gcno files before running any test case.	The result  is
	      a	 "baseline" coverage data file that contains zero coverage for
	      every instrumented line and function.  Combine  this  data  file
	      (using  lcov  -a)	with coverage data files captured after	a test
	      run to ensure that the percentage	of total lines covered is cor-
	      rect  even when not all object code files	were loaded during the
	      test.

	      Note: currently, the --initial option does not  generate	branch
	      coverage information.

       --no-markers
	      Use  this	option if you want to get coverage data	without	regard
	      to exclusion markers in the source code file.

       --no-recursion
	      Use this option if you want to get coverage data for the	speci-
	      fied directory only without processing subdirectories.

       -o output-filename
       --output-filename output-filename
	      Write all	data to	output-filename.

	      If  you want to have all data written to a single	file (for eas-
	      ier handling), use this option to	specify	the  respective	 file-
	      name.  By	 default,  one tracefile will be created for each pro-
	      cessed .da file.

       -q
       --quiet
	      Do not print progress messages.

	      Suppresses all informational progress output. When  this	switch
	      is enabled, only error or	warning	messages are printed.

       --rc keyword=value
	      Override a configuration directive.

	      Use this option to specify a keyword=value statement which over-
	      rides the	corresponding configuration statement  in  the	lcovrc
	      configuration  file.  You	can specify this option	more than once
	      to override multiple configuration  statements.	See  lcovrc(5)
	      for a list of available keywords and their meaning.

       -t testname
       --test-name testname
	      Use  test	case name testname for resulting data. Valid test case
	      names can	consist	of letters, decimal digits and the  underscore
	      character	('_').

	      This  proves  useful when	data from several test cases is	merged
	      (i.e. by simply  concatenating  the  respective  tracefiles)  in
	      which case a test	name can be used to differentiate between data
	      from each	test case.

       -v
       --version
	      Print version number, then exit.

FILES
       /etc/lcovrc
	      The system-wide configuration file.

       ~/.lcovrc
	      The per-user configuration file.

       Following is a quick description	of the tracefile  format  as  used  by
       genhtml,	geninfo	and lcov.

       A tracefile is made up of several human-readable	lines of text, divided
       into sections. If available, a tracefile	begins with the	testname which
       is stored in the	following format:

	 TN:<test name>

       For  each  source  file	referenced in the .da file, there is a section
       containing filename and coverage	data:

	 SF:<absolute path to the source file>

       Following is a list of line numbers for each function name found	in the
       source file:

	 FN:<line number of function start>,<function name>

       Next,  there  is	a list of execution counts for each instrumented func-
       tion:

	 FNDA:<execution count>,<function name>

       This list is followed by	two lines containing the number	 of  functions
       found and hit:

	 FNF:<number of	functions found>
	 FNH:<number of	function hit>

       Branch coverage information is stored which one line per	branch:

	 BRDA:<line number>,<block number>,<branch number>,<taken>

       Block  number  and  branch  number are gcc internal IDs for the branch.
       Taken is	either '-' if the basic	block containing the branch was	 never
       executed	or a number indicating how often that branch was taken.

       Branch coverage summaries are stored in two lines:

	 BRF:<number of	branches found>
	 BRH:<number of	branches hit>

       Then  there  is	a  list	of execution counts for	each instrumented line
       (i.e. a line which resulted in executable code):

	 DA:<line number>,<execution count>[,<checksum>]

       Note that there may be an optional checksum present  for	 each  instru-
       mented  line.  The  current  geninfo implementation uses	an MD5 hash as
       checksumming algorithm.

       At the end of a section,	there is a summary about how many  lines  were
       found and how many were actually	instrumented:

	 LH:<number of lines with a non-zero execution count>
	 LF:<number of instrumented lines>

       Each sections ends with:

	 end_of_record

       In  addition  to	 the  main source code file there are sections for all
       #included files which also contain executable code.

       Note that the absolute path of a	source file is generated by interpret-
       ing  the	contents of the	respective .bb file (see gcov (1) for more in-
       formation on this file type). Relative filenames	are prefixed with  the
       directory in which the .bb file is found.

       Note  also that symbolic	links to the .bb file will be resolved so that
       the actual file path is used instead of the path	to a  link.  This  ap-
       proach  is  necessary  for  the	mechanism  to work with	the /proc/gcov
       files.

AUTHOR
       Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com>

SEE ALSO
       lcov(1),	lcovrc(5), genhtml(1), genpng(1), gendesc(1), gcov(1)

2019-02-28			   LCOV	1.14			    geninfo(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | AUTHOR | SEE ALSO

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

home | help