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

FreeBSD Manual Pages

  
 
  

home | help
LLVM-COV(1)			     LLVM			   LLVM-COV(1)

NAME
       llvm-cov	- emit coverage	information

SYNOPSIS
       llvm-cov	command	[args...]

DESCRIPTION
       The llvm-cov tool shows code coverage information for programs that are
       instrumented to emit  profile  data.  It	 can  be  used	to  work  with
       gcov-style coverage or with clang's instrumentation based profiling.

       If  the	program	is invoked with	a base name of gcov, it	will behave as
       if the llvm-cov gcov command were called. Otherwise, a  command	should
       be provided.

COMMANDS
       o gcov

       o show

       o report

       o export

GCOV COMMAND
   SYNOPSIS
       llvm-cov	gcov [options] SOURCEFILE

   DESCRIPTION
       The  llvm-cov gcov tool reads code coverage data	files and displays the
       coverage	information for	a specified source file. It is compatible with
       the  gcov  tool from version 4.2	of GCC and may also be compatible with
       some later versions of gcov.

       To use llvm-cov gcov, you must first build an instrumented  version  of
       your  application  that collects	coverage data as it runs. Compile with
       the -fprofile-arcs and -ftest-coverage options to add the  instrumenta-
       tion. (Alternatively, you can use the --coverage	option,	which includes
       both of those other options.) You should	compile	with debugging	infor-
       mation  (-g)  and  without  optimization	(-O0); otherwise, the coverage
       data cannot be accurately mapped	back to	the source code.

       At the time you compile the instrumented	code, a	.gcno data  file  will
       be  generated  for  each	object file. These .gcno files contain half of
       the coverage data. The other half of the	data comes  from  .gcda	 files
       that  are generated when	you run	the instrumented program, with a sepa-
       rate .gcda file for each	object file. Each time you  run	 the  program,
       the  execution  counts  are summed into any existing .gcda files, so be
       sure to remove any old files if you do not want their  contents	to  be
       included.

       By  default, the	.gcda files are	written	into the same directory	as the
       object files, but you can override that by setting the GCOV_PREFIX  and
       GCOV_PREFIX_STRIP environment variables.	The GCOV_PREFIX_STRIP variable
       specifies a number of directory components to be	removed	from the start
       of  the	absolute  path	to  the	object file directory. After stripping
       those directories, the prefix from the GCOV_PREFIX variable  is	added.
       These  environment  variables allow you to run the instrumented program
       on a machine where the original object file directories are not	acces-
       sible,  but  you	will then need to copy the .gcda files back to the ob-
       ject file directories where llvm-cov gcov expects to find them.

       Once you	have generated the coverage data files,	run llvm-cov gcov  for
       each  main  source file where you want to examine the coverage results.
       This should be run from the same	directory where	you previously ran the
       compiler.  The  results	for the	specified source file are written to a
       file named by appending a .gcov suffix. A separate output file is  also
       created	for  each  file	 included by the main source file, also	with a
       .gcov suffix added.

       The basic content of an .gcov output file is a copy of the source  file
       with  an	 execution  count and line number prepended to every line. The
       execution count is shown	as - if	a line does not	contain	any executable
       code.  If  a  line  contains code but that code was never executed, the
       count is	displayed as #####.

   OPTIONS
       -a, --all-blocks
	      Display all basic	blocks.	If there are  multiple	blocks	for  a
	      single  line of source code, this	option causes llvm-cov to show
	      the count	for each block instead of just one count for  the  en-
	      tire line.

       -b, --branch-probabilities
	      Display conditional branch probabilities and a summary of	branch
	      information.

       -c, --branch-counts
	      Display branch counts instead of probabilities (requires -b).

       -f, --function-summaries
	      Show a summary of	coverage for each function instead of just one
	      summary for an entire source file.

       --help Display available	options	(--help-hidden for more).

       -l, --long-file-names
	      For coverage output of files included from the main source file,
	      add the main file	name followed by ## as a prefix	to the	output
	      file  names.  This can be	combined with the --preserve-paths op-
	      tion to use complete paths for both the main file	 and  the  in-
	      cluded file.

       -n, --no-output
	      Do not output any	.gcov files. Summary information is still dis-
	      played.

       -o=<DIR|FILE>, --object-directory=<DIR>,	--object-file=<FILE>
	      Find objects in DIR or based on FILE's path. If  you  specify  a
	      particular  object file, the coverage data files are expected to
	      have the same base name with .gcno and .gcda extensions. If  you
	      specify  a  directory,  the files	are expected in	that directory
	      with the same base name as the source file.

       -p, --preserve-paths
	      Preserve path components when naming the coverage	output	files.
	      In  addition  to	the  source file name, include the directories
	      from the path to that file. The directories are  separate	 by  #
	      characters,  with	 .  directories	removed	and .. directories re-
	      placed by	^ characters. When used	with the --long-file-names op-
	      tion,  this  applies to both the main file name and the included
	      file name.

       -u, --unconditional-branches
	      Include  unconditional  branches	 in   the   output   for   the
	      --branch-probabilities option.

       -version
	      Display the version of llvm-cov.

       -x, --hash-filenames
	      Use md5 hash of file name	when naming the	coverage output	files.
	      The source file name will	be suffixed by ## followed by MD5 hash
	      calculated for it.

   EXIT	STATUS
       llvm-cov	 gcov  returns 1 if it cannot read input files.	 Otherwise, it
       exits with zero.

SHOW COMMAND
   SYNOPSIS
       llvm-cov	show [options] -instr-profile PROFILE  BIN  [-object  BIN,...]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  show command shows line by line coverage of the binaries
       BIN,...	using the profile data PROFILE.	It can optionally be  filtered
       to only show the	coverage for the files listed in SOURCES.

       BIN  may	 be  an	 executable,  object file, dynamic library, or archive
       (thin or	otherwise).

       To use llvm-cov show, you need a	program	that is	compiled with  instru-
       mentation  to  emit  profile and	coverage data. To build	such a program
       with clang  use	the  -fprofile-instr-generate  and  -fcoverage-mapping
       flags.  If linking with the clang driver, pass -fprofile-instr-generate
       to the link stage to make sure  the  necessary  runtime	libraries  are
       linked in.

       The  coverage  information is stored in the built executable or library
       itself, and this	is what	you should pass	to llvm-cov show as a BIN  ar-
       gument. The profile data	is generated by	running	this instrumented pro-
       gram normally. When the program exits it	will write out a  raw  profile
       file,  typically	 called	 default.profraw,  which can be	converted to a
       format that is suitable for the PROFILE argument	using  the  llvm-prof-
       data merge tool.

   OPTIONS
       -show-line-counts
	      Show  the	 execution counts for each line. Defaults to true, un-
	      less another -show option	is used.

       -show-expansions
	      Expand inclusions, such as preprocessor macros or	textual	inclu-
	      sions,  inline  in  the  display of the source file. Defaults to
	      false.

       -show-instantiations
	      For source regions that are instantiated multiple	times, such as
	      templates	 in C++, show each instantiation separately as well as
	      the combined summary.  Defaults to true.

       -show-regions
	      Show the execution counts	for each region	by displaying a	 caret
	      that  points  to the character where the region starts. Defaults
	      to false.

       -show-line-counts-or-regions
	      Show the execution counts	for each line if there is only one re-
	      gion  on	the line, but show the individual regions if there are
	      multiple on the line.  Defaults to false.

       -use-color
	      Enable or	disable	color output. By default this is autodetected.

       -arch=[*NAMES*]
	      Specify a	list of	architectures such that	the Nth	entry  in  the
	      list corresponds to the Nth specified binary. If the covered ob-
	      ject is a	universal binary, this specifies the  architecture  to
	      use.  It	is an error to specify an architecture that is not in-
	      cluded in	the universal binary or	to use	an  architecture  that
	      does not match a non-universal binary.

       -name=<NAME>
	      Show code	coverage only for functions with the given name.

       -name-whitelist=<FILE>
	      Show  code coverage only for functions listed in the given file.
	      Each line	in the file should start with whitelist_fun:,  immedi-
	      ately  followed by the name of the function to accept. This name
	      can be a wildcard	expression.

       -name-regex=<PATTERN>
	      Show code	coverage only for functions that match the given regu-
	      lar expression.

       -ignore-filename-regex=<PATTERN>
	      Skip source code files with file paths that match	the given reg-
	      ular expression.

       -format=<FORMAT>
	      Use the specified	output	format.	 The  supported	 formats  are:
	      "text", "html".

       -tab-size=<TABSIZE>
	      Replace  tabs with <TABSIZE> spaces when preparing reports. Cur-
	      rently, this is only supported for the html format.

       -output-dir=PATH
	      Specify a	directory to write coverage reports into. If  the  di-
	      rectory  does  not  exist,  it is	created. When used in function
	      view mode	(i.e when -name	or -name-regex are used	to select spe-
	      cific functions),	the report is written to PATH/functions.EXTEN-
	      SION. When used in file view mode, a report  for	each  file  is
	      written to PATH/REL_PATH_TO_FILE.EXTENSION.

       -Xdemangler=<TOOL>|<TOOL-OPTION>
	      Specify  a  symbol  demangler.  This can be used to make reports
	      more human-readable. This	option can be specified	multiple times
	      to  supply  arguments  to	the demangler (e.g -Xdemangler c++filt
	      -Xdemangler -n for C++).	The demangler is expected  to  read  a
	      newline-separated	 list  of  symbols from	stdin and write	a new-
	      line-separated list of the same length to	stdout.

       -num-threads=N, -j=N
	      Use N threads to write file reports (only	applicable when	 -out-
	      put-dir is specified). When N=0, llvm-cov	auto-detects an	appro-
	      priate number of threads to use. This is the default.

       -line-coverage-gt=<N>
	      Show code	coverage only for functions with line coverage greater
	      than the given threshold.

       -line-coverage-lt=<N>
	      Show  code  coverage  only for functions with line coverage less
	      than the given threshold.

       -region-coverage-gt=<N>
	      Show code	coverage  only	for  functions	with  region  coverage
	      greater than the given threshold.

       -region-coverage-lt=<N>
	      Show  code coverage only for functions with region coverage less
	      than the given threshold.

       -path-equivalence=<from>,<to>
	      Map the paths in the coverage data to local source  file	paths.
	      This  allows  you	 to generate the coverage data on one machine,
	      and then use llvm-cov on a different machine where you have  the
	      same files on a different	path.

REPORT COMMAND
   SYNOPSIS
       llvm-cov	 report	[options] -instr-profile PROFILE BIN [-object BIN,...]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The llvm-cov report command displays a summary of the coverage  of  the
       binaries	 BIN,...  using	the profile data PROFILE. It can optionally be
       filtered	to only	show the coverage for the files	listed in SOURCES.

       BIN may be an executable, object	 file,	dynamic	 library,  or  archive
       (thin or	otherwise).

       If  no  source  files  are provided, a summary line is printed for each
       file in the coverage data. If any files are provided, summaries can  be
       shown  for each function	in the listed files if the -show-functions op-
       tion is enabled.

       For information on compiling programs for coverage and generating  pro-
       file data, see SHOW COMMAND.

   OPTIONS
       -use-color[=VALUE]
	      Enable or	disable	color output. By default this is autodetected.

       -arch=<name>
	      If  the  covered binary is a universal binary, select the	archi-
	      tecture to use.  It is an	error to specify an architecture  that
	      is  not  included	in the universal binary	or to use an architec-
	      ture that	does not match a non-universal binary.

       -show-functions
	      Show coverage summaries for each function. Defaults to false.

       -show-instantiation-summary
	      Show statistics for all  function	 instantiations.  Defaults  to
	      false.

       -ignore-filename-regex=<PATTERN>
	      Skip source code files with file paths that match	the given reg-
	      ular expression.

EXPORT COMMAND
   SYNOPSIS
       llvm-cov	export [options] -instr-profile	PROFILE	BIN [-object  BIN,...]
       [[-object BIN]] [SOURCES]

   DESCRIPTION
       The  llvm-cov  export  command  exports	coverage  data of the binaries
       BIN,... using the profile data PROFILE in either	 JSON  or  lcov	 trace
       file format.

       When  exporting JSON, the regions, functions, expansions, and summaries
       of the coverage data will be exported. When  exporting  an  lcov	 trace
       file, the line-based coverage and summaries will	be exported.

       The  exported data can optionally be filtered to	only export the	cover-
       age for the files listed	in SOURCES.

       For information on compiling programs for coverage and generating  pro-
       file data, see SHOW COMMAND.

   OPTIONS
       -arch=<name>
	      If  the  covered binary is a universal binary, select the	archi-
	      tecture to use.  It is an	error to specify an architecture  that
	      is  not  included	in the universal binary	or to use an architec-
	      ture that	does not match a non-universal binary.

       -format=<FORMAT>
	      Use the specified	output	format.	 The  supported	 formats  are:
	      "text" (JSON), "lcov".

       -summary-only
	      Export  only  summary  information for each file in the coverage
	      data. This mode will not export coverage information for smaller
	      units  such  as individual functions or regions. The result will
	      contain the same information as produced by the llvm-cov	report
	      command, but presented in	JSON or	lcov format rather than	text.

       -ignore-filename-regex=<PATTERN>
	      Skip source code files with file paths that match	the given reg-
	      ular expression.

	      -skip-expansions

	      Skip exporting macro expansion coverage data.

	      -skip-functions

	      Skip exporting per-function coverage data.

	      -num-threads=N, -j=N

	      Use N threads  to	 export	 coverage  data.  When	N=0,  llvm-cov
	      auto-detects  an	appropriate  number of threads to use. This is
	      the default.

AUTHOR
       Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT
       2003-2020, LLVM Project

10				  2020-08-24			   LLVM-COV(1)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | GCOV COMMAND | SHOW COMMAND | REPORT COMMAND | EXPORT COMMAND | AUTHOR | COPYRIGHT

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

home | help