From 3cb9a864b698c2894c8af84010612ee87759fac5 Mon Sep 17 00:00:00 2001 From: Henry Cox Date: Thu, 14 May 2026 18:26:52 -0400 Subject: [PATCH] Generate documentation from RST, modify testcase directory structure, fix various typos. Signed-off-by: Henry Cox --- .github/workflows/run_test_suite.yml | 2 + Makefile | 46 +- README | 580 --- README.rst | 629 +++ bin/genhtml | 4 +- bin/lcov | 6 +- bin/xml2lcovutil.py | 16 +- docs/Makefile | 22 + docs/_static/.gitkeep | 0 docs/conf.py | 353 ++ docs/index.rst | 7 + docs/man/gendesc.rst | 72 + docs/man/genhtml.rst | 1705 ++++++++ docs/man/geninfo.rst | 946 ++++ docs/man/genpng.rst | 81 + docs/man/lcov.rst | 1513 +++++++ docs/man/lcovrc.rst | 1862 ++++++++ docs/man/llvm2lcov.rst | 132 + docs/man/perl2lcov.rst | 111 + docs/man/py2lcov.rst | 182 + docs/man/spreadsheet.rst | 140 + docs/scripts.rst | 632 +++ example/Makefile | 4 +- example/README | 81 - example/README.rst | 79 + lcovrc | 4 +- lib/lcovutil.pm | 50 +- man/gendesc.1 | 85 - man/genhtml.1 | 3890 ----------------- man/geninfo.1 | 2082 --------- man/genpng.1 | 115 - man/lcov.1 | 1992 --------- man/lcovrc.5 | 3238 -------------- scripts/P4version.pm | 2 +- scripts/annotateutil.pm | 2 +- scripts/batchGitVersion.pm | 4 +- scripts/get_signature | 2 +- scripts/gitblame.pm | 2 +- scripts/gitdiff | 6 +- scripts/p4annotate.pm | 6 +- scripts/p4udiff | 19 +- scripts/simplify.pm | 2 +- scripts/spreadsheet.py | 9 +- scripts/threshold.pm | 2 +- tests/Makefile | 2 +- tests/gendiffcov/Makefile | 3 - tests/genhtml/Makefile | 3 +- tests/genhtml/demangle.sh | 2 +- tests/{gendiffcov => genhtml}/errs/Makefile | 0 .../errs/MsgContext.pm | 0 .../{gendiffcov => genhtml}/errs/genError.pm | 0 .../errs/mcdc_errs.dat | 0 .../errs/missingRestore.pm | 0 tests/{gendiffcov => genhtml}/errs/msgtest.sh | 48 +- .../errs/parallelFail.pm | 0 tests/{gendiffcov => genhtml}/errs/select.sh | 0 tests/genhtml/exception/exception.sh | 4 +- tests/{gendiffcov => genhtml}/filter/Makefile | 0 tests/{gendiffcov => genhtml}/filter/brace.c | 0 .../{gendiffcov => genhtml}/filter/brace.info | 0 tests/{gendiffcov => genhtml}/filter/expr1.c | 0 tests/{gendiffcov => genhtml}/filter/expr2.c | 0 tests/{gendiffcov => genhtml}/filter/expr3.c | 0 tests/{gendiffcov => genhtml}/filter/expr4.c | 0 .../{gendiffcov => genhtml}/filter/filter.pl | 3 +- .../filter/multilineTrivial.c | 0 .../filter/multilineTrivial2.c | 0 .../filter/notTrivial1.c | 0 .../filter/notTrivial2.c | 0 .../filter/notTrivial3.c | 0 .../filter/notTrivial_init.c | 0 .../filter/notTrivial_multiline.c | 0 .../{gendiffcov => genhtml}/filter/trivial1.c | 0 .../{gendiffcov => genhtml}/filter/trivial2.c | 0 .../{gendiffcov => genhtml}/filter/trivial3.c | 0 .../filter/trivialMethod.c | 0 .../{gendiffcov => genhtml}/function/Makefile | 0 .../function/baseline_call_current_call.gold | 0 .../baseline_call_current_call_region.gold | 0 .../baseline_call_current_nocall.gold | 0 .../baseline_call_current_nocall_region.gold | 0 .../baseline_nocall_current_call.gold | 0 .../baseline_nocall_current_call_region.gold | 0 .../baseline_nocall_current_nocall.gold | 0 ...baseline_nocall_current_nocall_region.gold | 0 .../function/current.cpp | 0 .../function/function.sh | 2 +- .../function/initial.cpp | 0 .../function/template.cpp | 0 .../insensitive/Makefile | 0 .../insensitive/annotate.sh | 0 .../insensitive/insensitive.sh | 4 +- .../insensitive/version.sh | 0 tests/{gendiffcov => genhtml}/simple/Makefile | 0 .../simple/annotate.sh | 2 +- .../{gendiffcov => genhtml}/simple/script.sh | 28 +- .../{gendiffcov => genhtml}/simple/simple.cpp | 0 .../simple/simple2.cpp | 0 .../simple/simple2.cpp.annotated | 0 .../simple/unreach.cpp | 0 .../synthesize/Makefile | 0 .../synthesize/munge.pl | 0 .../synthesize/munge2.pl | 0 .../synthesize/synthesize.sh | 4 +- tests/lcov/demangle/demangle.sh | 14 +- tests/lcov/errs/errs.sh | 4 +- tests/lcov/exception/exception.sh | 24 +- tests/lcov/extract/extract.sh | 14 +- tests/lcov/extract/fakeResolve.sh | 2 +- tests/lcov/format/format.sh | 2 +- tests/lcov/summary/full.sh | 2 +- tests/perl2lcov/perltest1.sh | 11 +- tests/py2lcov/py2lcov.sh | 2 +- 113 files changed, 8663 insertions(+), 12234 deletions(-) delete mode 100644 README create mode 100644 README.rst create mode 100644 docs/Makefile create mode 100644 docs/_static/.gitkeep create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/man/gendesc.rst create mode 100644 docs/man/genhtml.rst create mode 100644 docs/man/geninfo.rst create mode 100644 docs/man/genpng.rst create mode 100644 docs/man/lcov.rst create mode 100644 docs/man/lcovrc.rst create mode 100644 docs/man/llvm2lcov.rst create mode 100644 docs/man/perl2lcov.rst create mode 100644 docs/man/py2lcov.rst create mode 100644 docs/man/spreadsheet.rst create mode 100644 docs/scripts.rst delete mode 100644 example/README create mode 100644 example/README.rst delete mode 100644 man/gendesc.1 delete mode 100644 man/genhtml.1 delete mode 100644 man/geninfo.1 delete mode 100644 man/genpng.1 delete mode 100644 man/lcov.1 delete mode 100644 man/lcovrc.5 delete mode 100644 tests/gendiffcov/Makefile rename tests/{gendiffcov => genhtml}/errs/Makefile (100%) rename tests/{gendiffcov => genhtml}/errs/MsgContext.pm (100%) rename tests/{gendiffcov => genhtml}/errs/genError.pm (100%) rename tests/{gendiffcov => genhtml}/errs/mcdc_errs.dat (100%) rename tests/{gendiffcov => genhtml}/errs/missingRestore.pm (100%) rename tests/{gendiffcov => genhtml}/errs/msgtest.sh (94%) rename tests/{gendiffcov => genhtml}/errs/parallelFail.pm (100%) rename tests/{gendiffcov => genhtml}/errs/select.sh (100%) rename tests/{gendiffcov => genhtml}/filter/Makefile (100%) rename tests/{gendiffcov => genhtml}/filter/brace.c (100%) rename tests/{gendiffcov => genhtml}/filter/brace.info (100%) rename tests/{gendiffcov => genhtml}/filter/expr1.c (100%) rename tests/{gendiffcov => genhtml}/filter/expr2.c (100%) rename tests/{gendiffcov => genhtml}/filter/expr3.c (100%) rename tests/{gendiffcov => genhtml}/filter/expr4.c (100%) rename tests/{gendiffcov => genhtml}/filter/filter.pl (99%) rename tests/{gendiffcov => genhtml}/filter/multilineTrivial.c (100%) rename tests/{gendiffcov => genhtml}/filter/multilineTrivial2.c (100%) rename tests/{gendiffcov => genhtml}/filter/notTrivial1.c (100%) rename tests/{gendiffcov => genhtml}/filter/notTrivial2.c (100%) rename tests/{gendiffcov => genhtml}/filter/notTrivial3.c (100%) rename tests/{gendiffcov => genhtml}/filter/notTrivial_init.c (100%) rename tests/{gendiffcov => genhtml}/filter/notTrivial_multiline.c (100%) rename tests/{gendiffcov => genhtml}/filter/trivial1.c (100%) rename tests/{gendiffcov => genhtml}/filter/trivial2.c (100%) rename tests/{gendiffcov => genhtml}/filter/trivial3.c (100%) rename tests/{gendiffcov => genhtml}/filter/trivialMethod.c (100%) rename tests/{gendiffcov => genhtml}/function/Makefile (100%) rename tests/{gendiffcov => genhtml}/function/baseline_call_current_call.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_call_current_call_region.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_call_current_nocall.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_call_current_nocall_region.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_nocall_current_call.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_nocall_current_call_region.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_nocall_current_nocall.gold (100%) rename tests/{gendiffcov => genhtml}/function/baseline_nocall_current_nocall_region.gold (100%) rename tests/{gendiffcov => genhtml}/function/current.cpp (100%) rename tests/{gendiffcov => genhtml}/function/function.sh (99%) rename tests/{gendiffcov => genhtml}/function/initial.cpp (100%) rename tests/{gendiffcov => genhtml}/function/template.cpp (100%) rename tests/{gendiffcov => genhtml}/insensitive/Makefile (100%) rename tests/{gendiffcov => genhtml}/insensitive/annotate.sh (100%) rename tests/{gendiffcov => genhtml}/insensitive/insensitive.sh (96%) rename tests/{gendiffcov => genhtml}/insensitive/version.sh (100%) rename tests/{gendiffcov => genhtml}/simple/Makefile (100%) rename tests/{gendiffcov => genhtml}/simple/annotate.sh (98%) rename tests/{gendiffcov => genhtml}/simple/script.sh (98%) rename tests/{gendiffcov => genhtml}/simple/simple.cpp (100%) rename tests/{gendiffcov => genhtml}/simple/simple2.cpp (100%) rename tests/{gendiffcov => genhtml}/simple/simple2.cpp.annotated (100%) rename tests/{gendiffcov => genhtml}/simple/unreach.cpp (100%) rename tests/{gendiffcov => genhtml}/synthesize/Makefile (100%) rename tests/{gendiffcov => genhtml}/synthesize/munge.pl (100%) rename tests/{gendiffcov => genhtml}/synthesize/munge2.pl (100%) rename tests/{gendiffcov => genhtml}/synthesize/synthesize.sh (99%) diff --git a/.github/workflows/run_test_suite.yml b/.github/workflows/run_test_suite.yml index 4ccc39eb..f0f2940c 100644 --- a/.github/workflows/run_test_suite.yml +++ b/.github/workflows/run_test_suite.yml @@ -73,6 +73,8 @@ jobs: llvm # for command "llvm-profdata" python3-coverage # PyPI coverage python3-xlsxwriter # PyPI xlsxwriter + python3-sphinx # doc build + python3-sphinx-rtd-theme # doc build # Additional dependencies for "make check" libgd-perl # CPAN GD diff --git a/Makefile b/Makefile index 2ddaeb4e..6e9c7932 100644 --- a/Makefile +++ b/Makefile @@ -32,6 +32,8 @@ VERSION := $(shell bin/get_version.sh --version) RELEASE := $(shell bin/get_version.sh --release) FULL := $(shell bin/get_version.sh --full) +# Tool name - can be overridden from command line +TOOL_NAME ?= LCOV # Set this variable during 'make install' to specify the interpreters used in # installed scripts, or leave empty to keep the current interpreter. @@ -49,13 +51,15 @@ CFG_DIR := $(PREFIX)/etc BIN_DIR := $(PREFIX)/bin LIB_DIR := $(PREFIX)/lib/lcov MAN_DIR := $(PREFIX)/share/man -SHARE_DIR := $(PREFIX)/share/lcov/ +SHARE_DIR := $(PREFIX)/share/lcov +HTML_DIR := $(SHARE_DIR)/html SCRIPT_DIR := $(SHARE_DIR)/support-scripts CFG_INST_DIR := $(DESTDIR)$(CFG_DIR) BIN_INST_DIR := $(DESTDIR)$(BIN_DIR) LIB_INST_DIR := $(DESTDIR)$(LIB_DIR) MAN_INST_DIR := $(DESTDIR)$(MAN_DIR) +HTML_INST_DIR := $(DESTDIR)$(HTML_DIR) SHARE_INST_DIR := $(DESTDIR)$(SHARE_DIR) SCRIPT_INST_DIR := $(SHARE_INST_DIR)/support-scripts @@ -94,7 +98,7 @@ else .SILENT: endif -.PHONY: all info clean install uninstall rpms test +.PHONY: all info clean install uninstall rpms test doc all: info @@ -114,9 +118,14 @@ clean: $(RM) -r ./bin/__pycache__ $(MAKE) -C example -s clean $(MAKE) -C tests -s clean + $(MAKE) -C docs -s clean find . -name '*.tdy' -o -name '*.orig' | xargs rm -f -install: +doc: + $(MAKE) -C docs RELEASE=${VERSION} TOOL_NAME=$(TOOL_NAME) man html + find docs/_build -type d -exec chmod u+x {} \; # apparent permissions bug?? + +install: doc $(INSTALL) -d -m 755 $(BIN_INST_DIR) for b in $(EXES) ; do \ $(call echocmd," INSTALL $(BIN_INST_DIR)/$$b") \ @@ -148,21 +157,26 @@ install: for section in $(MAN_SECTIONS) ; do \ DEST=$(MAN_INST_DIR)/man$$section ; \ $(INSTALL) -d -m 755 $$DEST ; \ - for m in man/*.$$section ; do \ + for m in docs/_build/man/*.$$section ; do \ F=`basename $$m` ; \ $(call echocmd," INSTALL $$DEST/$$F") \ - $(INSTALL) -m 644 man/$$F $$DEST/$$F ; \ + $(INSTALL) -m 644 docs/_build/man/$$F $$DEST/$$F ; \ $(FIX) --version $(VERSION) --fixver --fixdate \ --fixscriptdir --scriptdir $(SCRIPT_DIR) \ --manpage $$DEST/$$F ; \ done ; \ done - mkdir -p $(SHARE_INST_DIR) + for f in `( cd ./docs/_build ; find html -type f )` ; do \ + DEST=$(SHARE_DIR)/`dirname $$f` ; \ + $(INSTALL) -d -m 755 $$DEST ; \ + $(INSTALL) -m 644 ./docs/_build/$$f $$DEST ; \ + done + for d in example tests ; do \ ( cd $$d ; make clean ) ; \ - find $$d -type d -exec mkdir -p "$(SHARE_INST_DIR){}" \; ; \ - find $$d -type f -exec $(INSTALL) -Dm 644 "{}" "$(SHARE_INST_DIR){}" \; ; \ - done ; + find $$d -type d -exec mkdir -p -m 755 "$(SHARE_INST_DIR)/{}" \; ; \ + find $$d -type f -exec $(INSTALL) -Dm 644 "{}" "$(SHARE_INST_DIR)/{}" \; ; \ + done @chmod -R ugo+x $(SHARE_INST_DIR)/tests/bin @find $(SHARE_INST_DIR)/tests \( -name '*.sh' -o -name '*.pl' \) -exec chmod ugo+x {} \; $(INSTALL) -d -m 755 $(CFG_INST_DIR) @@ -210,7 +224,7 @@ dist: lcov-$(VERSION).tar.gz lcov-$(VERSION)-$(RELEASE).noarch.rpm \ lcov-$(VERSION).tar.gz: $(FILES) $(call echocmd," DIST lcov-$(VERSION).tar.gz") $(RM) -r $(TMP_DIR)/lcov-$(VERSION) - mkdir -p $(TMP_DIR)/lcov-$(VERSION) + mkdir -p -m 755 $(TMP_DIR)/lcov-$(VERSION) cp -r $(DIST_CONTENT) $(TMP_DIR)/lcov-$(VERSION) ./bin/copy_dates.sh . $(TMP_DIR)/lcov-$(VERSION) $(MAKE) -s -C $(TMP_DIR)/lcov-$(VERSION) clean >/dev/null @@ -232,11 +246,11 @@ lcov-$(VERSION)-$(RELEASE).src.rpm: rpms rpms: lcov-$(VERSION).tar.gz $(call echocmd," DIST lcov-$(VERSION)-$(RELEASE).noarch.rpm") - mkdir -p $(TMP_DIR) - mkdir $(TMP_DIR)/BUILD - mkdir $(TMP_DIR)/RPMS - mkdir $(TMP_DIR)/SOURCES - mkdir $(TMP_DIR)/SRPMS + mkdir -p -m 755 $(TMP_DIR) + mkdir -m 755 $(TMP_DIR)/BUILD + mkdir -m 755 $(TMP_DIR)/RPMS + mkdir -m 755 $(TMP_DIR)/SOURCES + mkdir -m 755 $(TMP_DIR)/SRPMS cp lcov-$(VERSION).tar.gz $(TMP_DIR)/SOURCES ( \ cd $(TMP_DIR)/BUILD ; \ @@ -267,7 +281,7 @@ test: check # once without - so we can merge the result check: if [ "x$(COVERAGE)" != 'x' ] ; then \ - mkdir -p $(COVER_DB) ; \ + mkdir -p -m 755 $(COVER_DB) ; \ echo "*** Run once, force parallel ***" ; \ LCOV_FORCE_PARALLEL=1 $(MAKE) -s -C tests check LCOV_HOME=`pwd` ; \ LCOV_FORCE_PARALLEL=1 $(MAKE) -s -C example LCOV_HOME=`pwd` ; \ diff --git a/README b/README deleted file mode 100644 index a62bcbb2..00000000 --- a/README +++ /dev/null @@ -1,580 +0,0 @@ -------------------------------------------------- -- README file for the LTP GCOV extension (LCOV) - -- Last changes: 2026-03-15 -------------------------------------------------- - -Description ------------ - LCOV is a tool to manipulate and display information about what parts of a - program are actually executed (i.e. "covered") while running a particular test - case or set of testcases. LCOV consists of a set of Perl scripts which build on - the text output of various coverage tools - e.g., gcov, llvm-cov, Coverage.py, - Cobertura, Devel::Cover, Jacoco, etc. - to implement the following enhanced - functionality: - - * HTML based output: coverage rates are indicated using bar - graphs and specific colors in a hyperlinked coverage report, intended - to enable the user to quickly diagnose and address coverage issues. - - * Support for large projects: overview pages allow quick browsing of - coverage data by providing a hierarchical directory structure - view, a flat list of all source files in the project, or a three-level - detail view: directory, file and source code view. - - * Support for multiple languages - including C/C++, Perl, and Python. - - LCOV was initially designed to support Linux kernel coverage measurements, - but works as well for coverage measurements on standard user space - applications. - - LCOV supports differential coverage, as well as date- and owner-binning. - See: - https://arxiv.org/abs/2008.07947 - or - https://ieeexplore.ieee.org/document/9438597 - for a detailed explanation of the concepts and several possible use models. - - A video presentation of the basic ideas can be found at - http://doi.org/10.5281/zenodo.4653252 - - In addition, several other features and capabilities are available. See - section 6, below, for a brief description - and also see the man pages and - the test cases. - - -Further README contents ------------------------ - 1. Included files - 2. Installing LCOV - 3. Dependencies - 4. An example of how to access kernel coverage data - 5. An example of how to access coverage data for a user space program - 6. LCOV features - 7. Questions and Comments - 8. Filing a new issue - - - -1. Important files ------------------- - README - This README file - CHANGES - List of changes between releases - bin/lcov - Tool for capturing LCOV coverage data - bin/genhtml - Tool for creating HTML output from LCOV data - bin/gendesc - Tool for creating description files as used by genhtml - bin/perl2lcov - Tool to translate Perl Devel::Cover data to lcov format - bin/llvm2lcov - Tool to translate LLVM 'llvm-cov' JSON data to LCOV format - bin/py2lcov - Tool to translate Python Coverage.py to lcov format - bin/xml2lcov - Tool to translate Cobertura-like XML coverage data - to lcov format - bin/geninfo - Internal tool (creates LCOV data files) - bin/genpng - Internal tool (creates png overviews of source files) - lcovrc - LCOV configuration file - man - Directory containing man pages for included tools - example - Directory containing an example to demonstrate LCOV - tests - Directory containing lcov regression tests - Makefile - Makefile providing 'install' and 'uninstall' targets - - -2. Installing LCOV ------------------- -The LCOV package is available as either RPM or tarball from: - - https://github.com/linux-test-project/lcov/releases - -To install the tarball, unpack it to a directory and run: - - make install - -Use Git for the most recent (but possibly unstable) version: - - git clone https://github.com/linux-test-project/lcov.git - -Change to the resulting lcov directory and type: - - make install - -The default install location is /usr/local. Note that you may need to -have superuser permissions to write into system directories. - -To install in a different location - for example, your home directory, run: - - make PREFIX=$HOME/my_lcov install - -your PREFIX should be an absolute path. - -To run the LCOV regression test suite on your installation: - - $ cp -r $LCOV_HOME/share/test path/to/myTestDir - $ cd path/to/myTestDir - $ make [COVERAGE=1] - -If desired, you can collect coverage data for the LCOV module by setting -the COVERAGE makefile variable. -Note that the Devel::Cover package must be installed if COVERAGE is enabled -or if you want to use the perl2lcov utility. -To view the collected coverage information, point your browser to -.../lcov_coverage/index.html after running the tests. - -Note that the testcases are primarily intended to test LCOV functionality -and not to be easily readable tutorial examples. - -3. Dependencies: ----------------- - -The lcov module is implemented primarily in Perl - and requires both a -moderately up-to-date Perl installation and multiple Perl packages. - -These perl packages include: - - - Capture::Tiny - - DateTime - - Devel::Cover - - Devel::StackTrace - - Digest::MD5 - - File::Spec - - at least one flavor of JSON module. - In order of performance/preference: - - JSON::XS - - Cpanel::JSON::XS - - JSON::PP - - JSON - - Memory::Process - - Module::Load::Conditional - - Scalar::Util - - Time::HiRes - - TimeDate - -If your system is missing any of these, then you may be able to install them -via: - - $ perl -MCPAN -e 'install()' - -You will very likely need superuser access to be able to install Perl -modules. - -Some of the applications provided with the lcov module are written -in Python - and may require additional Python packages. -In particular, 'xlsxwriter' is required in order to generate any -of the spreadsheet reports. - -To measure Python code coverage, users will need Python packages: - - - Coverage.py - -In addition, contributors will need: - - - perltidy - -Your platform may support other mechanisms to install and/or update -required packages. - - - -4. An example of how to access Linux kernel coverage data ---------------------------------------------------------- -Requirements: Follow the Linux kernel coverage setup instructions at: - - https://docs.kernel.org/dev-tools/gcov.html - -As root, do the following: - - a) Resetting counters - - lcov --zerocounters - - b) Capturing the current coverage state to a file - - lcov --capture --output-file kernel.info - - c) Getting HTML output - - genhtml kernel.info - -Point the web browser of your choice to the resulting index.html file. - - -5. An example of how to access coverage data for a user space program ---------------------------------------------------------------------- - - a) Capture current coverage state to a file: - - i) C/C++ code: - - Compile your program using the '--coverage' GCC or LLVM - option. During linking, make sure to specify '--coverage': - - $ gcc -o myTest --coverage simple.c - OR - $ gcc -c file1.c file2.c ... --coverage - $ gcc -o myOtherTest --coverage file1.o file2.o .... - - Alternately, LLVM users can use the 'profdata path' (rather than the - 'gcov path') to collect coverage data from their C/C++ code. See - https://github.com/linux-test-project/lcov/discussions/234 for more - information. - - Run your testcase at least once: - - $ path/to/my/testcase/myTest - - Capture the current coverage state to a file: - - $ lcov --directory path/to/my/testcase --capture --output-file app.info - - (LLVM users using the 'profdata path' will use a somewhat different - command for this step - see the discussion referenced above.) - - If you want to collect Modified Condition / Decision Coverage (MD/DC) - date, then: - - you must use gcc/14.2 (or newer), or LLVM/18 (or newer) - - your GCC compile- and link command line must include flag - '-fcondition-coverage'. - - LLVM users must use the 'profdata path' for coverage data collection, - and your compile command line must include - '-fprofile-inst-generate -fcoverage-mapping -fcoverage-mcdc'. - See the above referenced discussion for details. - - your lcov and genhtml command line must include flag - '--mcdc-coverage' - See the '--mcdc-coverage' section in the genhtml and geninfo man pages. - - Note that runtime coverage data exists only after the application has - been started and stopped at least once. Otherwise, no data will be found - and lcov will abort with an error mentioning that there are no - data/.gcda files. - - The coverage runtime emits data (the .gcda files) in an atexit - callback. If your application exits abnormally or crashes before - the callback is executed, then no coverage data will be available. - - For further information on the gcc profiling mechanism, please - consult the gcov man page. - - See 'man lcov' for more information - especially if your build/test - environment is not trivial. - - ii) Python code: - - - install the Coverage.py module - - - execute your testcase to produce python coverage data: - - $ COVERAGE_FILE=./pycov.dat coverage run --append --branch \ - myPythonScript [my script args] - - - translate Python coverage data to LCOV format: - - $ py2lcov -o pycov.info [py2lcov_options] pycov.dat [x.dat]+ - - See 'py2lcov --help' and the Coverage.py documentation for more - information. - - iii) Perl code: - - - install the Devel::Cover module - - - execute your testcase to produce perl coverage data: - - $ perl -MDevel::Cover=-db,perlcov_db,-coverage,statement,branch,condition,subroutine,-silent,1 myPerlTest.pl [my script args] - - - translate Perl coverage data to LCOV format: - - $ perl2lcov --output perlcov.info perlcov_db [perl2lcov options] - - See 'perl2lcov --help' and the Devel::Cover documentation for more - information. - - iv) XML data (for example, generated by Cobertura): - - - translate XM coverage data to LCOV format: - - $ xml2lcov --output myData.info coverage.xml [xml2lcov options] - - See 'xml2lcov --help' and the Cobertura documentation for more - information. - - b) Generate an HTML coverage report: - - Generate an HTML report, combining all of your LCOV data files: - - $ genhtml -o html_report app.info pycov.info perlcov.info - - Point the web browser of your choice to the resulting file: - html_report/index.html. - - See 'man genhtml' for more details. - - c) Generate a differential coverage report: - - See the example in .../example (run "make test_differential") - as well as the examples in .../tests/gendiffcov. - - -6. LCOV Features: ------------------ - -LCOV features and capabilities fall into 7 major categories: - - a) Categorization - - This refers primarily to differential coverage categorization as - well as date- and owner-binning. See https://arxiv.org/abs/2008.07947 - or https://ieeexplore.ieee.org/document/9438597 for a detailed - description of the concepts. - - Differential categorization and binning are orthogonal in the sense - that you can generate differential report without binning as well - as 'vanilla' coverage reports with binning. See the above papers - and the genhtml man page for details. - - Related options: - --baseline-file, --diff-file, --annotate-script, --select-script - --date-bins, --date-labels --new-file-as-baseline, - --elide-path-mismatch - - b) Error handling - - A generic - but very simple - error handler has been added to the - lcov tool suite. The error handler is used to report exceptions, - and provides a mechanism for the user to ignore the particular - message if desired. Note that ignoring certain errors can cause - subsequent errors and/or can result in inconsistent or confusing - coverage reports. - See the genhtml/lcov/geninfo man pages for details. - - Note that some errors are unrecoverable - and cannot be suppressed or - ignored. - - If environment variable 'LCOV_SHOW_LOCATION' is set to a non-zero - integer, then the error manager will emit more detailed debugging - information into the error log. Higher values generate more - information. - More detail is useful to developers in case of a bug in lcov - but is - unlikely to helpful to regular users. - - Related options: - --ignore-error, --expect-message-count, --keep-going, --msg-log - - c) Navigation and display: - - Navigation aids such as hyperlinks to the first uncovered region, - to the next uncovered region, etc. have been implemented. Similarly, - new tables, new columns, and new links between tables enable the - user to identify the author of particular code (covered or not - covered), as well as the time period when the code was written. - - Collectively, these features help the user to quickly identify the - cause of code coverage issues, and to then decide what to do. - - An option to generate a 'hierarchical' coverage report (which follows - the source code directory structure) or 'flat' (all files in top level - of two-level report) as well as various other small features (tooltip - popups, user-specified HTML header, footer, and table labels, etc.) are - also available. - - See the genhtml man page for some details, as well as the - 'gendiffcov/simple' testcases for some examples. - - Related options: - --baseline-title, --baseline-date, --current-date, - --flat, --hierarchical, - --show-owners, --show-noncode, --show-navigation, --show-proportion, - --suppress-aliases --simplify-script - - d) Data manipulation - - Filters are used to suppress or remove certain coverage artifacts - - for example, branches generated by the compiler (e.g., for exception - handling). These artifacts can overwhelm the user code and obscure - coverage features that are interesting to the user. - - Other options are used to focus on or to exclude certain sections - of code and/or particular expressions, as well as to do regexp - replacement of file names - possibly using case-insensitive comparison. - (Path munging is useful primarily when the build structure does - not exactly match the layout in your revision control system; this - is common in large projects with reusable components.) - - During coverage data capture, the --build-directory option can be used - to specify a search path, to find the .gcno (compile-time coverage data) - file corresponding to a particular .gcda (runtime coverage data) file. - Similarly, the --source-directory option can be used to specify a - search path for source files. - - See the lcov/geninfo/genhtml man pages for a detailed description of - the available filters and manipulation features. - - Related options: - --include, --exclude, --erase-functions, --omit-lines, - --substitute, --filter - --build-directory --source-directory - - e) Callbacks/customization - - The user can supply callbacks which are used to: - - i) interface with the revision control system - to determine source - code differences between versions and to find the author - and date of the most recent edits. - Sample scripts: - - Perforce: see 'p4diff', 'p4annotate.pm', 'p4annotate' - - Git: see 'gitdiff', 'gitblame.pm', 'gitblame' - ii) verify that source code versions are compatible - e.g., - before aggregating coverage data or displaying source code. - Sample scripts: 'get_signature', 'P4version.pm', 'getp4version', - 'gitversion', 'gitversion.pm', and 'batchGitVersion.pm' - iii) enforce a desired code coverage criteria - Sample script: criteria.pm/criteria - iv) find source files in more complicated environments - where - simple substitutions become complicated or unweildy. - v) select a subset of coverage data to display - e.g., to - use in a code review which wants to concentrate on only - the changes caused by a particular commit or range of commits, - or to review changes in a particular release. - Sample script: select.pm - vi) keep track of environment and other settings - to aid - infrastructure debugging in more complicated use cases. - Sample script: context.pm - vii) compress the 'function detail' table to improve readability - by shortening long C++ template and function names. - Sample script: simplify.pm - viii) use history from previous execution to improve runtime - performance of current execution by improving load balancing. - Sample script: history.pm - ix) mark particular branch expressions and/or MC/DC conditions as - 'unreachable' - so they are excluded from the coverage DB. - Sample script: unreach.pm - - The callback may be any desired script or executable - but there - may be performance advantages if it is written as a Perl module. - See the "Additional considerations" and "Callbacks and parallel - execution" discussion in the genhtml man page. - - See the genhtml/lcov/geninfo man pages for details. - - Note that the various sample scripts are found in the source code - 'scripts' directory, but are installed in the - $LCOV_HOME/share/lcov/support-scripts directory of the release. - - Related options: - --annotate-script, --criteria-script, --version-script - --resolve-script, --select-script, --context-script - --simplify-script --history-script --unreachable-script - - f) Performance - - lcov/genhtml/geninfo have been refactored to parallelize computation - across multiple cores, if requested. - In general, this provides speedup that is nearly linear in the number - of cores. - There is also an option to throttle parallelism to not exceed peak - memory consumption constraints, as well as options to enable simple - profile data collection - so you can see where time is going and - thus to hint at potential optimizations. The 'spreadsheet.py' - script can be used to view generated profile data. - - There are several configuration file options which can be used to - tweak certain parallelization parameters to optimize performance - for your environment in cases that the default behaviour is suboptimal. - See the lcovrc man page for more information. - - See the genhtml/lcov/geninfo man pages for details - - Related options: --parallel, --memory, --profile, --history-script - - g) Language/tool support - - Added 'llvm2lcov', 'py2lcov', 'perl2lcov' and 'xml2lcov' scripts. - - - llvm2lcov: - - translates JSON coverage data generated by 'llvm-cov export -format=text ...' - to lcov format. - - See "llvm2lcov --help" for brief instruction on how to use the - translator. Note that llvm2lcov uses a similar set of command line - and configuration file options as lcov, genhtml, and geninfo. - - - py2lcov: - - translates python Coverage.py XML data to lcov format. - - See the Coverage.py documentation at https://coverage.readthedocs.io, - as well as ".../py2lcov --help" - - - perl2lcov - - translates Perl Devel::Cover data to lcov format. - - See the Devel::Cover documentation at - https://metacpan.org/pod/Devel::Cover - to find out how to generate coverage data for Perl code. - - See "perl2lcov --help" for brief instructions on how to - use the translator. - Note that perl2lcov uses a similar set of command line and - config file options as lcov, genhtml, and geninfo. - - - xml2lcov - - translates XML coverage data to lcov format. - The XML data may come from Cobertura or similar tools. - - See "xml2lcov --help" for brief instructions on how to use - the translator. - See the Coburtura documentation for directions on how to - generate XML data. - - Other languages can be integrated using a similar approach. - -In general, the new features and options are implemented uniformly in lcov, -genhtml, and geninfo. Most of the features can be enabled/disabled -using either command line options or by setting defaults in your 'lcovrc' -file. See the lcovrc man page for details. - - -7. Questions and comments -------------------------- -See the included man pages for more information on how to use the LCOV tools. - -In case of further questions, feel free to open a new issue or discussion using -the issue tracker on the LCOV code repository site at: - - https://github.com/linux-test-project/lcov - - -8. Filing a new issue ---------------------- -Before filing a new issue - and if you are using an LCOV release (as opposed -to using a clone of the github repo) - please verify whether the issue is -still present in the LCOV master version. See section 2, above for -directions on how to clone and install the most up-to-date LCOV version. - -If possible, please include a testcase which illustrates the problem -when you file an issue. -Please describe your environment (platform, compiler, perl, and python -versions, etc.). Please include a detailed description of the issue: -what you were trying to do (your goal - not the mechanics of your -procedure), what you did (the mechanics of your procedure), the result -you wanted to see vs. what actually happened. -Depending on the issue, your testcase may need to include source code and -compile/link command lines, directions for how to run your example, the -command lines used to capture and generate your lcov reports, etc. -In other cases, the captured '.info' files may be sufficient to reproduce -the issue. -When in doubt: more is better than less. - -If you cannot include a testcase - e.g., because you feel that it is -senstitive or proprietary - then your detailed description is even more -important. -Note that, without an example, it may be difficult or impossible to -diagnose or fix the problem. - -Bear in mind that you are asking for help from volunteers. Your -priority might not be their priority. Civility, consideration and politeness -go a long way. - -Please check back and to verify the fix and close the issue once it has -been addressed. -Again: remember that you are asking for help from volunteers. -Make sure that you are doing your part. diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..3e602121 --- /dev/null +++ b/README.rst @@ -0,0 +1,629 @@ +================================================= +README file for the LTP GCOV extension (LCOV) +================================================= + +Last changes: 2026-05-22 + +Description +=========== + +LCOV is a tool to manipulate and display information about what parts of a +program are actually executed (*i.e.* "covered") while running a particular test +case or set of testcases. LCOV consists of a set of Perl scripts which build on +the text output of various coverage tools - *e.g.*, gcov, llvm-cov, Coverage.py, +Cobertura, Devel::Cover, Jacoco, etc. - to implement the following enhanced +functionality: + +- **HTML based output**: coverage rates are indicated using bar graphs and + specific colors in a hyperlinked coverage report, intended to enable the + user to quickly diagnose and address coverage issues. + +- **Support for large projects**: overview pages allow quick browsing of + coverage data by providing a hierarchical directory structure view, a flat + list of all source files in the project, or a three-level detail view: + directory, file and source code view. + +- **Support for multiple languages** - including C/C++, Perl, and Python. + +LCOV was initially designed to support Linux kernel coverage measurements, +but works as well for coverage measurements on standard user space applications. + +LCOV supports differential coverage, as well as date- and owner-binning. See: + +- https://arxiv.org/abs/2008.07947 + +or + +- https://ieeexplore.ieee.org/document/9438597 + +for a detailed explanation of the concepts and several possible use models. + +A video presentation of the basic ideas can be found at: + +- http://doi.org/10.5281/zenodo.4653252 + +In addition, several other features and capabilities are available. See +section 6, below, for a brief description - and also see the man pages and +the test cases. + + +Table of Contents +================= + +1. Included files +2. Installing LCOV +3. Dependencies +4. An example of how to access kernel coverage data +5. An example of how to access coverage data for a user space program +6. LCOV features +7. Questions and Comments +8. Filing a new issue + + +1. Included files +================= + +====================== ====================================================== +README.rst This README file +bin/lcov Tool for capturing LCOV coverage data +bin/genhtml Tool for creating HTML output from LCOV data +bin/perl2lcov Tool to translate Perl Devel::Cover data to lcov format +bin/llvm2lcov Tool to translate LLVM 'llvm-cov' JSON data to LCOV format +bin/py2lcov Tool to translate Python Coverage.py to lcov format +bin/xml2lcov Tool to translate Cobertura-like XML coverage data + to lcov format +bin/geninfo Internal tool (creates LCOV data files) +bin/gendesc Tool for creating description files as used by genhtml +bin/genpng Internal tool (creates png overviews of source files) +lcovrc LCOV configuration file +docs Directory containing documentation source +example Directory containing an example to demonstrate LCOV +tests Directory containing lcov regression tests +Makefile Makefile providing 'install' and 'uninstall' targets +====================== ====================================================== + + +2. Installing LCOV +================== + +The LCOV package is available as either RPM or tarball from: + +https://github.com/linux-test-project/lcov/releases + +To install the tarball, unpack it to a directory and run:: + + make install + +Use Git for the most recent (but possibly unstable) version:: + + git clone https://github.com/linux-test-project/lcov.git + +Change to the resulting lcov directory and type:: + + make install + +The default install location is /usr/local. Note that you may need to +have superuser permissions to write into system directories. + +To install in a different location - for example, your home directory, run:: + + make PREFIX=$HOME/my_lcov install + +Your PREFIX should be an absolute path. + +After installation, the LCOV documentation can be found in both ``man`` and +``html`` formats. + + - **man**: + $ export MANPATH=$MANPATH:$LCOV_HOME/share/lcov/man + $ man lcov # or 'man genhtml', 'man llvm2lcov', etc. + + - **html** + point your browser to ``$LCOV_HOME/share/lcov/html/index.html`` + +To run the LCOV regression test suite on your installation:: + + $ cp -r $LCOV_HOME/share/test path/to/myTestDir + $ cd path/to/myTestDir + $ make [COVERAGE=1] + +If desired, you can collect coverage data for the LCOV module by setting +the COVERAGE makefile variable. +Note that the Devel::Cover package must be installed if COVERAGE is enabled +or if you want to use the perl2lcov utility. +To view the collected coverage information, point your browser to +``.../lcov_coverage/index.html`` after running the tests. + +Note that the testcases are primarily intended to test LCOV functionality +and not to be easily readable tutorial examples. + + +3. Dependencies +=============== + +The lcov module is implemented primarily in Perl - and requires both a +moderately up-to-date Perl installation and multiple Perl packages. + +These perl packages include: + +- Capture::Tiny +- DateTime +- Devel::Cover +- Devel::StackTrace +- Digest::MD5 +- File::Spec +- at least one flavor of JSON module. In order of performance/preference: + + - JSON::XS + - Cpanel::JSON::XS + - JSON::PP + - JSON + +- Memory::Process +- Module::Load::Conditional +- Scalar::Util +- Time::HiRes +- TimeDate + +If your system is missing any of these, then you may be able to install them +via:: + + $ perl -MCPAN -e 'install()' + +You will very likely need superuser access to be able to install Perl +modules. + +Some of the applications provided with the lcov module are written +in Python - and may require additional Python packages. +In particular, 'xlsxwriter' is required in order to generate any +of the spreadsheet reports. + +To measure Python code coverage, users will need Python packages: + +- Coverage.py + +In addition, contributors will need: + +- perltidy + +Your platform may support other mechanisms to install and/or update +required packages. + + +4. An example of how to access Linux kernel coverage data +========================================================== + +Requirements: Follow the Linux kernel coverage setup instructions at: + +https://docs.kernel.org/dev-tools/gcov.html + +As root, do the following: + +a) Resetting counters:: + + lcov --zerocounters + +b) Capturing the current coverage state to a file:: + + lcov --capture --output-file kernel.info + +c) Getting HTML output:: + + genhtml kernel.info + +Point the web browser of your choice to the resulting index.html file. + + +5. An example of how to access coverage data for a user space program +====================================================================== + +a) Capture current coverage state to a file: + + i) C/C++ code: + + Compile your program using the '--coverage' GCC or LLVM + option. During linking, make sure to specify '--coverage':: + + $ gcc -o myTest --coverage simple.c + + or:: + + $ gcc -c file1.c file2.c ... --coverage + $ gcc -o myOtherTest --coverage file1.o file2.o .... + + Alternately, LLVM users can use the 'profdata path' (rather than the + 'gcov path') to collect coverage data from their C/C++ code. See + https://github.com/linux-test-project/lcov/discussions/234 for more + information. + + Run your testcase at least once:: + + $ path/to/my/testcase/myTest + + Capture the current coverage state to a file:: + + $ lcov --directory path/to/my/testcase --capture --output-file app.info + + (LLVM users using the 'profdata path' will use a somewhat different + command for this step - see the discussion referenced above.) + + If you want to collect Modified Condition / Decision Coverage (MD/DC) + data, then: + + - you must use ``gcc/14.2`` (or newer), or ``LLVM/18`` (or newer) + - your GCC compile- and link command line must include flag + ``-fcondition-coverage``. + - LLVM users must use the 'profdata path' for coverage data collection, + and your compile command line must include + ``-fprofile-inst-generate -fcoverage-mapping -fcoverage-mcdc``. + See the above referenced discussion for details. + - your lcov and genhtml command line must include flag + ``--mcdc-coverage`` + + See the ``--mcdc-coverage`` section in the genhtml and geninfo man pages. + + Note that runtime coverage data exists only after the application has + been started and stopped at least once. Otherwise, no data will be found + and lcov will abort with an error mentioning that there are no + data/.gcda files. + + The coverage runtime emits data (the .gcda files) in an atexit + callback. If your application exits abnormally or crashes before + the callback is executed, then no coverage data will be available. + + For further information on the gcc profiling mechanism, please + consult the gcov man page. + + See 'man lcov' for more information - especially if your build/test + environment is not trivial. + + ii) Python code: + + - install the Coverage.py module + + - execute your testcase to produce python coverage data:: + + $ COVERAGE_FILE=./pycov.dat coverage run --append --branch \ + myPythonScript [my script args] + + - translate Python coverage data to LCOV format:: + + $ py2lcov -o pycov.info [py2lcov_options] pycov.dat [x.dat]+ + + See 'py2lcov --help' and the Coverage.py documentation for more + information. + + iii) Perl code: + + - install the Devel::Cover module + + - execute your testcase to produce perl coverage data:: + + $ perl -MDevel::Cover=-db,perlcov_db,-coverage,statement,branch,condition,subroutine,-silent,1 myPerlTest.pl [my script args] + + - translate Perl coverage data to LCOV format:: + + $ perl2lcov --output perlcov.info perlcov_db [perl2lcov options] + + See ``perl2lcov --help`` and the ``Devel::Cover`` documentation for more + information. + + iv) XML data (for example, generated by Cobertura): + + - translate XML coverage data to LCOV format:: + + $ xml2lcov --output myData.info coverage.xml [xml2lcov options] + + See ``xml2lcov --help`` and the Cobertura documentation for more + information. + +b) Generate an HTML coverage report: + + Generate an HTML report, combining all of your LCOV data files:: + + $ genhtml -o html_report app.info pycov.info perlcov.info + + Point the web browser of your choice to the resulting file: + html_report/index.html. + + See 'man genhtml' for more details. + +c) Generate a differential coverage report: + + See the example in ``.../example`` (run ``make test_differential``) + as well as the examples in ``.../tests/genhtml``. + + +6. LCOV Features +================ + +LCOV features and capabilities fall into 7 major categories: + +a) Categorization + + This refers primarily to differential coverage categorization as + well as date- and owner-binning. See https://arxiv.org/abs/2008.07947 + or https://ieeexplore.ieee.org/document/9438597 for a detailed + description of the concepts. + + Differential categorization and binning are orthogonal in the sense + that you can generate differential report without binning as well + as 'vanilla' coverage reports with binning. See the above papers + and the genhtml man page for details. + + Related options: + + - ``--baseline-file``, ``--diff-file``, ``--annotate-script``, ``--select-script``, + ``--date-bins``, ``--date-labels``, ``--new-file-as-baseline``, + ``--elide-path-mismatch`` + +b) Error handling + + A generic - but very simple - error handler has been added to the + lcov tool suite. The error handler is used to report exceptions, + and provides a mechanism for the user to ignore the particular + message if desired. Note that ignoring certain errors can cause + subsequent errors and/or can result in inconsistent or confusing + coverage reports. + See the genhtml/lcov/geninfo man pages for details. + + Note that some errors are unrecoverable - and cannot be suppressed or + ignored. + + If environment variable ``LCOV_SHOW_LOCATION`` is set to a non-zero + integer, then the error manager will emit more detailed debugging + information into the error log. Higher values generate more + information. + More detail is useful to developers in case of a bug in lcov - but is + unlikely to helpful to regular users. + + Related options: + + - ``--ignore-error``, ``--expect-message-count``, ``--keep-going``, ``--msg-log`` + +c) Navigation and display + + Navigation aids such as hyperlinks to the first uncovered region, + to the next uncovered region, etc. have been implemented. Similarly, + new tables, new columns, and new links between tables enable the + user to identify the author of particular code (covered or not + covered), as well as the time period when the code was written. + + Collectively, these features help the user to quickly identify the + cause of code coverage issues, and to then decide what to do. + + An option to generate a 'hierarchical' coverage report (which follows + the source code directory structure) or 'flat' (all files in top level + of two-level report) as well as various other small features (tooltip + popups, user-specified HTML header, footer, and table labels, etc.) are + also available. + + See the genhtml man page for some details, as well as the + 'gendiffcov/simple' testcases for some examples. + + Related options: + + - ``--baseline-title``, ``--baseline-date``, ``--current-date``, + ``--flat``, ``--hierarchical``, + ``--show-owners``, ``--show-noncode``, ``--show-navigation``, + ``--show-proportion``, + ``--suppress-aliases``, ``--simplify-script`` + +d) Data manipulation + + Filters are used to suppress or remove certain coverage artifacts - + for example, branches generated by the compiler (*e.g.*, for exception + handling). These artifacts can overwhelm the user code and obscure + coverage features that are interesting to the user. + + Other options are used to focus on or to exclude certain sections + of code and/or particular expressions, as well as to do regexp + replacement of file names - possibly using case-insensitive comparison. + (Path munging is useful primarily when the build structure does + not exactly match the layout in your revision control system; this + is common in large projects with reusable components.) + + During coverage data capture, the --build-directory option can be used + to specify a search path, to find the .gcno (compile-time coverage data) + file corresponding to a particular .gcda (runtime coverage data) file. + Similarly, the --source-directory option can be used to specify a + search path for source files. + + See the lcov/geninfo/genhtml man pages for a detailed description of + the available filters and manipulation features. + + Related options: + + - ``--include``, ``--exclude``, ``--erase-functions``, ``--omit-lines``, + ``--substitute``, ``--filter``, ``--build-directory``, + ``--source-directory`` + +e) Callbacks/customization + + The user can supply callbacks which are used to: + + i) interface with the revision control system - to determine source + code differences between versions and to find the author + and date of the most recent edits. + + Sample scripts: + + - Perforce: see ``p4diff``, ``p4annotate.pm``, ``p4annotate`` + - Git: see ``gitdiff``, ``gitblame.pm``, ``gitblame`` + + ii) verify that source code versions are compatible - *e.g.*, + before aggregating coverage data or displaying source code. + + Sample scripts: ``get_signature``, ``P4version.pm``, ``getp4version``, + ``gitversion``, ``gitversion.pm``, and ``batchGitVersion.pm`` + + iii) enforce a desired code coverage criteria + + Sample script: ``criteria.pm``, ``criteria`` + + iv) find source files in more complicated environments - where + simple substitutions become complicated or unwieldy. + + v) select a subset of coverage data to display - *e.g.*, to + use in a code review which wants to concentrate on only + the changes caused by a particular commit or range of commits, + or to review changes in a particular release. + + Sample script: ``select.pm`` + + vi) keep track of environment and other settings - to aid + infrastructure debugging in more complicated use cases. + + Sample script: ``context.pm`` + + vii) compress the 'function detail' table to improve readability + by shortening long C++ template and function names. + + Sample script: ``simplify.pm`` + + viii) use history from previous execution to improve runtime + performance of current execution by improving load balancing. + + Sample script: ``history.pm`` + + ix) mark particular branch expressions and/or MC/DC conditions as + 'unreachable' - so they are excluded from the coverage DB. + + Sample script: ``unreach.pm`` + + The callback may be any desired script or executable - but there + may be performance advantages if it is written as a Perl module. + See the "Additional considerations" and "Callbacks and parallel + execution" discussion in the genhtml man page. + + See the genhtml/lcov/geninfo man pages for details. + + Note that the various sample scripts are found in the source code + 'scripts' directory, but are installed in the + $LCOV_HOME/share/lcov/support-scripts directory of the release. + + Related options: + + - ``--annotate-script``, ``--criteria-script``, ``--version-script``, + ``--resolve-script``, ``--select-script``, ``--context-script``, + ``--simplify-script``, ``--history-script``, ``--unreachable-script`` + +f) Performance + + lcov/genhtml/geninfo have been refactored to parallelize computation + across multiple cores, if requested. + In general, this provides speedup that is nearly linear in the number + of cores. + There is also an option to throttle parallelism to not exceed peak + memory consumption constraints, as well as options to enable simple + profile data collection - so you can see where time is going and + thus to hint at potential optimizations. The 'spreadsheet.py' + script can be used to view generated profile data. + + There are several configuration file options which can be used to + tweak certain parallelization parameters to optimize performance + for your environment in cases that the default behaviour is suboptimal. + See the lcovrc man page for more information. + + See the genhtml/lcov/geninfo man pages for details + + Related options: ``--parallel``, ``--memory``, ``--profile``, ``--history-script`` + +g) Language/tool support + + Added ``llvm2lcov``, ``py2lcov``, ``perl2lcov`` and ``xml2lcov`` scripts. + + - **llvm2lcov**: + + translates JSON coverage data generated by ``llvm-cov export -format=text ...`` + to lcov format. + + See ``llvm2lcov --help`` for brief instruction on how to use the + translator. Note that llvm2lcov uses a similar set of command line + and configuration file options as lcov, genhtml, and geninfo. + + - **py2lcov**: + + translates python ``Coverage.py`` XML data to lcov format. + + See the Coverage.py documentation at https://coverage.readthedocs.io, + as well as ``.../py2lcov --help`` + + - **perl2lcov**: + + translates Perl ``Devel::Cover`` data to lcov format. + + See the Devel::Cover documentation at + https://metacpan.org/pod/Devel::Cover + to find out how to generate coverage data for Perl code. + + See ``perl2lcov --help`` for brief instructions on how to + use the translator. + Note that perl2lcov uses a similar set of command line and + config file options as lcov, genhtml, and geninfo. + + - **xml2lcov**: + + translates XML coverage data to lcov format. + The XML data may come from Cobertura or similar tools. + + See ``xml2lcov --help`` for brief instructions on how to use + the translator. + See the Cobertura documentation for directions on how to + generate XML data. + + Other languages can be integrated using a similar approach. + +In general, the new features and options are implemented uniformly in lcov, +genhtml, and geninfo. Most of the features can be enabled/disabled +using either command line options or by setting defaults in your 'lcovrc' +file. See the lcovrc man page for details. + + +7. Questions and comments +========================== + +See the included man pages for more information on how to use the LCOV tools. + +In case of further questions, feel free to open a new issue or discussion using +the issue tracker on the LCOV code repository site at: + +https://github.com/linux-test-project/lcov + + +8. Filing a new issue +====================== + +Before filing a new issue - and if you are using an LCOV release (as opposed +to using a clone of the github repo) - please verify whether the issue is +still present in the LCOV master version. See section 2, above for +directions on how to clone and install the most up-to-date LCOV version. + +If possible, please include a testcase which illustrates the problem +when you file an issue. +Please describe your environment (platform, compiler, perl, and python +versions, etc.). Please include a detailed description of the issue: +what you were trying to do (your goal - not the mechanics of your +procedure), what you did (the mechanics of your procedure), the result +you wanted to see vs. what actually happened. +Depending on the issue, your testcase may need to include source code and +compile/link command lines, directions for how to run your example, the +command lines used to capture and generate your lcov reports, etc. +In other cases, the captured '.info' files may be sufficient to reproduce +the issue. +When in doubt: more is better than less. + +If you cannot include a testcase - *e.g.*, because you feel that it is +sensitive or proprietary - then your detailed description is even more +important. +Note that, without an example, it may be difficult or impossible to +diagnose or fix the problem. + +Bear in mind that you are asking for help from volunteers. Your +priority might not be their priority. Civility, consideration and politeness +go a long way. + +Please check back and verify the fix and close the issue once it has +been addressed. +Again: remember that you are asking for help from volunteers. +Make sure that you are doing your part. diff --git a/bin/genhtml b/bin/genhtml index c53119ca..58639667 100755 --- a/bin/genhtml +++ b/bin/genhtml @@ -7992,7 +7992,7 @@ sub html_create($$) $filename = lc($filename) if $lcovutil::case_insensitive; if ($html_gzip) { - open($handle, "|-", "gzip -c > $filename'") or + open($handle, "|-", "gzip -c > $filename") or die("cannot open $filename for writing (gzip): $!\n"); } else { open($handle, ">", $filename) or @@ -11513,7 +11513,7 @@ sub write_source_line(*$$$$$$$) # between code lines owned by '$src_owner', such that the # all the code lines have the same TLA. # In that case, we just insert an href at the top of the - # block to take us past all of of them - to the next code block + # block to take us past all of them - to the next code block # owned by $src_owner with this TLA, which separated by at least # one line of code either owned by someone else, or with a different # TLA. diff --git a/bin/lcov b/bin/lcov index 7d3eeaba..aa817e1e 100755 --- a/bin/lcov +++ b/bin/lcov @@ -620,8 +620,8 @@ sub userspace_reset() unlink($_) or die("cannot remove file $_: $!\n"); } } - ignorable_error($ERROR_EMPTY, - "$pattern does not match any directory entries") + lcovutil::ignorable_error($ERROR_EMPTY, + "$pattern does not match any directory entries") if 0 == $count; } } @@ -1287,7 +1287,7 @@ sub kernel_capture_initial() $base_directory = $build; if (@kernel_directory) { foreach my $dir (@kernel_directory) { - push(@params, File::Scpec->catdir($build, $dir)); + push(@params, File::Spec->catdir($build, $dir)); } } else { push(@params, $build); diff --git a/bin/xml2lcovutil.py b/bin/xml2lcovutil.py index e7e3c7f0..00acb2e4 100644 --- a/bin/xml2lcovutil.py +++ b/bin/xml2lcovutil.py @@ -105,14 +105,11 @@ def __init__(self, scriptArgs): self._versionScript = scriptArgs.version.split(',') if scriptArgs.version else None if self._versionScript and self._versionScript[0][-3:] == ".pm": # hard to handle Perl module in python - so we hack it - self._vesionModule = self._versionScript + self._versionModule = self._versionScript self._versionScript = None self._outf = open(scriptArgs.output, "w") - try: - self._isPython = scriptArgs.isPython - except: - self._isPython = False + self._isPython = getattr(scriptArgs, 'isPython', False) self._outf.write("TN:%s\n" % scriptArgs.testName) @@ -236,7 +233,7 @@ def process_file(self, fileNode, filename): try: with open(filename, 'r') as f: sourceCode = f.read().split('\n') - except: + except (IOError, OSError) as e: feature = ' compute line checksum' if self._args.checksum else '' if self._isPython and self._args.deriveFunctions: if feature != '': @@ -258,7 +255,7 @@ def count(indent): return count def buildFunction(functions, objStack, currentObj, lastLine): - if currentObj and prevLine: + if currentObj and lastLine: currentObj['end'] = lastLine # last line prefix = '' sep = '' @@ -268,10 +265,7 @@ def buildFunction(functions, objStack, currentObj, lastLine): if currentObj['type'] == 'def': fullname = prefix + sep + currentObj['name'] # function might be unreachable dead code - try: - hit = currentObj['hit'] - except: - hit = 0 + hit = currentObj.get('hit', 0) functions.append({'name' : fullname, 'start' : currentObj['start'], 'end' : currentObj['end'], diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..ac4e7e0a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,22 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +RELEASE ?= 2.5 +TOOL_NAME ?= LCOV +BUILD_DATE ?= $(shell date +%Y-%m-%d) +SPHINXOPTS ?= -D release=$(RELEASE) -D version=$(RELEASE) -D today=$(BUILD_DATE) +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @LCOV_BUILD_DATE=$(BUILD_DATE) LCOV_RELEASE=$(RELEASE) TOOL_NAME=$(TOOL_NAME) $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @LCOV_BUILD_DATE=$(BUILD_DATE) LCOV_RELEASE=$(RELEASE) TOOL_NAME=$(TOOL_NAME) $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..8aa110dd --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,353 @@ +# LCOV Documentation Configuration +# Sphinx configuration for building HTML documentation from RST sources. + +import os +import re +from pathlib import Path +from datetime import date +import pdb + +# Tool name - can be overridden via environment variable +# the potentially mixed case product name +ToolName = os.environ.get('TOOL_NAME', 'LCOV') +# the product name in upper case - used in environment variable prefixes, etc. +TOOLNAME = ToolName.upper() + +# Project information +project = ToolName +copyright = f'2024-2026, {ToolName} Project' +author = f'{ToolName} Contributors' + +# Build date - used in man page headers and HTML pages +# Can be overridden via: make BUILD_DATE="YYYY-MM-DD" html +build_date = os.environ.get('LCOV_BUILD_DATE', date.today().strftime('%Y-%m-%d')) + +# The full version, including alpha/beta/rc tags +# Can be overridden via: make RELEASE=X.Y html +# or: sphinx-build -D release=X.Y -D version=X.Y ... +release = os.environ.get('LCOV_RELEASE', '2.5.0') +version = release # For Sphinx, version is typically the short version + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', +] + +# Date format for man pages and HTML pages +today = build_date +today_fmt = '%B %d, %Y' # e.g., "May 19, 2026" + +# Add any paths that contain templates here +templates_path = ['_templates'] + +# List of patterns to exclude +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# Disable syntax highlighting - use plain fixed-width font for code blocks +highlight_language = 'none' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel. +html_theme_options = { + 'display_version': True, + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 1, +} + +# Show build date in HTML pages +html_last_updated_fmt = '%b %d, %Y' + +# Add any paths that contain custom static files +html_static_path = ['_static'] + +# -- Options for manual page output ------------------------------------------ +# Link external man page references to local installed man pages +# Assumes man pages are installed in ../man/ relative to HTML docs +manpages_url = 'file://../man/{page}.{section}.html' + +def get_man_pages(): + """ + Generate man_pages list dynamically from RST files in man/ directory. + + Each entry is a tuple: (source_path, name, description, authors, section) + """ + man_dir = Path(__file__).parent / 'man' + man_pages = [] + + section_pattern = re.compile(r'^:Manual section:\s*(\d+)', re.MULTILINE) + equals_line = re.compile(r'^=+$') + dash_line = re.compile(r'^-+$') + + for rst_file in sorted(man_dir.glob('*.rst')): + content = rst_file.read_text() + lines = content.split('\n') + + name = rst_file.stem + description = f'{name} documentation' + section = 1 + + section_match = section_pattern.search(content) + if section_match: + section = int(section_match.group(1)) + + i = 0 + while i < len(lines): + stripped = lines[i].strip() + if stripped.startswith('..') or not stripped: + i += 1 + else: + break + + if i < len(lines) and equals_line.match(lines[i].strip()): + if i + 2 < len(lines): + title = lines[i + 1].strip() + if title and equals_line.match(lines[i + 2].strip()): + name = title + i += 3 + elif i + 1 < len(lines) and equals_line.match(lines[i + 1].strip()): + name = lines[i].strip() + i += 2 + + while i < len(lines) and not lines[i].strip(): + i += 1 + + if i < len(lines) and dash_line.match(lines[i].strip()): + if i + 2 < len(lines): + subtitle = lines[i + 1].strip() + if subtitle and dash_line.match(lines[i + 2].strip()): + description = subtitle + + name_section = re.search( + r'^NAME\s*\n([-=]+)\s*\n\s*(.+?)\s*$', + content, + re.MULTILINE + ) + if name_section: + desc_line = name_section.group(2).strip() + if ' - ' in desc_line: + description = desc_line.split(' - ', 1)[1].strip() + + if ' - ' in name: + name = name.split(' - ')[0].strip() + + source = f'man/{rst_file.stem}' + man_pages.append((source, name, description, [], section)) + + return man_pages + +man_pages = get_man_pages() + +# -- Dynamic index.rst generation -------------------------------------------- + +def generate_index_rst(app, docname, source): + """ + Generate index.rst content dynamically from man directory entries. + + This callback intercepts the index.rst read and generates: + - The toctree with all man pages + - The overview section with tool descriptions + """ + if docname != 'index': + return + + man_dir = Path(__file__).parent / 'man' + + # Get sorted list of man page names + man_pages_list = sorted(p.stem for p in man_dir.glob('*.rst')) + + # Build toctree entries + toctree_entries = '\n '.join(f'man/{name}' for name in man_pages_list) + + # Get release version from config + rel_version = app.config.release + + # Generate title with version + title = f'{ToolName} Documentation ({rel_version})' + title_underline = '=' * len(title) + + # Generate the full index.rst content + content = f'''.. {ToolName} Documentation + =================== + +{title} +{title_underline} + +{ToolName} is a graphical tool which collects and aggregates +coverage data from multiple sources then generates HTML reports to +visualizae the data. +It supports line, function, branch and MC/DC coverage. +{ToolName} was originally written to display coverage data GCC's coverage testing tool gcov - but has been enhanced to support multiple tools and languages - including C/C++, Perl, Python, Java and SystemVerilog. + +.. toctree:: + :maxdepth: 1 + :caption: Manual Pages + :titlesonly: + + {toctree_entries} + scripts + +Callback Scripts +================ + +{ToolName} provides callback scripts to customize version control system integration, +coverage criteria enforcement and various other purposes: + + - **Annotate scripts**: + + - ``--annotate-script`` option + - extract file author/date data (examples: ``gitblame.pm``, ``p4annotate.pm``) + + - **Version scripts**: + + - ``--version-script`` option + - extract and compare file versions (examples: ``gitversion.pm``, ``batchGitVersion.pm``, ``P4version.pm``, ``get_signature``) + + - **Diff scripts**: + + - used by ``--diff-file`` option + - generate unified source text diffs (examples: ``gitdiff``, ``p4udiff``) + + - **Criteria scripts**:`` + + - --criteria-script`` option + - check and enforce coverage thresholds (examples: ``criteria.pm``, ``threshold.pm``) + + - **Subset/code review**: + + - ``--select-script`` option + - generate HTML report showing only particular subset of sources (example: ``select.pm``) + + - **Unreachable code**: + + - `--unreachable-script`` option + - tag unreachable expressions so they are not counted/do not appear in the coverage report (example: ``unreach.pm``) + + - **Modify code appearance**: + + - ``--simplify-script`` option + - shorten very long C++ template names (example: ``simplify.pm``) + + - **Find corresponding source file** (in non-trivial build environment: + + - ``--resolve-script`` option + +The callback scripts shipped with the {ToolName} release +are primarily intended only as examples of possible callback implementations. +The expectation is that users will want or need to customize the +callbacks in order +to support their specific environment and requirements. + +For details, see the ``*-script`` option section in the individual tool man pages +(``genhtml``, ``llvm2lcov``, *etc.*) +Note that not all tools support all options. For example, `--diff-file` and ``--annotate-script`` are supported ``genhtml`` only. + +Getting Started +=============== + + #. Point your environment to your installation of {ToolName} - or install {ToolName} using ``make install`` + + #. Prepare your executables: + + - C/C++: compile and link with coverage flags: ``--coverage`` or ``-fprofile-arcs -ftest-coverage``. + + - Perl, Python, *etc.* - see the other tools in this release. + + #. Run your tests + + #. Capture coverage + + - C/C++: ``lcov --capture --directory . --output-file coverage.info`` + + - Other languages: see other tools in this release and/or consult your toolchain documentation. + + #. Generate HTML report: ``genhtml coverage.info --output-directory out`` + + #. Read the man pages and/or the HTML documentation to discover other capabilities and options. + +Example +======= + +The {ToolName} source distribution includes a complete working example in +directory ``${TOOLNAME}_HOME/share/lcov/example`` (or in the ``example`` subdirectory, +if you are using an lcov source version). + +The example demonstrates: + +- Compiling C/C++ code with coverage instrumentation +- Running tests and capturing coverage data +- Generating HTML coverage reports +- Using differential coverage analysis +- Using coverage and part of your code review process + + +.. include:: ../example/README.rst + + +AUTHOR +====== + +Peter Oberparleiter + + Original LCOV implementation + +Henry Cox + + Differential coverage, age/author binning, *etc.*. + +LCOV Community + + Ideas, suggestions, fixes...lots of help + +License +======= + +{ToolName} is licensed under the GNU General Public License. See the LICENSE file +for details. +''' + + source[0] = content + +# -- Options for intersphinx extension --------------------------------------- + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} + +# Suppress warnings about title underline/overline length mismatches +# These occur when |TOOL_NAME| substitution changes title length +suppress_warnings = [ + 'misc.highlight_overline', + 'misc.highlight_underline', +] + +# -- Substitutions for all RST files ----------------------------------------- +# Define substitutions that can be used as |TOOL_NAME| in all .rst files +rst_epilog = f""" +.. |TOOL_NAME| replace:: {TOOLNAME} +.. |ToolName| replace:: {ToolName} +""" + +def setup(app): + """Sphinx extension setup.""" + app.connect('source-read', generate_index_rst) + +# -- Options for intersphinx extension --------------------------------------- + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..661e41d3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,7 @@ +.. This file is dynamically generated by conf.py + The content is replaced at build time from man/ directory entries. + +|TOOL_NAME| Documentation +================== + +.. This placeholder content is replaced at build time. diff --git a/docs/man/gendesc.rst b/docs/man/gendesc.rst new file mode 100644 index 00000000..51704948 --- /dev/null +++ b/docs/man/gendesc.rst @@ -0,0 +1,72 @@ +=============================================== +gendesc - generate a test case description file +=============================================== + +:Manual section: 1 +:Manual group: |ToolName| 2.5 + +NAME +---- + +gendesc + Generate a test case description file (internal application) + + +SYNOPSIS +-------- + +**gendesc** [ **-h** | **--help** ] [ **-v** | **--version** ] + [ **-o** | **--output-filename** *filename* ] + *inputfile* + +DESCRIPTION +----------- + +Convert plain text test case descriptions into a format as understood by +**genhtml**. *inputfile* needs to observe the following format: + +For each test case: + +- one line containing the test case name beginning at the start of the line +- one or more lines containing the test case description indented with at + least one whitespace character (tab or space) + +**Example input file:** + +:: + + test01 + An example test case description. + Description continued + + test42 + Supposedly the answer to most of your questions + +Note: valid test names can consist of letters, decimal digits and the +underscore character ('_'). + +OPTIONS +------- + +**-h**, **--help** + Print a short help text, then exit. + +**-v**, **--version** + Print version number, then exit. + +**-o** *filename*, **--output-filename** *filename* + Write description data to *filename*. + + By default, output is written to STDOUT. + +AUTHOR +------ + +Peter Oberparleiter + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)`, :manpage:`genpng(1)`, :manpage:`gcov(1)` + +https://github.com/linux-test-project/lcov diff --git a/docs/man/genhtml.rst b/docs/man/genhtml.rst new file mode 100644 index 00000000..b7cbc8f8 --- /dev/null +++ b/docs/man/genhtml.rst @@ -0,0 +1,1705 @@ +================================================================= +genhtml - generate HTML view from |ToolName| coverage data files +================================================================= + +NAME +---- + +genhtml + Generate HTML view from |ToolName| coverage data files - including differential coverage analysis, age and author binning, and various visualization options. + + +SYNOPSIS +-------- + +:: + + genhtml [ -h | --help ] [ --version ] + [ -q | --quiet ] + [ -v | --verbose ] + [ --debug ] [ --validate ] + [ -s | --show-details ] + [ -f | --frames ] + [ -b | --baseline-file baseline-file-pattern ] + [ -o | --output-directory output-directory ] + [ --header-title banner ] + [ --footer string ] + [ -t | --title title ] + [ -d | --description-file description-file ] + [ -k | --keep-descriptions ] [ -c | --css-file css-file ] + [ -p | --prefix prefix ] [ --no-prefix ] + [ --build-directory directory ] + [ --source-directory dirname ] + [ --no-source ] [ --no-html ] + [ --num-spaces num ] [ --highlight ] + [ --legend ] [ --html-prolog prolog-file ] + [ --html-epilog epilog-file ] [ --html-extension extension ] + [ --html-gzip ] [ --sort-tables ] [ --no-sort ] + [ --function-coverage ] [ --no-function-coverage ] + [ --branch-coverage ] [ --no-branch-coverage ] + [ --mcdc-coverage ] + [ --demangle-cpp [ param ] ] + [ --msg-log [ log_file_name ] ] + [ --ignore-errors errors ] + [ --expect-message-count message_type=expr[,message_type=expr..] ] + [ --keep-going ] [ --config-file config-file ] + [ --profile [ profile-file ] ] + [ --history-script callback ] + [ --rc keyword = value ] + [ --precision num ] [ --missed ] + [ --merge-aliases ] + [ --suppress-aliases ] + [ --forget-test-names ] + [ --dark-mode ] + [ --baseline-title title ] + [ --baseline-date date ] + [ --current-date date ] + [ --diff-file diff-file ] + [ --annotate-script script ] + [ --context-script script ] + [ --criteria-script script ] + [ --version-script script ] + [ --resolve-script script ] + [ --select-script script ] + [ --simplify-script script ] + [ --unreachable-script module ] + [ --checksum ] + [ --fail-under-branches percentage ] + [ --fail-under-lines percentage ] + [ --new-file-as-baseline ] + [ --elide-path-mismatch ] + [ --synthesize-missing ] + [ --date-bins day[,day,...] ] + [ --date-labels string[,string,...] ] + [ --show-owners [ all ] ] + [ --show-noncode ] + [ --show-zero-columns ] + [ --show-navigation ] + [ --show-proportions ] + [ --simplified-colors ] + [ --hierarchical ] [ --flat ] + [ --filter filters ] + [ --include glob_pattern ] + [ --exclude glob_pattern ] + [ --erase-functions regexp_pattern ] + [ --substitute regexp_pattern ] + [ --omit-lines regexp_pattern ] + [ --parallel | -j [ integer ] ] + [ --memory integer_num_Mb ] + [ --tempdir dirname ] + [ --preserve ] + [ --save ] + [ --sort-input ] + [ --serialize serialize_output_file ] + tracefile_pattern(s) + +DESCRIPTION +----------- + +``genhtml`` creates an HTML view of coverage data found in tracefiles ``geninfo`` and ``lcov`` tools which are found from glob-match pattern(s) *tracefile_pattern*. See :manpage:`geninfo(1)` for a description of the tracefile format. + +Features include: + +- Differential coverage comparison against baseline coverage data + +- Annotation of reports with date and owner information ("binning") + +The basic concepts of differential coverage and date/owner binning are described in the paper found at *https://arxiv.org/abs/2008.07947* + + +Differential coverage +~~~~~~~~~~~~~~~~~~~~~ + +Differential coverage compares two versions of source code - the baseline and the current versions - and the coverage results for each to segment the code into categories. + +To create a differential coverage report, ``genhtml`` requires + +1. one or more *baseline-files* specified via ``--baseline-file``, and + +2. a patch file in unified format specified using ``--diff-file``. + +Both *tracefile_pattern* and *baseline-file* are treated as glob patterns which match one or more files. + +The difference in coverage between the set of *tracefiles* and *baseline-files* is classified line-by-line into categories based on changes in 2 aspects: + +1. **Test coverage results**:\ a line of code can be tested (1), untested (0), or unused (#). An unused line is a source code line that has no associated coverage data, for example due to a disabled #ifdef statement. + +2. **Source code changes**:\ a line can be unchanged, added (+ =>), or removed (=> -). Note that the diff-file format used by ``genhtml`` reports changes in lines as removal of old line and addition of new line. + +Below are the resulting 12 categories, sorted by priority (assuming that untested code is more interesting than tested code, and new code is more interesting than old code): + + +**UNC** + Uncovered New Code (+ => 0): newly added code is not tested. + +**LBC** + Lost Baseline Coverage (1 => 0): unchanged code is no longer tested. + +**UIC** + Uncovered Included Code (# => 0): previously unused code is untested. + +**UBC** + Uncovered Baseline Code (0 => 0): unchanged code was untested before, is untested now. + +**GBC** + Gained Baseline Coverage (0 => 1): unchanged code is tested now. + +**GIC** + Gained Included Coverage (# => 1): previously unused code is tested now. + +**GNC** + Gained New Coverage (+ => 1): newly added code is tested. + +**CBC** + Covered Baseline Code (1 => 1): unchanged code was tested before and is still tested. + +**EUB** + Excluded Uncovered Baseline (0 => #): previously untested code is unused now. + +**ECB** + Excluded Covered Baseline (1 => #): previously tested code is unused now. + +**DUB** + Deleted Uncovered Baseline (0 => -): previously untested code has been deleted. + + Note: Because these lines are not represented in the current source version, they are only represented in the classification summary table. + +**DCB** + Deleted Covered Baseline (1 => -): previously tested code has been deleted. + + Note: Because these lines are not represented in the current source version, they are only represented in the classification summary table. + +The differential coverage report colorizes categorized regions in the source code view using unique colors for each. You can use the ``--simplified-colors`` option to instead use one color for 'covered' code and another for 'uncovered'. + + +Date and owner binning +~~~~~~~~~~~~~~~~~~~~~~ + +**Date binning** annotates coverage reports with age-of-last-change information to distinguish recently added or modified code which has not been tested from older, presumed stable code which is also not tested. **Owner binning** adds annotation identifying the author of changes. + +Both age and ownership reporting can be used to enhance team efforts to maintain good coverage discipline by spotlighting coverage shortfalls in recently modified code, even in the absence of baseline coverage data. + +To enable date and owner binning, the ``--annotate-script`` option must be used to specify a script that provides source code line age and ownership information. + +For each source line, age is the interval since the most recent modification date and the owner is the user identity responsible for the most recent change to that line. + +Line coverage overall totals and counts for each of the 12 classification categories are collected for each of the specified age ranges (see the ``--date-bins`` option, below). + + +Script conventions +~~~~~~~~~~~~~~~~~~ + +Some ``genhtml`` options expect the name of an external script or tool as argument. These scripts are then run as part of the associated function. This includes the following options: + +:: + + --annotate-script + --context-script + --criteria-script + --history-script + --resolve-script + --select-script + --simplify-script + --unreachable-script + --version-script + +While each script performs a separate function there are some common aspects in the way these options are handled: + +1. If the callback script name ends in ``.pm`` then the script is assumed to be a Perl module. + + A perl module may offer performance advantages over an external script, as it is compiled once and loaded into the interpreter and because it can load and maintain internal state. + + The module is expected to export a method 'new', which is called with the script name and the script parameters (if any) as arguments. It is expected to return an object which implements several standard methods: + + ``$callback_obj =`` *packagename* ``->new(perl_module_file, args);`` + + version-script + ``$version = $callback_obj->extract_version($source_file_ename);`` + + ``$match = $version->check_version($old_version, $new_version, $source_file_name);`` + + *$match* is expected to be 1 (true) if the version keys refer to the came file and 0 (false) otherwise. + + *$version* + is a string representing a unique identifier of the particular version of the file + + See example implementations ``*$|TOOL_NAME|_HOME/share/lcov/support-scripts/gitversion.pm`` and ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/getp4version.pm``. + + annotate-script + ``($status, $array) = $callback_obj->annotate($source_file_name);`` + + where + + *$status* + is 0 if the command succeeded and nonzero otherwise. *$status* is interpreted in same way as the return code from 'system(..)' + + *$array* + is a list of line data of the form: + + ``[$text, $abbrev, $full_name, $when, $changelist]``. + + and + + *$text* + is the source text from the corresponding line (without newline termination) + + *$abbrev* + is the "abbreviated author name" responsible for this line of code. This is the name that will be used in the various HTML tables. For example, for brevity/readability, you may want to strip the domain from developers who are inside your organization. If there is no associated author, then the value should be *\"NONE\"*. + + *$full_name* + is the "full author name" which is used in annotation tooltips. See the *genhtml_annotate_tooltip* entry in :manpage:`lcovrc(5)`. *$fullname* may be *undef* if the full name and abbreviated names are the same. + + *$when* + is the timestamp associated with the most recent edit of the corresponding line and may be *\"NONE\"* if there is no associated time. + + *$changelist* + is the commit identifier associated with the most recent change to this line, or *\"NONE\"* if there isn't one. + + See example implementations ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/gitblame.pm`` and ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/p4annotate.pm``. + + context-script + ``$hash = $callback_obj->context();`` + + where *$hash* is a reference to a hash of key/value pairs which are meaningful to you. This data is stored in the *profile* database. See the 'profile' section in :manpage:`lcovrc(5)` for more information. + + If your callback is not a perl module - for example, is a shellscript - then it should return a string such that the first word on each line is the key and the remainder is the associated data. If a key is repeated, then the corresponding data strings are concatenated, separated by newline. + + If you want to record only system information, then a shell callback is likely sufficient. If you want to record any tool-specific/internal information, then you will need to implement a perl module so that your callback will be able to access the information. + + Note that the constructor of your *context-script* callback (or of any callback) can perform any additional actions which are required - for example, to write additional files, to query or set tool-specific information, *etc.* For example, the example implementation, below, has an option to append comments to the generated .info file. + + See the example implementation ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/context.pm``. + + criteria-script + ``($status, $array) = $callback_obj->check_criteria($obj_name, $type, $json);`` + + where + + *$obj_name* + is the source file or directory name, or "top" of the object whose coverage criteria is being checked. + + *$type* + is the object type - either *\"file\"*, *\"directory\"*, or *\"top\"*. + + *$json* + is the coverage data associated with this object, in JSON format - see below. + + *$status* + is the return status of the operation, interpreted the same way as the *annotate* callback status, described above. + + *$array* + is a reference to a possibly empty list of strings which will be reported by genhtml. The strings are expected to explain why the coverage criteria failed. + + See example implementations ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/criteria.pm``. + + history-script + ``$cpu_seconds = $callback_obj->history($element_name)`` + + where *$cpu_seconds* is the predicted time taken to process *$element_name* or *undef* if there is no prediction/the element is unknown. + + See the sample implementation ``scripts/history.pm``, + which uses the *--profile* data generated by a previous ``genhtml`` execution to predict the time required this time. + + The prediction may improve load balancing - and thus improve overall runtime performance (*i.e.*, because we won't be waiting for some "long pole" task to complete while all other threads are idle. + + resolve-script + ``$newpath = $callback_obj->resolve($source_file_name)`` + + where *$newpath* is the correct path to the indicated source file or *undef* if the source file is not found by the callback. + + simplify-script + ``$new_func_name = $callback_obj->simplify($orig_func_name)`` + + where *$new_func_name* is the function name which will appear in the function detail table and *$orig_func_name* is the (possibly demangled) function name found in the coverage DB. + + Note that the modified name is only used in the "function detail" table and does not modify information in the coverage DB. + + unreachable-script + ``$data_changed = $callback_obj->exclude($type, $source, $summary, $testdata);`` + + where *$data_changed* is non-zero if coverage data was changed in the callback, *$type* is either "branch" or "mcdc", *$source* is a "ReadCurrentSource" object, *$summary* is the coverage summary across all testcases, and *$testdata* is the per-tescase coverage data. + + See the sample implementation ``.../scripts/unreach.pm`` + for a simple example callback which uses source code annotations to indicate branch expressions and/or MC/DC conditions which are excluded. See the comment at the top of the file for script usage directions. + + More sophisticated unreachability analysis is easy to visualize. For example, one could use reachability data from the compiler or another tool, rather than relying on user annotation. + + Note that the *--unreachable-script* callback must be a Perl module. Unlike the other callbacks, generic scripts are not supported. + +2. The option may be specified as a single *split_char* separated string which is divided into words (see :manpage:`lcovrc(5)`), or as a list of arguments. The resulting command line is passed to a shell interpreter to be executed. The command line includes the script path followed by optional additional parameters separated by spaces. Care must be taken to provide proper quoting if script path or any parameter contains spaces or shell special characters. + + Note that module callbacks must be called via the 'list' method: they cannot be called as an executable with a space-separated set of arguments. + + For convenience: your callback module may need to implement its own 'split_char' so that you can pass multiple parameters to your callback without interacting with genhtml's split mechanism. + +3. If an option is specified multiple times, then the parameters are *not* split, but are simply concatenated to form the command line - see the examples, below. + + For simplicity and ease of understanding: your command line should pass all arguments individually, or all as a comma-separated list - not a mix of the two. + +4. ``genhtml`` passes any additional parameters specified via option arguments between the script path and the parameters required by the script's function. + +Example: + + :: + + genhtml --annotate-script /bin/script.sh + --annotate-script arg0 ... + + results in the same callback as + + :: + + genhtml --annotate-script "/bin/script.sh arg0" ... + + or + + :: + + genhtml --annotate-script /bin/script.sh,arg0 ... + + Note that the first form is preferred. + +The resulting ``genhtml`` callback executes the command line: + + :: + + /bin/script.sh arg0 *source_file_name* + +Similarly + + :: + + genhtml --annotate-script */bin/myMoodule.pm* + --annotate-script arg0 --annotate-script arg1 ... + + or + + :: + + genhtml --annotate-script */bin/myMoodule.pm,arg0,arg1* + +result in ``genhtml`` executing + + :: + + $annotateCallback = myModule->new(arg0, arg1); + +to initialize the class object - *arg0* and *arg1* passed as strings - and then to execute + + :: + + ($status, $arrayRef) = $annotateCallback(*source_file_name*); + +to retrieve the annotation information. + +In contrast, the command + + :: + + genhtml --annotate-script */bin/myMoodule.pm* + --annotate-script arg0,arg1 ... + +would result in ``genhtml`` initializing the callback object via + + :: + + $annotateCallback = myModule->new("arg0,arg1"); + +where "arg0,arg1" is passed as single comma-separated string. + +Similarly, the command + + :: + + genhtml --annotate-script */bin/myMoodule.pm,arg0* + --annotate-script arg1 ... + +would very likely result in an error when genhtml tries to find a script called ``/bin/mymodule.pm,arg0``. + +Note that multiple instances of each script may execute simultaneously if the ``--parallel`` option was specified. Therefore each script must either be reentrant or should arrange for its own synchronization, if necessary. + +In particular, if your callback is implemented via a perl module: + + - the class object associated with the module will initialized once (in the parent process) + + - The callback will occur in the child process (possibly simultaneously with other child processes). + + As a result: if your callback needs to pass data back to the parent, you will need to arrange a communication mechanism to do so. + + +Callbacks and parallel execution +-------------------------------- + +Because callbacks may need to record data - *e.g.*, for error reporting or action summaries in the presence of parallel execution - ``genhtml`` (and ``lcov`` and ``geninfo``\ ) can call certain optional callback methods: + + - ``$callback->start()`` + + is called when the child process begins execution. This method can be used to capture initial state - *e.g.*, to set the count of events in this child to zero. This method is optional. + + - ``my $data = $callback->save()`` + + is called when processing is complete, just before the child process exits. The scalar *$data* returned by your *$callback*\ ``->save()`` method *$callback*\ ``->restore()`` method when the child process is reaped. + + - ``$callback->restore($data)`` + + is called in the parent process when the child is reaped. *$data* is the data that was returned when your *$callback*\ ``->save()`` method was called in the child. (Serialization/deserialization has happened under the covers.) + + - ``$callback->finalize()`` + + is called in the parent process when all calculations are complete and the parent setting up to report final results. This method is optional. + + Note that, unlike the other callback methods described in this section, *finalize()* is called in both parallel and serial execution contexts. + +Note that your callback must implement ``$callback->restore()`` if it implements ``$callback->save()``. +``$callback->start()`` and ``$callback->finalize()`` are optional: if they are implemented, then they will be called. + +These methods are available only for callbacks implemented a perl modules. If you callback is implemented as an executable script (say) - then you are free to implement parent/child data passing however you prefer. + + +Additional considerations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the ``--criteria-script`` option is used, genhtml will use the referenced script to determine whether your coverage criteria have been met - and will return a non-zero status and print a message if the criteria are not met. + +The ``--version-script`` option is used to verify that the same/compatible source code versions are displayed as were used to capture coverage data, as well as to verify that the same source code was used to capture coverage information which is going to be merged and to verify that the source version used for filtering operations is compatible with the version used to generate the data. + +HTML output files are created in the current working directory unless the ``--output-directory`` option is used. If *tracefile* or *baseline-file* ends with ".gz", it is assumed to be GZIP-compressed and the gunzip tool will be used to decompress it transparently. + +Note that all source code files have to be present and readable at the exact file system location they were compiled, and all path references in the input data ".info" and "diff" files must match exactly (*i.e.*, exact string match). + +Further, the ``--version-script``, ``--annotate-script``, and ``--criteria-script`` scripts use the same path strings. However, see the ``--substitute`` and ``--resolve-script`` options for a mechanism to adjust extracted paths so they match your source and/or revision control layout. + +You can use the *check_existence_before_callback* configuration option to tell the tool to check that the file exists before calling the ``--version-script`` or ``--annotate-script`` callback. See :manpage:`lcovrc(5)` for details. + + +Additional options +~~~~~~~~~~~~~~~~~~ + +Use option ``--diff-file`` to supply a unified diff file that represents the changes to the source code files between the version used to compile and capture the baseline trace files, and the version used to compile and capture the current trace files. + +Use option ``--css-file`` to modify layout and colors of the generated HTML output. Files are marked in different colors depending on the associated coverage rate. + +By default, the coverage limits for low, medium and high coverage are set to 0-75%, 75-90% and 90-100% percent respectively. To change these values, use configuration file options. + + *genhtml_hi_limit* and *genhtml_med_limit* + +or type-specific limits: + + *genhtml_line_hi_limit* and *genhtml_line_med_limit* + *genhtml_branch_hi_limit* and *genhtml_branch_med_limit* + *genhtml_function_hi_limit* and *genhtml_function_med_limit* + +See :manpage:`lcovrc(5)` for details. + +Also note that when displaying percentages, 0% and 100% are only printed when the values are exactly 0% and 100% respectively. Other values which would conventionally be rounded to 0% or 100% are instead printed as nearest non-boundary value. This behavior is in accordance with that of the :manpage:`gcov(1)` tool. + +By default, ``genhtml`` reports will include both line and function coverage data. Neither branch or MC/DC data is displayed by default; you can use the ``--branch-coverage`` and ``--mcdc-coverage`` options to enable branch or MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate settings to your personal, group, or site lcov configuration file. See the *branch_coverage* and *mcdc_coverage* sections of :manpage:`lcovrc(5)` for details. + + +OPTIONS +------- + +In general, (almost) all ``genhtml`` options can also be specified in your personal, group, project, or site configuration file - see :manpage:`lcovrc(5)` for details. + + +``-h``, ``--help`` + Print a short help text, then exit. + +``--version`` + Print version number, then exit. + +``-v``, ``--verbose`` + Increment informational message verbosity. This is mainly used for script and/or flow debugging - *e.g.*, to figure out which data files are found, where. Also see the --quiet flag. + +``-q``, ``--quiet`` + Decrement informational message verbosity. + + Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. + +``--debug`` + Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. + +``--validate`` + Check the generated HTML to verify that there are no dead hyperlinks and no unused files in the output directory. The checks can also be enabled by setting environment variable ``LCOV_VALIDATE = 1``. This option is primarily intended for use by developers who modify the HTML report. + +``--flat``, ``--hierarchical`` + Use the specified HTML report hierarchy layout. + + The default HTML report is 3 levels: + + 1. **top-level**:\ table of all directories, + + 2. **directory**:\ table of source files in a directory, and + + 3. **source file detail**:\ annotated source code. + + Option ``--hierarchical`` produces a multilevel report which follows the directory structure of the source code (similar to the file tool in Microsoft Windows). + + Option ``--flat`` produces a two-level HTML report: + + 1. **top-level**:\ table of all project source files, and + + 2. **source file detail**:\ annotated source code. + + The 'flat' view can reduce the number of clicks required to navigate around the coverage report - but is unwieldy except for rather small projects consisting of only a few source files. It can be useful in 'code review' mode, even for very large projects (see the *--select-script* option). + + Most large projects follow a rational directory structure - which favors the 'hierarchical' report format. Teams responsible for a particular module can focus on a specific subdirectory or set of subdirectories. + + Only one of options ``--flat`` or ``--hierarchical`` can be specified at the same time. + + These options can also be persistently set via the lcovrc configuration file using either: + + *genhtml_hierarchical* = 1 + + or + + *genhtml_flat_view* = 1 + + See :manpage:`lcovrc(5)` for details. + +``-f``, ``--frames`` + Use HTML frames for source code view. + + If enabled, a frameset is created for each source code file, providing an overview of the source code as a "clickable" image. Note that this option will slow down output creation noticeably because each source code character has to be inspected once. Note also that the GD.pm Perl module has to be installed for this option to work (it may be obtained from http://www.cpan.org). + + This option can also be controlled from the *genhtml_frames* entry of the ``lcovrc`` file. + + Please note that there is a bug in firefox and in chrome, such that enabling frames will disable hyperlinks from the 'directory' level summary table entry to the first line in the corresponding file in the particular category - *e.g.*, to the first 'MIS' line (vanilla coverage report - see the .i --show-navigation option, below), to the first 'UNC' branch (differential coverage report), etc. Hyperlinks from the summary table at the top of the 'source detail' page are not affected. + +``-s``, ``--show-details`` + Generate detailed directory view. + + When this option is enabled, ``genhtml`` generates two versions of each source file file entry in the corresponding summary table: + + - one containing the standard information plus a link to a "detailed" version, and + + - a second which contains the number of coverpoints in the hit by each testcase. + + Note that missed coverpoints are not shown in the per-testcase table entry data. + + The corresponding summary table is found on the 'directory' page of the default 3-level genthm report, or on the top-level page of the 'flat' report (see *genhtml --flat ...* ), or on the parent directory page of the 'hierarchical' report (see *genhtml --hierarchical ...* ). + + Note that this option may significantly increase memory consumption. + +``-b`` *baseline-file-pattern*, ``--baseline-file`` *baseline-file-pattern* + Use data in the files found from glob pattern *baseline-file-pattern* as coverage baseline. + + ``--baseline-file`` may be specified multiple times - for example, if you have multiple trace data files for each of several test suites and you do not want to go through the additional step of merging all of them into a single aggregated data file. + + The coverage data files specified by *baseline-file-pattern* is read and used as the baseline for classifying the change in coverage represented by the coverage counts in *tracefile-patterns*. If *baseline-file-pattern* is a directory, then genhtml will search the directory for all files ending in '.info'. See the *info_file_extension* section in ``man(5) lcovrc`` for how to change this pattern. + + In general, you should specify a diff file in unified diff format via ``--diff-file`` when you specify a *--baseline-file-pattern*. Without a diff file, genhtml will assume that there are no source differences between 'baseline' and 'current'. For example: this might be used to find incremental changes caused by the addition of more testcases, or to compare coverage results between gcc versions, or between gcc and llvm. + +``--baseline-title`` *title* + Use *title* as the descriptive label text for the source of coverage baseline data. + +``--baseline-date`` *date* + Use *date* as the collection date in text format for the coverage baseline data. If this argument is not specified, the default is to use the creation time of the first file matched by *baseline-file-pattern* as the baseline date. If there are multiple baseline files, then the creation date of the first file is used. + +``--current-date`` *date* + Use *date* as the collection date in text format for the coverage baseline data. If this argument is not specified, the default is to use the creation time of the current *tracefile*. + +``--diff-file`` *diff-file* + Use the *diff-file* as the definition for source file changes between the sample points for *baseline-file-pattern* and *tracefile(s)*. + + Note: + + - if filters are applied during the creation of a differential coverage report, (see the ,I --filter section, below), then those filters will be applied to the *baseline coverage data* (see the *--baseline-file* section, above) as well as to the *current coverage data*. It is important that the *diff-file* accurately reflect all source code changes so that the baseline coverage data can be correctly filtered. + + - Best practice is to use a *--version-script* callback to verify that source versions match before source-based filtering is applied. + + It is almost always a better idea to filter at capture or aggregate time - not at report generation. + + A suitable *"universal diff"* input file for the *--diff-file* option can be generated using either the "p4udiff" or "gitdiff" sample scripts that are provided as part of this package, or by using revision control commands directly. + + The "p4udiff" or "gitdiff" sample scripts are found in: + + ``scripts/p4udiff`` + + and + + ``scripts/gitdiff`` + + These scripts simply post-process the 'p4' or 'git' output to (optionally) remove files that are not of interest and to explicitly note files which have not changed. + + ``p4udiff`` accepts either a changelist ID or the literal string "sandbox"; "sandbox" indicates that there are modified files which have not been checked in. See "*gitdiff -- help*" and "*p4udiff -- help*" for more information. + + It is useful to note unchanged files denoted by lines of the form: + + :: + + diff [optional header strings] + === file_path + + in the p4diff/gitdiff output as this knowledge will help to suppress spurious 'path mismatch' warnings. See the ``--elide-path-mismatch`` and ``--build-directory`` entries, below. + + In general, you will specify ``--baseline-file`` when you specify ``--diff-file``. The *baseline_files* are used to compute coverage differences (*e.g.* gains and losses) between the baseline and current, where the *diff_file* is used to compute code changes: source text is identical between 'baseline' and 'current'. If you specify *baseline_files* but no *diff_file*, the tool will assume that there are no code changes between baseline and current. If you specify a *diff_file* but no *baseline_files*, the tool will assume that there is no baseline coverage data (no baseline code was covered); as result unchanged code (*i.e.*, which does not appear in the *diff_file* will be categorized as eiher GIC (covered) or UIC (not covered) while new or changed code will be categorized as either GNC or UNC. + +``--annotate-script`` *script* + Use *script* to get source code annotation data. + + Use this option to specify an external tool or command line that ``genhtml`` can use to obtain source code annotation data such as age and author of the last change for each source code line. + + This option also instructs ``genhtml`` to add a summary table to the HTML report header that shows counts in the various coverage categories, associated with each date bin. In addition, each source code line will show age and owner information. Annotation data is also used to populate a 'tooltip' which appears when the mouse hovers over the associated source code. See the *genhtml_annotate_tooltip* entry in :manpage:`lcovrc(5)` for details. + + The specified *script* is expected to obtain age and ownership information for each source code line from the revision management system and to output this information in the format described below. + + If the annotate script fails and annotation errors are ignored via ``--ignore-errors``, then ``genhtml`` will try to load the source file normally. If the file is not present or not readable, and the ``--synthesize-missing`` flag is specified, then ``genhtml`` will synthesize fake data for the file. + + ``genhtml`` will emit an error if you have specified an annotation script but no files are successfully annotated (see below). This can happen, for example, if your P4USER, P4CLIENT, or P4PORT environment variables are not set correctly - *e.g.*, if the Jenkins user who generates coverage reports is not the same and the user who checked out the code and owns the sandbox. + + Sample annotation scripts for Perforce ("p4annotate") and git ("gitblame") are provided as part of this package in the following locations: + + ``scripts/p4annotate`` + + and + + ``scripts/gitblame`` + + Note that these scripts generate annotations from the file version checked in to the repository - not the locally modified file in the build directory. If you need annotations for locally modified files, you can shelve your changes in P4, or check them in to a local branch in git. + + **Creating your own script** + + When creating your own script, please first see **Script considerations** above for general calling conventions and script requirements. + + *script* is called by genhtml with the following command line: + + ``script`` *[additional_parameters]* *source_file_name* + + where + + ``script`` + is the script executable + + ``additional_parameters`` + includes any optional parameters specified (see **Script conventions** above) + + ``source_file_name`` + is the source code file name + + The *script* executable should output a line to the standard output stream in the following format for each line in file *source_file_name*: + + *commit_id* | *author_data* | *date* | *source_code* + + where + + ``commit_id`` + is an ID identifying the last change to the line or NONE if this file is not checked in to your revision control system. + + ``genhtml`` counts the file as not 'successfully annotated' if ``commit_id`` is *NONE* and as 'successfully annotated' otherwise. + + ``author_data`` + identifies the author of the last change. + + For backward compatibility with existing annotate-script implementations, two *author_data* formats are supported: + + - *string*:\ the string used as both the 'abbreviated name' (used as 'owner' name in HTML output and callbacks) and as 'full name' (used in tooltip callbacks) + + - *abbrev_string;full_name*:\ the *author_data* string contains both an 'abbreviated name' and a 'full name' - separated by a semicolon character (';'). + + This is useful when generating coverage reports for opensource software components where there are many 'External' contributors who you do not want to distinguish in 'owner' summary tables but you still want to know who the actual author was. (See the ``gitblame`` callback script for an example.) + + ``date`` + is the data of last change in W3CDTF format (--
T::) + + ``source_code`` + is the line's source code + + The script should return 0 (zero) if processing was successful and non-zero if it encountered an error. + +``--criteria-script`` *script* + Use *script* to test for coverage acceptance criteria. + + Use this option to specify an external tool or command line that ``genhtml`` can use to determine if coverage results meet custom acceptance criteria. Criteria checking results are shown in the standard output log of ``genhtml``\ . If at least one check fails, ``genhtml`` will exit with a non-zero exit code after completing its processing. + + A sample coverage criteria script is provided as part of this package in the following location: + + ``scripts/criteria`` + + The sample script checks that top-level line coverage meets the criteria "UNC + LBC + UIC == 0" (added code and newly activated code must be tested, and existing tested code must not become untested). + + As another example, it is possible to create scripts that mimic the ``lcov --fail-under-lines`` feature by checking that the ratio of exercised lines to total lines ("(GNC + GIC + CBC) / (GNC + GIC + CBC + UNC + UIC + UBC)") is greater than the threshold - either only at the top level, in every directory, or wherever desired. Similarly, criteria may include branch and function coverage metrics. + + By default the criteria script is called for all source code hierarchy levels, *i.e.*: top-level, directory, and file-level. The *criteria_callback_levels* configuration file option can be used to limit the hierarchy levels to any combination of 'top', 'directory', or 'file' levels. + + Example: + + :: + + genhtml --rc criteria_callback_levels=directory,top ... + + You can increase the amount of data passed to the criteria script using configuration file option *criteria_callback_data*. By default, only total counts are included. Specifying "date" adds per date-bin counts, "owner" adds per owner-bin counts. + + Example: + + :: + + genhtml --rc criteria_callback_data=date,owner ... + + See :manpage:`lcovrc(5)` for more details. + + **Creating your own script** + + When creating your own script, please first see **Script considerations** above for general calling conventions and script requirements. + + *script* is run with the following command line for each source code file, leaf-directory, and top-level coverage results: + + :: + + script [additional_parameters] "name " " type" "coverage_data" + + where + + ``script`` + is the script executable + + ``additional_parameters`` + includes any optional parameters specified (see **Script conventions** above) + + ``name`` + is the name of the object for which coverage criteria should be checked, that is either the source code file name, directory name, or "top" if the script is called for top-level data + + ``type`` + is the type of source code object for which coverage criteria should be checked, that is one of "file", "directory", or "top" + + ``coverage_data`` + is either a coverage data hash or a JSON representation of coverage data hash of the corresponding source code object. If the callback is a Perl module, then the it is passes a hash object - other wise, it is passed a JSON representation of that data. + + The JSON data format is defined as follows: + + :: + + { + "": { + "found": , + "hit": , + "": , + ... + }, + "": { + "" : { + "found": , + "hit": , + "": , + ... + }, + ... + }, + ... + } + + where + + ``type`` + specifies the type of coverage as one of "line", "function", or "branch" + + ``bin_type`` + specifies the type of per-bin coverage as one of "line_age", "function_age", or "branch_age" for date-bin data, and "line_owners" or "branch_owners" for owner-bin data + + ``bin_id`` + specifies the date-bin index for date-bin data, and owner ID for owner-bin data. + + ``found`` + defines the number of found lines, functions, or branches + + ``hit`` + defines the number of hit lines, functions, or branches + + ``category`` + defines the number of lines, functions, or branches that fall in the specified category (see **Differential coverage** above) + + Note that data is only reported for non-empty coverage types and bins. + + The script should return 0 (zero) if the criteria are met and non-zero otherwise. + + If desired, it may print a single line output string which will be appended to the error log if the return status is non-zero. Additionally, non-empty lines are appended to the genhtml standard output log. + +``--version-script`` *script* + Use *script* to get source code file version data. + + Use this option to specify an external tool or command line that ``genhtml`` can use to obtain a source code file's version ID when generating HTML or applying source filters (see ``--filter`` option). + + A version ID can be a file hash or commit ID from revision control. It is used to check the version of the source file which is loaded against the version which was used to generate coverage data (*i.e.*, the file version seen by lcov/geninfo). It is important that source code versions match - otherwise inconsistent or confusing results may be produced. + + Version mismatches typically happen when the tasks of capture, aggregation, and report generation are split between multiple jobs - *e.g.*, when the same source code is used in multiple projects, a unified/global coverage report is required, and the projects accidentally use different revisions. + + If your .info (coverage data) file does not contain version information - for example, because it was generated by a tool which did not support versioning - then you can use the *compute_file_version* = 1 config file option to generate the data afterward. A convenient way to do this might be to use ``lcov`` *--add-tracefile* to read the original file, insert version information, and write out the result. See :manpage:`lcovrc(5)` for more details. + + Sample scripts for Perforce ("getp4version"), git ("gitversion") and using an md5 hash ("get_signature") are provided as part of this package in the following locations: + + ``scripts/getp4version`` + + ``scripts/gitversion`` + + and + + ``scripts/get_signature`` + + Note that you must use the same script/same mechanism to determine the file version when you extract, merge, and display coverage data - otherwise, you may see spurious mismatch reports. + + **Creating your own script** + + When creating your own script, please first see **Script considerations** above for general calling conventions and script requirements. + + *"script "* is used both to generate and to compare the version ID to enable retaining history between calls or to do more complex processing to determine equivalence. It will be called by ``genhtml`` with either of the following command lines: + + 1. Determine source file version ID + + ``script`` *source_file_name* + + It should write the version ID of *source_file_name* to stdout and return a 0 exit status. If the file is not versioned, it should write an empty string and return a 0 exit status. + + 2. Compare source file version IDs + + ``script --compare`` *source_file_name* *source_file_id* *info_file_id* + + where + + "source_file_name" + is the source code file name + + "source_file_id " + is the version ID returned by calling "script source_file_name" + + "info_file_id " + is the version ID found in the corresponding .info file + + It should return non-zero if the IDs do not match. + +``--resolve-script`` *script* + Use *script* to find the file path for some source file which which appears in an input data file if the file is not found after applying *--substitute* patterns and searching the *--source-directory* list. This option is equivalent to the *resolve_script* config file option. See :manpage:`lcovrc(5)` for details. + +``--select-script`` *callback* + Use *callback* to decide whether a particular source line is interesting and should be included in the output data/generated report or not. + + This option is equivalent to the *select_script* config file option. See :manpage:`lcovrc(5)` for details. + +``--simplify-script`` *callback* + Use *callback* to shorten/simplify long demangled C++ function and template names to make the function detail table more compact and readable - for example, to remove nested namespace names. + + Note that the simplifications affect only the display and not the actual names stored in the coverage DB. In particular, the DB name (not the simplified name) is the one used to match *--erase-function* patterns. + + This option is equivalent to the *simplify_script* config file option. See :manpage:`lcovrc(5)` for details + +``--unreachable-script`` *module* + Use *module* to decide whether particular branch expressions and/or MC/DC conditions should be removed from the coverage report. This option is equivalent to the *unreachable_script* config file option. See :manpage:`lcovrc(5)` for details. + + Note that *"module"* is required to be a Perl module. + + See the *--unreachable-script* discussion in the *"Script conventions"* section, above, and the *"Exclusion markers"* section in :manpage:`geninfo(1)`. + +``--checksum`` + Specify whether to compare stored tracefile checksum to checksum computed from the source code. + + Checksum verification is **disabled** by default. + + When checksum verification is enabled, a checksum will be computed for each source code line and compared to the checksum found in the 'current' tracefile. This will help to prevent attempts to display source code which is not identical to the code used to generate the coverage data. + + Note that this option is somewhat subsumed by the ``--version-script`` option - which does something similar, but at the 'whole file' level. + +``--fail-under-branches`` *percentage* + Use this option to tell genhtml to exit with a status of 1 if the total branch coverage is less than *percentage*. See :manpage:`lcov(1)` for more details. + +``--fail-under-lines`` *percentage* + Use this option to tell genhtml to exit with a status of 1 if the total line coverage is less than *percentage*. See :manpage:`lcov(1)` for more details. + +``--new-file-as-baseline`` + By default, when code is identified on source lines in the 'current' data which were not identified as code in the 'baseline' data, but the source text has not changed, their coverpoints are categorized as "included code": *GIC* or *UIC*. + + However, if the configuration of the coverage job has been recently changed to instrument additional files, then all un-exercised coverpoints in those files will fall into the *GIC* category - which may cause certain coverage criteria checks to fail. + + When this option is specified, genhtml pretends that the baseline data for the file is the same as the current data - so coverpoints are categorized as *CBC* or *UBC* which do not trigger the coverage criteria check. + + Please note that coverpoints in the file are re-categorized only if: + + - There is no 'baseline' data for any coverpoint in this file, AND + + - The file pre-dates the baseline: the oldest line in the file is older than the 'baseline' data file (or the value specified by the ``--baseline-date`` option). + +``--elide-path-mismatch`` + Differential categorization uses file pathnames to match coverage entries from the ".info" file with file difference entries in the unified-diff-file. If the entries are not identical, then categorization may be incorrect or strange. + + When paths do not match, genhtml will produce "path" error messages to tell you about the mismatches. + + If mismatches occur, the best solution is to fix the incorrect entries in the .info and/or unified-diff-file files. However, fixing these entries is not possible, then you can use this option to attempt to automatically work around them. + + When this option is specified, genhtml will pretend that the unified-diff-file entry matches the .info file entries if: + + - the same path is found in both the 'baseline' and 'current' .info files, and + + - the basename of the path in the .info file and the path in the unified-diff-file are the same, and + + - there is only one unmatched unified-diff-file entry with that basename. + + See the ``--diff-file`` and ``--build-directory`` entries for a discussion of how to avoid spurious warnings and/or incorrect matches. + +``--synthesize-missing`` + Generate (fake) file content if source file does not exist. This option can be used to work around otherwise fatal annotation errors. + + When generating annotated file content, ``genhtml`` assumes that the source was written 'now' (so age is zero), the author is *no.body* and the commit ID is *synthesized*. These names and ages will appear in your HTML reports. + + This option is equivalent config file *genhtml_synthesize_missing* parameter; see :manpage:`lcovrc(5)` for details. + +``--date-bins`` *day[,day,...]* + The ``--date-bins`` option is used to specify age boundaries (cutpoints) for date-binning classification. Each *age* element is expected to be an integer number of days prior to today (or prior to your SOURCE_DATE_EPOCH environment variable, if set). If *--date-bins* is not specified, the default is to use 4 age ranges: less than 7 days, 7 to 30 days, 30 to 180 days, and more than 180 days. This option is equivalent to the *genhtml_date_bins* config file option. See :manpage:`lcovrc(5)`. + + This argument has no effect if there is no *source-annotation-script*. + +``--date-labels`` *string[,string,...]* + The ``--date-labels`` option is used to specify labels used for the 'date-bin' table entries in the HTML report. The number of labels should be one greater than the number of cutpoints. If not specified, the default is to use label strings which specify the *[from ..to)* range of ages held by the corresponding bin. + + One possible use of this option is to use release names in the tables - *i.e.*, to indicate the release in which each particular line first appeared. + + This option is equivalent to the *genhtml_date_labels* config file option. See :manpage:`lcovrc(5)`. + + This argument has no effect if there is no *source-annotation-script*. + +``--show-owners`` [ *all* ] + If the ``--show-owners`` option is used, each coverage report header report contain a summary table, showing counts in the various coverage categories for everyone who appears in the revision control annotation as the most recent editor of the corresponding line. If the optional argument 'all' is not specified, the table will show only users who are responsible for un-exercised code lines. If the optional argument is specified, then users responsible for any code lines will appear. In both cases, users who are responsible for non-code lines (e.g, comments) are not shown. This option does nothing if ``--annotate-script`` is not used; it needs revision control information provided by calling the script. + + Please note: if the *all* option is not specified, the summary table will contain "Total" rows for all date/owner bins which are not empty - but there will be no secondary "File/Directory" entries for elements which have no "missed" coverpoints. + + This option is equivalent config file *genhtml_show_owner_table* parameter; see :manpage:`lcovrc(5)` for details. + + The lcovrc controls *owner_table_entries* and *truncate_owner_table* can be used to improve readability by limiting the number of authors who are displayed in the table when the author number is large. For example, if your configuration is: + + *owner_table_entries* = 5 + + *truncate_owner_table* = top,directory + + then the owner table displayed at the top- and directory-levels will be truncated while the table shown at the 'file' level will display the full list. + + See :manpage:`lcovrc(5)` for details. + +``--show-noncode`` + By default, the source code detail view does not show owner or date annotations in the far-left column for non-code lines (*e.g.*, comments). If the ``--show-noncode`` option is used, then the source code view will show annotations for both code and non-code lines. This argument has no effect if there is no *source-annotation-script*. + + This option is equivalent config file *genhtml_show_noncode_owners* parameter; see :manpage:`lcovrc(5)` for details. + +``--show-zero-columns`` + By default, columns whose entries are all zero are removed (not shown) in the summary table at the top of each HTML page. If the ``--show-zero-columns`` option is used, then those columns will be shown. + + When columns are retained, then all the tables have the same width/contain the same number of columns - which may be a benefit in some situations. + + When columns are removed, then the tables are more compact and easier to read. This is especially true in relatively mature development environments, when there are very few un-exercised coverpoints in the project. + +``--show-navigation`` + By default, the summary table in the source code detail view does not contain hyperlinks from the number to the first line in the corresponding category ('Hit' or 'Missed') and from the current location to the next location in the current category, in non-differential coverage reports. (This is the lcov 'legacy' view non-differential reports.) + + If the ``--show-navigation`` option is used, then the source code summary table will be generated with navigation links. Hyperlinks are always generated for differential coverage reports. + + This feature enables developers to find and understand coverage issues more quickly than they might otherwise, if they had to rely on scrolling. + + See the *--frames* description above for a description of a browser bug which disables these hyperlinks in certain conditions. + + Navigation hyperlinks are always enabled in differential coverage report. + +``--show-proportions`` + In the 'function coverage detail' table, also show the percentage of lines and branches within the function which are exercised. + + This feature enables developers to focus attention on functions which have the largest effect on overall code coverage. + + This feature is disabled by default. Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the *derive_function_end_line* discussion in :manpage:`lcovrc(5)`. + +``--simplified-colors`` + By default, each differential category is colorized uniquely in the source code detail view. With this option, only two colors are used: one for covered code and another for uncovered code. Note that ECB and EUB code is neither covered nor uncovered - and so may be difficult to distinguish in the source code view, as they will be presented in normal background color. + +``--exclude`` *pattern* + pattern is a glob-match pattern of filenames to exclude from the report. Files which do NOT match will be included. See the lcov man page for details. + +``--include`` *pattern* + pattern is a glob-match pattern of filenames to include in processing. Files which do not match will be excluded from the report. See the lcov man page for details. + +``--erase-functions`` *regexp* + Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the ``--demangle-cpp`` option is used or not. + + Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the *derive_function_end_line* discussion in :manpage:`lcovrc(5)`. + +``--substitute`` *regexp_pattern* + Apply Perl regexp *regexp_pattern* to source file names found during processing. This is useful when some file paths in the baseline or current .info file do not match your source layout and so the source code is not found. See the lcov man page for more details. + + Note that the substitution patterns are applied to the *--diff-file* entries as well as the baseline and current .info files. + +``--omit-lines`` *regexp_pattern* + Exclude coverage data from lines whose content matches *regexp*. + + Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (*e.g.*, some complicated macro). See the lcov man page for details. + +``--parallel`` [*integer*], ``-j`` [*integer*] + Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). + + Also see the *memory, memory_percentage, max_fork_fails* and *fork_fail_timeout* entries in :manpage:`lcovrc(5)`. + + A previously generated execution profile may help to enable better utilization and faster parallel execution. See the *--profile* and *--history-script* sections of this man page. + +``--memory`` *integer* + Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. + + This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does not know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. + + The configuration file *memory_percentage* option provided another way to set the maximum memory consumption. See man ``lcovrc (5)`` for details. + +``--filter`` *filters* + Specify a list of coverpoint filters to apply to input data. + + Note that certain filters apply only to C/C++ source files. ``genhtml`` associates the file extension ('.c', '.vhd', *etc.*) with its source language. See the *c_file_extentions* and *rtl_file_extensions* sections of :manpage:`lcovrc(5)` for a description of the default associations and how they can be changed. + + Note that filters are applied to both 'branch' and 'MC/DC' coverpoints, where appropriate: if a particular filter would remove some branch, then it will also remove corresponding MC/DC coverpoints - for example, *--filter branch* will remove MC/DC coverpoints if there is no conditional expression on the corresponding line, and *--filter branch_region* will remove both branch and MC/DC coverpoints in the marked region. + + Most filters need the source code; filters are not applied if the source file is not available. Similarly, for each source file, if the version recorded in the coverage data (the '.info' file) does not match the version found on the filesystem, then a *version* error is reported. If the *version* error is ignored, then filtering is not applied to the mismatched file. See the *--version-script* for more information. + + *filters* can be a comma-separated list of the following keywords: + + branch: + ignore branch counts for C/C++ source code lines which do not appear to contain conditionals. These may be generated automatically by the compiler (*e.g.*, from C++ exception handling) - and are not interesting to users. This option has no effect unless ``--branch-coverage`` is used. + + See also :manpage:`lcovrc(5)` - which describes several variables which affect branch filtering: *filter_lookahead* and *filter_bitwise_conditional*. + + The most common use for branch filtering is to remove compiler-generated branches related to C++ exception handlers. See the no_exception_branch' option in :manpage:`lcovrc(5)` for a way to remove all identified exception branches. + + brace: + ignore line coverage counts on the closing brace of C/C++ code block, if the line contains only a closing brace and the preceding line has the same count or if the close brace has a zero count and either the preceding line has a non-zero count, or the close brace is not the body of a conditional. + + These lines seem to appear and disappear in gcov output - and cause differential coverage to report bogus LBC and/or GIC and/or UIC counts. Bogus LBC or UIC counts are a problem because an automated regression which uses pass criteria "LBC + UIC + UNC == 0" will fail. + + blank: + ignore lines which contain only whitespace (or whitespace + comments) whose 'hit' count is zero. These appear to be a 'gcov' artifact related to compiler-generated code - such as exception handlers and destructor calls at the end of scope - and can confuse differential coverage criteria. + + If lcovrc option *filter_blank_aggressive* = 1 is enabled, then blank lines will be ignored whether their 'hit' count is zero or not. Aggressive filtering may be useful in LLVM-generated coverage data, which tends to include large numbers of such lines. + + directive: + ignore lines which look like C compiler directives: #ifdef, #include, #define, *etc.* These lines are sometimes included by *llvm-cov* when LLVM profile data is translated to LCOV format. + + exception: + Exclude branches related to C++ exception handling from branch coverage. Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data. See the *no_exception_branch* section of :manpage:`lcovrc(5)`. + + initializer: + Exclude lines which appear to be part of a C++ std::initializer_list. + + line: + alias for "--filter brace,blank". + + mcdc: + Remove MC/DC coverpoint which contains single expression, if 'branch' coverpoint is present on the same line. Singe-element MC/DC coverpoints are identical to the corresponding branch - except in the case of compile-time expression evaluation, for example, in a template function. + + orphan: + Remove branches which appear by themselves - *i.e.*, the branch has only one destination and so cannot be a conditional. + + These occur most frequently as a result of exception branch filtering. + + range: + Ignore line and branch coverpoints on lines which are out-of range/whose line number is beyond the end of the source file. These appear to be gcov artifacts caused by a macro instantiation on the last line of the file. + + region: + apply LCOV_EXCL_START/LCOV_EXCL_STOP/LCOV_EXCL_LINE and LCOV_UNREACHABLE_START/LCOV_UNREACHABLE_STOP/LCOV_UNREACHABLE_LINE directives found in source text to the coverpoints found in the current and baseline .info files. This option may be useful in cases that the source code was not found during 'lcov --capture ...' but is accessible now. + + branch_region: + apply LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP/LCOV_EXCL_BR_LINE directives found in source text to the coverpoints found in the current and baseline .info files. This is similar to the 'region option, above - but applies to branch coverpoints only. + + function: + combine data for every "unique" function which is defined at the same file/line. *geninfo/gcov* seem to have a bug such that they create multiple entries for the same function. This feature also merges all instances of the same template function/template method. + + trivial: + remove trivial functions and associated coverpoints. 'Trivial' functions are whose body is empty/do not contain any statements. Commonly, these include compiler-generated methods (*e.g.*, default constructors and assignment operators) as well as static initialization wrappers, etc. + + Note that the *trivial* filter requires function end line information - and so requires that you use a compiler version which is new enough to support begin/end line reports (*e.g.*, gcc/9 or newer) or that you enable lcov/genhtml/geninfo to derive the information: + + In :manpage:`lcovrc(5)`, see the *derive_function_end_line* setting as well as the *trivial_function_threshold* setting. The former is used to turn end line calculation on or off, and the latter to change the lookahead used to determine whether the function body is empty. Also see the *lcov_filter_parallel* and *lcov_filter_chunk_size* settings, which may improve CPU performance if the number of files to process is very large. + +``-o``, ``--output-directory`` *output-directory* + Create files in *output-directory*. + + Use this option to tell ``genhtml`` to write the resulting files to a directory other than the current one. If *output-directory* does not exist, it will be created. + + It is advisable to use this option since depending on the project size, a lot of files and subdirectories may be created. + +``-t``, ``--title`` *title* + Display *title* in header table of all pages. + + *title* is written to the "Test:"-field in the header table at the top of each generated HTML page to identify the context in which a particular output was created. By default, this is the name of the 'current; tracefile. + + A common use is to specify a test run name, or a version control system identifier (perforce changelist or git SHA, for example) that indicates the code level that was tested. + +``--header-title`` *BANNER* + Display *BANNER* in header of all pages. + + *BANNER* is written to the header portion of each generated HTML page. By default, this simply identifies this as an |ToolName| (differential) coverage report. + + A common use is to specify the name of the project or project branch and the Jenkins build ID. + +``--footer`` *FOOTER* + Display *FOOTER* in footer of all pages. + + *FOOTER* is written to the footer portion of each generated HTML page. The default simply identifies the |ToolName| tool version used to generate the report. + +``-d``, ``--description-file`` *description-file* + Read test case descriptions from *description-file*. + + All test case descriptions found in *description-file* and referenced in the input data file are read and written to an extra page which is then incorporated into the HTML output. + + The file format of *description-file* is: + + for each test case: + + TN: + TD: + + Valid test case names can consist of letters, numbers and the underscore character ('_'). + +``-k``, ``--keep-descriptions`` + Do not remove unused test descriptions. + + Keep descriptions found in the description file even if the coverage data indicates that the associated test case did not cover any lines of code. + + This option can also be configured permanently using the configuration file option *genhtml_keep_descriptions*. + +``-c``, ``--css-file`` *css-file* + Use external style sheet file *css-file*. + + Using this option, an extra .css file may be specified which will replace the default one. This may be helpful if the default colors make your eyes want to jump out of their sockets :) + + This option can also be configured permanently using the configuration file option *genhtml_css_file*. + +``--build-directory`` *dirname* + To support 'linked build directory' structures, add 'dirname' to the list of places to search for soft links to source files - *e.g.*, to handle the case that the links point to source files which are held in your revision control system, and appear in the *--diff-file* data. In this use case, paths in the coverage data very likely refer to the structure seen by the compiler during the build - so resolving them back to the corresponding revsion-controlled source structure is likely to be successful. + + Look in *dirname* for file paths which appear in *tracefile* - possibly after substitutions have been applied - which are soft links. Both the original file path and the path to the linked file will resolve to the same *--diff-file* entry. + + This option can be specified multiple times, to add more directories to the search path. + +``--source-directory`` *dirname* + Add 'dirname' to the list of places to look for source files. + + For relative source file paths *e.g.* paths found in *tracefile*, or in *diff-file* - possibly after substitutions have been applied - ``genhtml`` will first look for the path from 'cwd' (where genhtml was invoked) and then from each alternate directory name in the order specified. The first location matching location is used. + + This option can be specified multiple times, to add more directories to the source search path. + +``-p``, ``--prefix`` *prefix* + Remove *prefix* from all directory names. + + Because lists containing long filenames are difficult to read, there is a mechanism implemented that will automatically try to shorten all directory names on the overview page beginning with a common prefix. By default, this is done using an algorithm that tries to find the prefix which, when applied, will minimize the resulting sum of characters of all directory names. + + Use this option to specify the prefix to be removed by yourself. + +``--no-prefix`` + Do not remove prefix from directory names. + + This switch will completely disable the prefix mechanism described in the previous section. + + This option can also be configured permanently using the configuration file option *genhtml_no_prefix*. + +``--no-source`` + Do not create source code view. + + Use this switch if you don't want to get a source code view for each file. + + This option can also be configured permanently using the configuration file option *genhtml_no_source*. + +``--no-html`` + Do not create HTML report. + + Use this switch if you want some artifact of coverage report generation - *e.g.*, the coverage criteria check or the serialized coverage DB, *etc.* - but do not need the coverage report HTML itself. + +``--num-spaces`` *spaces* + Change appearance of tabs in source view according to *spaces*. + + When set to 0, tabs and their behaviour will be the browser's default. + + Negative values will set the rendered width in the source view to *spaces* spaces. + + Positive values will replace tabs with *spaces* spaces. + + Default value is 8. + + This option can also be configured permanently using the configuration file option *genhtml_num_spaces*. + +``--highlight`` + Highlight lines with converted-only coverage data. + + Use this option in conjunction with the ``--diff`` option of ``lcov`` to highlight those lines which were only covered in data sets which were converted from previous source code versions. + + This option can also be configured permanently using the configuration file option *genhtml_highlight*. + +``--legend`` + Include color legend in HTML output. + + Use this option to include a legend explaining the meaning of color coding in the resulting HTML output. + + This option can also be configured permanently using the configuration file option *genhtml_legend*. + +``--html-prolog`` *prolog-file* + Read customized HTML prolog from *prolog-file*. + + Use this option to replace the default HTML prolog (the initial part of the HTML source code leading up to and including the tag) with the contents of *prolog-file*. Within the prolog text, the following words will be replaced when a page is generated: + + ``@pagetitle@`` + The title of the page. + + ``@basedir@`` + A relative path leading to the base directory (*e.g.*, for locating css-files). + + This option can also be configured permanently using the configuration file option *genhtml_html_prolog*. + +``--html-epilog`` *epilog-file* + Read customized HTML epilog from *epilog-file*. + + Use this option to replace the default HTML epilog (the final part of the HTML source including ) with the contents of *epilog-file*. + + Within the epilog text, the following words will be replaced when a page is generated: + + ``@basedir@`` + A relative path leading to the base directory (*e.g.*, for locating css-files). + + This option can also be configured permanently using the configuration file option *genhtml_html_epilog*. + +``--html-extension`` *extension* + Use customized filename extension for generated HTML pages. + + This option is useful in situations where different filename extensions are required to render the resulting pages correctly (*e.g.*, php). Note that a '.' will be inserted between the filename and the extension specified by this option. + + This option can also be configured permanently using the configuration file option *genhtml_html_extension*. + +``--html-gzip`` + Compress all generated html files with gzip and add a .htaccess file specifying gzip-encoding in the root output directory. + + Use this option if you want to save space on your webserver. Requires a webserver with .htaccess support and a browser with support for gzip compressed html. + + This option can also be configured permanently using the configuration file option *genhtml_html_gzip*. + +``--sort-tables``, ``--no-sort`` + Specify whether to include sorted views of file and directory overviews. + + Use ``--sort-tables`` to include sorted views or ``--no-sort`` to not include them. Sorted views are **enabled** by default. + + When sorted views are enabled, each overview page will contain links to views of that page sorted by coverage rate. + + This option can also be configured permanently using the configuration file option *genhtml_sort*. + +``--function-coverage``, ``--no-function-coverage`` + Specify whether to display function coverage summaries in HTML output. + + Use --function-coverage to enable function coverage summaries or --no-function-coverage to disable it. Function coverage summaries are **enabled** by default. + + This option can also be configured permanently using the configuration file option *genhtml_function_coverage*. + + When function coverage summaries are enabled, each overview page will contain the number of functions found and hit per file or directory, together with the resulting coverage rate. In addition, each source code view will contain a link to a page which lists all functions found in that file plus the respective call count for those functions. The function coverage page groups the data for every alias of each function, sorted by name or execution count. The representative name of the group of functions is the shorted (*i.e.*, containing the fewest characters). + + If using differential coverage and a sufficiently recent compiler version which report both begin and end line of functions (*e.g.*, gcc/9 and newer), functions are considered 'new' if any of their source lines have changed. With older compiler versions, functions are considered 'new' if the function signature has changed or if the entire function is new. + +``--branch-coverage``, ``--no-branch-coverage`` + Specify whether to display branch coverage data in HTML output. + + Use ``--branch-coverage`` to enable branch coverage display or ``--no-branch-coverage`` to disable it. Branch coverage data display is **disabled** by default. + + When branch coverage display is enabled, each overview page will contain the number of branches found and hit per file or directory, together with the resulting coverage rate. In addition, each source code view will contain an extra column which lists all branches of a line with indications of whether the branch was taken or not. Branches are shown in the following format: + + :: + + ' + ': Branch was taken at least once + ' - ': Branch was not taken + ' # ': The basic block containing the branch was never executed + + Note that it might not always be possible to relate branches to the corresponding source code statements: during compilation, GCC might shuffle branches around or eliminate some of them to generate better code. + + This option can also be configured permanently using the configuration file option *branch_coverage*. + +``--mcdc-coverage`` + Specify whether to display Modifie Condition / Decision Coverage (MC/DC) data in HTML output. + + MC/DC data display is **disabled** by default. + + MC/DC coverage is supported for GCC versions 14.2 and higher, or LLVM 18.1 and higher. + + See *llvm2lcov --help* for details on MC/DC data capture in LLVM. + + When MC/DC display is enabled, each overview page will contain the number of MC/DC expressions found and hit per file or directory - two senses per expression - together with the resulting coverage rate. In addition, each source code view will contain an extra column which lists all expressions and condition senses of a line with indications of whether the condition was sensitized or not. Conditions are shown in the following format: + + T: + True sense of subexpression was sensitized: if this subexpression's value had been false, then the condition result would have been different. + + t: + True sense of subexpression was **not** sensitized: the condition result would not change if the subexpression value was different. + + F: + False sense of subexpression was sensitized: if this subexpression's value had been true, then the condition result would have been different. + + f: + False sense of subexpression was **not** sensitized: the condition result would not change if the subexpression value was different. + + Note that branch and MC/DC coverage are identical if the condition is a simple expression - *e.g.*, + + :: + + if (enable) ... + + Note that, where appropriate, filters are applied to both 'branch' and 'MC/DC' coverpoints: if a particular filter would remove some branch, then it will also remove corresponding MC/DC coverpoints. See the *--filter* section, above. + + This option can also be configured permanently using the configuration file option *mcdc_coverage*. See :manpage:`lcovrc(5)`. + + Note that MC/DC coverpoints are defined differently by GCC and LLVM. + + GCC: + evaluates the sensitivity of the condition to the 'true' and 'false' sense of each constituent (leaf) expression independently. + + That is: it evaluates the question: does the result of the condition change if *this* constituent expression changed from true to false (termed the 'true' sense, above) or from false to true (termed the 'false' sense, above). + + For example, the expression *A || B* is sensitive to *A==true* when *B==false*, but is not sensitive to *A==true* when *B==true*. + + LLVM: + records the subexpression as covered if and only if there is a pair of evaluations of the condition such that the condition was sensitized for both 'true' and 'false' values of the subexpression. This is defined as an *independence pair* in the LLVM documentation. + + That is: the testcase must sensitize both values in order to be marked covered by LLVM, whereas GCC will independently mark each. Consequently: in LLVM-generated ``lcov`` reports, either both 'true' and 'false' sensitizations will be covered, or neither will be. + + See the examples in tesctcase *.../tests/lcov/mcdc*. + +``--demangle-cpp`` [ *param* ] + Specify whether to demangle C++ function names. + + Use this option if you want to convert C++ internal function names to human readable format for display on the HTML function overview page. + + If called with no parameters, genhtml will use *c++filt* for demangling. This requires that the c++filt tool is installed (see ``c++filt(1)``). + + If *param* is specified, it is treated as th tool to call to demangle source code. The ``--demangle-cpp`` option can be used multiple times to specify the demangling tool and a set of command line options that are passed to the tool - similar to how the gcc *-Xlinker* parameter works. In that case, you callback will be executed as *| demangle_param0 demangle_param1 ...* Note that the demangle tool is called as a pipe and is expected to read from stdin and write to stdout. + +``--msg-log`` [ *log_file_name* ] + Specify location to store error and warning messages (in addition to writing to STDERR). If *log_file_name* is not specified, then default location is used. + +``--ignore-errors`` *errors* + Specify a list of errors after which to continue processing. + + Use this option to specify a list of error classes after which ``genhtml`` should continue processing with a warning message instead of aborting. To suppress the warning message, specify the error class twice. + + *errors* can be a comma-separated list of the following keywords: + + annotate: + ``--annotate-script`` returned non-zero exit status - likely a file path or related error. HTML source code display will not be correct and ownership/date information may be missing. + + branch: + Branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. + + callback: + Annotate, version, or criteria script error. + + category: + Line number categorizations are incorrect in the .info file, so branch coverage line number turns out to not be an executable source line. + + child: + child process returned non-zero exit code during *--parallel* execution. This typically indicates that the child encountered an error: see the log file immediately above this message. In contrast: the *parallel* error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. + + count: + An excessive number of messages of some class has been reported - subsequent messages of that type will be suppressed. The limit can be controlled by the 'max_message_count' variable. See :manpage:`lcovrc(5)`. + + corrupt: + Corrupt/unreadable coverage data file found. + + deprecated: + You are using a deprecated option. This option will be removed in an upcoming release - so you should change your scripts now. + + empty: + The patch file specified by the ``--diff-file`` argument does not contain any differences. This may be OK if there were no source code changes between 'baseline' and 'current' (*e.g.*, the only change was to modify a Makefile) - or may indicate an unsupported file format. + + excessive: + your coverage data contains a suspiciously large 'hit' count which is unlikely to be correct - possibly indicating a bug in your toolchain. See the *excessive_count_threshold* section in :manpage:`lcorc(5)` for details. + + fork: + Unable to create child process during *--parallel* execution. + + If the message is ignored (*--ignore-errors fork*), then genhtml will wait a brief period and then retry the failed execution. + + If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. + + format: + Unexpected syntax or value found in .info file - for example, negative number or zero line number encountered. + + inconsistent: + This error indicates that your coverage data is internally inconsistent: it makes two or more mutually exclusive claims. For example: + + - Files have been moved or repository history presented by ``--diff-file`` data is not consistent with coverage data; for example, an 'inserted' line has baseline coverage data. These issues are likely to be caused by inconsistent handling in the 'diff' data compared to the 'baseline' and 'current' coverage data (*e.g.*, using different source versions to collect the data but incorrectly annotating those differences), or by inconsistent treatment in the 'annotate' script. Consider using a ``--version-script`` to guard against version mismatches. + + - Two or more ``gcov`` data files or ``lcov`` ".info" files report different end lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch. + + In this context, if the *"inconsistent"* error is ignored, then the tool will record the largest number as the function end line. + + - Two or more ``gcov`` data files or ``lcov`` ".info" files report different start lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch. + + In this context, if the *"inconsistent"* error is ignored, then the tool will retain only the first function definition that it saw. + + - Mismatched function declaration/alias records encountered: + + - (backward compatible LCOV format) function execution count record ( *FNDA* ) without matching function declaration record ( *FN* ). + + - (enhanced LCOV format) function alias record ( *FNA* ) without matching function declaration record ( *FLN* ). + + - branch expression (3rd field in the .info file 'BRDA' entry) of merge data does not match + + If the error is ignored, the offending record is skipped. + + internal: + internal tool issue detected. Please report this bug along with a testcase. + + mismatch: + Incorrect or inconsistent information found in coverage data and/or source code - for example, the source code contains overlapping exclusion directives. + + missing: + remove all coverpoints associated with source files which are not found or are not readable. This is equivalent to adding a *--exclude* pattern for each file which is not found. + + If a *--resolve-script* callback is specified, then the file is considered missing if it is not locally visible and the callback returns "" (empty string) or 'undef' - otherwise not missing. + + negative: + negative 'hit' count found. + + Note that negative counts may be caused by a known GCC bug - see + + :: + + https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 + + and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. + + package: + A required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. + + parallel: + various types of errors related to parallelism - *i.e.*, a child process died due to an error. The corresponding error message appears in the log file immediately before the *parallel* error. If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the --parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. + + path: + File name found in ``--diff-file`` file but does not appear in either baseline or current trace data. These may be mapping issues - different pathname in the tracefile vs. the diff file. + + range: + Coverage data refers to a line number which is larger than the number of lines in the source file. This can be caused by a version mismatch or by an issue in the *gcov* data. + + source: + The source code file for a data set could not be found. + + unmapped: + Coverage data for a particular line cannot be found, possibly because the source code was not found, or because the line number mapping in the \.info file is wrong. + + This can happen if the source file used in HTML generation is not the same as the file used to generate the coverage data - for example, lines have been added or removed. + + unreachable: + a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the *retain_unreachable_coverpoints_if_executed* configuration parameter. See :manpage:`lcovrc(5)` and the *"Exclusion markers"* section of :manpage:`geninfo(1)` for more information. + + unsupported: + The requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. + + unused: + The include/exclude/erase/substitute/omit pattern did not match any file pathnames. + + usage: + unsupported usage detected - *e.g.* an unsupported option combination. + + utility: + a tool called during processing returned an error code (*e.g.*, 'find' encountered an unreadable directory). + + version: + --version-script comparison returned non-zero mismatch indication. It likely that the version of the file which was used in coverage data extraction is different than the source version which was found. File annotations may be incorrect. + + Note that certain error messages are caused by issues that you probably cannot fix by yourself - for example, bugs in your tool chain which result in *inconsistent* coverage DB data (see above). In those cases, after reviewing the messages you may want to exclude the offending code or the entire offending file, or you may simply ignore the messages - either by converting to warning or suppressing entirely. Another alternative is to tell ``genhtml`` about the number of messages you expect - so that it can warn you if something changes such that the count differs, such that you know to review the messages again. See the *--expect-message-count* flag, below. + + Also see ':manpage:`lcovrc(5)`' for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. + +``--expect-message-count message_type:expr[,message_type:expr]`` + Give ``genhtml`` a constraint on the number of messages of one or more types which are expected to be produced during execution. Note that the total includes _all_ messages of the given type - including those which have been suppressed. If the constraint is not true, an error of type *count* (see above) is generated. *message_type* is one of the message mnemonics described above, and *expr* may be either + + - an integer - interpreted to mean that there should be exactly that number of messages of the corresponding type, or + + - a Perl expression containing the substring ``%C``; %C is replaced with the total number of messages of the corresponding type and then evaluated. The constraint is met if the result is non-zero and is not met otherwise. + + For example: + + :: + + --expect-message-count inconsistent:5 + + says that we expect exactly 5 messages of type 'inconsistent'. + + :: + + --expect-message-count inconsistent:%C==5 + + also says that we expect exactly 5 messages of this type, but specified using expression syntax. + + :: + + --expect-message-count 'inconsistent : %C > 6 && %C <= 10' + + says that we expect the number of messages to be in the range (6:10]. (Note that quoting may be necessary, to protect whitespace from interpretation by your shell, if you want to improve expression readability by adding spaces to your expression.) + + Multiple constraints can be specified using a comma-separated list or by using the option multiple times. + + This flag is equivalent to the *expect_message_count* configuration option. See :manpage:`lcovrc(5)` for more details on the expression syntax and how expressions are interpreted. The number of messages of the particular type is substituted into the expression before it is evaluated. + +``--keep-going`` + Do not stop if error occurs: attempt to generate a result, however flawed. + + This command line option corresponds to the *stop_on_error* lcovrc option. See :manpage:`lcovrc(5)` for more details. + +``--config-file`` *config-file* + Specify a configuration file to use. See :manpage:`lcovrc(5)` for details of the file format and options. Also see the *config_file* entry in the same man page for details on how to include one config file into another. + + When this option is specified, neither the system-wide configuration 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 ``genhtml`` with different configuration file options in parallel. + + Note that this option must be specified in full - abbreviations are not supported. + +``--profile`` [ *profile-data-file* ] + Tell the tool to keep track of performance and other configuration data. If the optional *profile-data-file* is not specified, then the profile data is written to a file named *genhtml.json* in the output directory. + + Profile data is useful if you are trying to optimize the ``lcov`` implementation (see ``$LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py``), and can also enable faster 'genhtml --parallel' execution (see the "--history-script" section of this man page). + +``--history-script`` *script* + Tell the tool to use performance data from a prior job to predict resource usage by the current job. This may allow better segmentation to enable more balanced workloads between parallel threads - thus improving wall clock execution time. + + A common source for the *previous-profile-data-file* is the profile data generated by a prior regression suite execution. See ``$LCOV_ROOT/share/lcov/example`` and ``$LCOV_ROOT/share/lcov/support-scripts/history.pm`` in the installed release (or ``.../example`` in the source repository). + +``--rc`` *keyword* = *value* + Override a configuration directive. + + Use this option to specify a *keyword* = *value* statement which overrides the corresponding configuration statement in the lcovrc configuration file. You can specify this option more than once to override multiple configuration statements. See :manpage:`lcovrc(5)` for a list of available keywords and their meaning. + +``--precision`` *num* + Show coverage rates with *num* number of digits after the decimal point. + + Default value is 1. + + This option can also be configured permanently using the configuration file option *genhtml_precision*. + +``--merge-aliases`` + Functions whose file/line is the same are considered to be aliases; ``genthml`` uses the shortest name in the list of aliases (fewest characters) as the leader. + + This option counts each alias group as a single object - so the 'function' count will be the number of distinct function groups rather than the total number of aliases of all functions - and displays them as groups in the 'function detail table. + + Note that this option has an effect only if ``"--filter function"`` has been applied to the coverage DB. + + This parameter an be configured via the configuration file *merge_function_aliases* option. See ``man(5) lcovrc``. + +``--suppress-aliases`` + Suppress list of aliases in function detail table. + + Functions whose file/line is the same are considered to be aliases; ``genthml`` uses the shortest name in the list of aliases (fewest characters) as the leader. + + The number of aliases can be large, for example due to instantiated templates - which can make function coverage results difficult to read. This option removes the list of aliases, making it easier to focus on the overall function coverage number, which is likely more interesting. + + Note that this option has an effect only if ``"--filter function"`` has been applied to the coverage DB. + + This parameter an be configured via the configuration file *merge_function_aliases* option. See ``man(5) lcovrc``. + +``--forget-test-names`` + If non-zero, ignore testcase names in .info file - *i.e.*, treat all coverage data as if it came from the same testcase. This may improve performance and reduce memory consumption if user does not need per-testcase coverage summary in coverage reports. + + This option can also be configured permanently using the configuration file option *forget_testcase_names*. + +``--missed`` + Show counts of missed lines, functions, branches, and MC/DC expressions. + + Use this option to change overview pages to show the count of lines, functions, branches, or MC/DC expressions that were not hit. These counts are represented by negative numbers. + + When specified together with --sort-tables, file and directory views will be sorted by missed counts. + + This option can also be configured permanently using the configuration file option *genhtml_missed*. + +``--dark-mode`` + Use a light-display-on-dark-background color scheme rather than the default dark-display-on-light-background. + + The idea is to reduce eye strain due to viewing dark text on a bright screen - particularly at night. + +``--tempdir`` *dirname* + Write temporary and intermediate data to indicated directory. Default is "/tmp". + +``--preserve`` + Preserve intermediate data files generated by various steps in the tool - *e.g.*, for debugging. By default, these files are deleted. + +``--save`` + Copy *unified-diff-file, baseline_trace_files,* and *tracefile(s)* to output-directory. + + Keeping copies of the input data files may help to debug any issues or to regenerate report files later. + +``--sort-input`` + Specify whether to sort file names before capture and/or aggregation. Sorting reduces certain types of processing order-dependent output differences. See the *sort_input* section in :manpage:`lcovrc(5)`. + +``--serialize`` *file_name* + Save coverage database to *file_name*. + + The file is in Perl "Storable" format. + + Note that this option may significantly increase *genhtml* memory requirements, as a great deal of data must be retained. + + +FILES +----- + +*/etc/lcovrc* + The system-wide configuration file. + +*~/.lcovrc* + The per-user configuration file. + +Sample *--diff-file* data creation scripts: + + ``scripts/p4udiff`` + Sample script for use with ``--diff-file`` that creates a unified diff file via **Perforce**. + + ``scripts/gitdiff`` + Sample script for use with ``--diff-file`` that creates a unified diff file via **git**. + +Sample *--annotate-script* callback Perl modules: + + ``scripts/p4annotate.pm`` + Sample script written as Perl module for use with ``--annotate-script`` that provides annotation data via **Perforce**. + + ``scripts/gitblame.pm`` + Sample script written as Perl module for use with ``--annotate-script`` that provides annotation data via git. + +Sample *--criteria-script* callback Perl modules: + + ``scripts/criteria.pm`` + Sample script written as Perl module for use with ``--criteria-script`` that implements a check for "UNC + LBC + UIC == 0". + + ``scripts/threshold.pm`` + Sample script written as Perl module to check for minimum acceptable line and/or branch and/or and/or MC/DC function coverage. For example, the + + *"genhtml --fail_under_lines 75 ..."* + + feature can instead be realized by + + *"genhtml --criteria-script scripts/threshold.pm,--line,75 ..."* + +Sample *--simplify-script* callback Perl module: + + ``scripts/simplify.pm`` + Sample script written as Perl module for use with ``--simplify-script`` that implements regular expression substitutions for function name simplification. + +Sample *--version-script* callback Perl modules and scripts: + + ``scripts/getp4version`` + Sample script for use with ``--version-script`` that obtains version IDs via **Perforce**. + + ``scripts/P4version.pm`` + A perl module with similar functionality to **getp4version** but higher performance. + + ``scripts/get_signature`` + Sample script for use with ``--version-script`` that uses md5hash as version IDs. + + ``scripts/gitversion.pm`` + A perl module with for use with ``--version-script`` which retrieves version IDs from **git**. + + ``scripts/batchGitVersion.pm`` + A perl module with similar functionality to **gitversion.pm** but higher performance. + + +AUTHORS +------- + +Peter Oberparleiter + +Henry Cox + Differential coverage and date/owner binning, filtering, error management, parallel execution sections, + + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`lcovrc(5)`, :manpage:`geninfo(1)`, :manpage:`llvm2lcov(1)`, :manpage:`perl2lcov(1)`, :manpage:`py2lcov(1)`, :manpage:`gendesc(1)`, :manpage:`gcov(1)` + +*https://github.com/linux-test-project/lcov* diff --git a/docs/man/geninfo.rst b/docs/man/geninfo.rst new file mode 100644 index 00000000..d21e1ab3 --- /dev/null +++ b/docs/man/geninfo.rst @@ -0,0 +1,946 @@ +============================================ +geninfo - translate GCOV data to LCOV format +============================================ + +NAME +---- + +geninfo + Generate tracefiles from GCOV coverage data files + +SYNOPSIS +-------- + +:: + + geninfo + [-h | --help] + [--version] + [-q | --quiet] + [-v | --verbose] + [--debug] + [--comment *comment-string*] + [-i | --initial] + [--all] + [-t | --test-name *test-name*] + [-o | --output-filename *filename*] + [-f | --follow] + [-b | --base-directory *directory*] + [--build-directory *directory*] + [--branch-coverage] + [--mcdc-coverage] + [--checksum] + [--no-checksum] + [--compat-libtool] + [--no-compat-libtool] + [--gcov-tool *tool*] + [--parallel | -j [*integer*]] + [--large-file *regexp*] + [--memory *integer_num_Mb*] + [--msg-log [*log_file_name*]] + [--ignore-errors *errors*] + [--expect-message-count *message_type* = *expr* [,*message_type* = *expr* ..]] + [--keep-going] + [--preserve] + [--filter *type*] + [--demangle-cpp [param]] + [--no-recursion] + [--external] + [--no-external] + [--sort-input] + [--config-file *config-file*] + [--no-markers] + [--profile [*profile-file*]] + [--history-script *callback*] + [--compat *mode* = on|off|auto] + [--rc *keyword* = *value*] + [--include *glob_pattern*] + [--exclude *glob_pattern*] + [--erase-functions *regexp_pattern*] + [--substitute *regexp_pattern*] + [--omit-lines *regexp_pattern*] + [--fail-under-branches *percentage*] + [--fail-under-lines *percentage*] + [--forget-test-names] + [--context-script *script_file*] + [--criteria-script *script_file*] + [--resolve-script *script_file*] + [--version-script *script_file*] + [--unreachable-script *module_file*] + [--tempdir *dirname*] + *directory* + +DESCRIPTION +----------- + +Use ``geninfo`` to create |ToolName| tracefiles from GCC and LLVM/Clang coverage data files (see ``--gcov-tool`` for considerations when working with LLVM). You can use ``genhtml`` to create an HTML report from a tracefile. + +Note that ``geninfo`` is called by ``lcov --capture``, so there is typically no need to call it directly. + +Unless the ``--output-filename`` option is specified ``geninfo`` writes its output to one file with .info filename extension per input file. + +Note also 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. + +By default, ``geninfo`` collects line and function coverage data. Neither branch nor MC/DC data is not collected by default; you can use the ``--branch-coverage`` and ``--mcdc-coverage`` command line options to enable them, or you can permanently enable them by adding ``branch_coverage = 1`` and/or ``mcdc_coverage = 1`` to your personal, group, or site lcov configuration file. See :manpage:`lcovrc(5)` for details. + +File types +~~~~~~~~~~ + +A ``tracefile`` is a coverage data file in the format used by all |ToolName| tools such as ``geninfo``, ``lcov``, and ``genhtml``. By convention, tracefiles have a .info filename extension. See "Tracefile format" below for a description of the file format. + +A ``.gcda file`` is a compiler-specific file containing run-time coverage data. It is created and updated when a program compiled with GCC/LLVM's ``--coverage`` option is run to completion. ``geninfo`` reads .gcda files in its default mode of operation. Note: earlier compiler versions used the .da filename extension for this file type. + +A ``.gcno file`` is a compiler-specific file containing static, compile-time coverage data. It is created when source code is compiled with GCC/LLVM's ``--coverage`` option. ``geninfo`` reads .gcno files when option ``--initial`` is specified. Note: earlier compiler versions used .bb and .bbg filename extensions for this file type. + +A ``.gcov file`` is a textual or JSON representation of the data found in .gcda and .gcno files. It is created by the ``gcov`` tools that is part of GCC (see ``--gcov-tool`` for LLVM considerations). There are multiple gcov file format versions, including textual, intermediate, and JSON format. ``geninfo`` internally uses ``gcov`` to extract coverage data from .gcda and .gcno files using the best supported gcov file format. + +See the ``gcov`` man page for more information on .gcda, .gcno and .gcov output formats. + +Exclusion markers +~~~~~~~~~~~~~~~~~ + +To exclude specific lines of code from a tracefile, you can add exclusion markers to the source code. Similarly, you can mark specific regions of code as "unreachable". An "unreachable" error message is generated if any coverpoints in unreachable regions are executed (*i.e.,* have non-zero hit counts. See the *retain_unreachable_coverpoints_if_executed* section in :manpage:`lcovrc(1)` for a description of the actions taken in this case. + +Additionally you can exclude specific branches or MC/DC expressions 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 :manpage:`lcovrc(5)` how to override the exclusion keywords (*e.g.,* to reuse markers inserted for other tools or to generate reports with different sets of excluded regions). + +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_UNREACHABLE_LINE`` + If the marked line is 'hit', then generate an error: we believe the marked code is unreachable and so there is a bug in the code, the placement of the directive, or both. Lines containing this marker will be excluded from reporting. Apart from error reporting, this directive is equivalent to *LCOV_EXCL_LINE.* + +``LCOV_UNREACHABLE_START`` + Marks the beginning of an unreachable section of code. The current line in part of this region. As described in the *LCOV_UNREACHABLE_LINE* section, above: an error is generated if any code in the region is hit, but the code is excluded from reporting. + +``LCOV_UNREACHABLE_STOP`` + Marks the end of the region of unreachable code. The current line not part of this section. + +``LCOV_EXCL_BR_LINE`` + Lines containing this marker will be excluded from branch coverage. + +``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 coverage. The current line not part of this section. + +``LCOV_EXCL_EXCEPTION_BR_LINE`` + Lines containing this marker will be excluded from exception branch coverage: Exception branches will be ignored, but non-exception branches will not be affected. + +``LCOV_EXCL_EXCEPTION_BR_START`` + Marks the beginning of a section which is excluded from exception branch coverage. The current line is part of this section. + +``LCOV_EXCL_EXCEPTION_BR_STOP`` + Marks the end of a section which is excluded from exception branch coverage. The current line not part of this section. + +In addition, ``geninfo`` also supports the *"--unreachable-script"* option. This provides a mechanism to exclude particular branch expressions and/or MC/DC conditions from coverage reports. A simple sample callback can be found in: + + ``bin``/unreach.pm. + +This sample callback adds support for branch-specific and condition-specific exclusion, specified by end-of-line annotations in the source code: + +``LCOV_EXCLUDE_BRANCH (expressionId[,blockId])+`` + One or more space-separated branch exclusions may specified. + + ``expressionId``: + decimal integer which specifies which branch to exclude. An error is generated if the index is invalid + + ``blockId`` + decimal integer which specified the block index which contains the excluded expression. An error is generated if the block index is invalid. If there is only one branch block at this location, then the block ID does not need to be specified + +``LCOV_UNREACHABLE_COND ([groupSize,]conditionId(t|f))+`` + One or more space-separated MC/DC exclusions may specified. + + ``groupSize`` + decimal integer which specified the group which contains the excluded condition. An error is generated if the groupSize is invalid. If there is only one MC/DC group at this location, then the groupSize does not need to be specified. + + ``conditionId`` + decimal integer which specifies which condition to exclude. An error is generated if the index is invalid + + ``sense`` + 't' or 'f': the value of the condition which is unreachable + +For example, the line: + +:: + + code // LCOV_EXCLUDE_BRANCH 0,1 3 LCOV_EXCLUDE_CONDITION 0f + +will exclude branch expressions 1 and 3 from block 0 (or generate an error if there is more than one branch block on this line), and the 'false' sense of condition 0 (or generate an error if there is more than one MC/DC group on this line). + +One way to determine the branch and/or condition ID in order to exclude them is to generate an HTML report without exclusions then hover the mouse over the colorized branch/condition region and read the IDs from the tooltip popup. Another way is to simply read the BRDA/MCDC entries in coverage data file. + +See the comment at the top of the sample script for more details. + +OPTIONS +------- + +In general, (almost) all ``geninfo`` options can also be specified in your personal, group, project, or site configuration file - see the *--config-file* section, below, and :manpage:`lcovrc(5)` for details. + +``-b``, ``--base-directory`` *directory* + Use *directory* as base directory for relative paths. + + Use this option to specify the base directory of a build-environment when geninfo produces error messages like: + + :: + + ERROR: could not read source file /home/user/project/subdir1/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 directory 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 multiple base directories are used. In that case use configuration file setting ``geninfo_auto_base=1`` (see :manpage:`lcovrc(5)`). + +``--build-directory`` *build_dir* + Search for .gcno data files from *build_dir* rather finding them only adjacent to the corresponding .o and/or .gcda file. + + By default, geninfo expects to find the .gcno and .gcda files (compile- and run-time data, respectively) in the same directory. + + When this option is used: + + :: + + geninfo path1 --build-directory path2 ... + + then geninfo will look for .gcno file + + :: + + path2/relative/path/to/da_base.gcno + + when it finds .gcda file + + :: + + path1/relative/path/to/da_base.gcda. + + Use this option when you have used the *GCOV_PREFIX* environment variable to direct the gcc or llvm runtime environment to write coverage data files to somewhere other than the directory where the code was originally compiled. See :manpage:`gcc(1)` and/or search for *GCOV_PREFIX* and *GCOV_PREFIX_STRIP*. + + This option can be used several times to specify multiple alternate directories to look for .gcno files. This may be useful if your application uses code which is compiled in many separate locations - for example, common libraries that are shared between teams. + +``--source-directory`` *dirname* + Add 'dirname' to the list of places to look for source files. + + For relative source file paths found in the gcov data - possibly after substitutions have been applied, ``geninfo`` will first look for the path from 'cwd' (where genhtml was invoked) and then from each alternate directory name in the order specified. The first location matching location is used. + + This option can be specified multiple times, to add more directories to the source search path. + +``--branch-coverage`` + Collect retain branch coverage data. + + This is equivalent to using the option "--rc branch_coverage=1"; the option was added to better match the genhtml interface. + +``--mcdc-coverage`` + Collect retain MC/DC data. + + This is equivalent to using the option "--rc mcdc_coverage=1". MC/DC coverage capture is supported for GCC versions 14.2 and higher, or LLVM versions 18.1 and higher. + + See *llvm2lcov --help* for details on MC/DC data capture in LLVM. + + See the MC/DC section of :manpage:`genhtml(1)` for more details. + +``--checksum``, ``--no-checksum`` + Specify whether to generate checksum data when writing tracefiles. + + 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 generated for each source code line and stored along with the coverage data. This checksum will be used to prevent attempts to combine 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. + + Note that this options is somewhat subsumed by the ``--version-script`` option - which does something similar, but at the 'whole file' level. + +``--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 provide 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 versions. 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 .gcda file located in a directory 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. See :manpage:`lcovrc(5)` for details of the file format and options. Also see the *config_file* entry in the same man page for details on how to include one config file into another. + + When this option is specified, neither the system-wide configuration 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. + + Note that this option must be specified in full - abbreviations are not supported. + +``--profile`` [*profile-data-file*] + Tell the tool to keep track of performance and other configuration data. If the optional *profile-data-file* is not specified, then the profile data is written to a file named with the same basename as the *--output-filename*, with suffix *".json"* appended. + + Profile data is useful if you are trying to optimize the ``geninfo`` implementation (see ``$LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py``), and can also enable faster 'geninfo --parallel' execution (see the "--history-script" section of this man page). + +``--history-script`` *callback* + Tell the tool to use performance data from a prior job to predict resource usage by the current job. This may allow better segmentation to enable more balanced workloads between parallel threads - thus improving wall clock execution time. + + A common source for the performance history is the *previous-profile-data-file* generated by the *"--profile"* argument. + + See a sample callback implementation in ``$LCOV_ROOT/share/lcov/support-scripts/history.pm`` and its use in ``$LCOV_ROOT/share/lcov/example`` in the installed release (or ``.../example`` and ``.../scripts/history.pm`` in the source repository). + + See :manpage:`genhtml(1)` for more details. + +``--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 coverpoints in external source files while capturing coverage data or *--no-external* to exclude them. If your *--directory* or *--base-directory* path contains a soft link, then actual target directory is not considered to be "internal" unless the *--follow* option is used. + + The *--no-external* option is somewhat of a blunt instrument; the *--exclude* and *--include* options provide finer grained control over which coverage data is and is not included if your project structure is complex and/or *--no-external* does not do what you want. + + Data for external source files is ``included`` by default. + +``-f``, ``--follow`` + Follow links when searching .gcda files, as well as to decide whether a particular (symbolically linked) source directory is "internal" to the project or not - see the *--no-external* option, above, for more information. The *--follow* command line option is equivalent to the *geninfo_follow_symlinks* config file option. See :manpage:`lcovrc(5)` for more information. + +``--sort-input`` + Specify whether to sort file names before capture and/or aggregation. Sorting reduces certain types of processing order-dependent output differences. See the ``sort_input`` section in :manpage:`lcovrc(5)`. + +``--gcov-tool`` *tool* + Specify the location of the gcov tool. + + If the ``--gcov-tool`` option is used multiple times, then the arguments are concatenated when the callback is executed - similar to how the gcc ``-Xlinker`` parameter works. This provides a possibly easier way to pass arguments to your tool, without requiring a wrapper script. In that case, your callback will be executed as: *tool-0 'tool-1; ... 'filename'*'. Note that the second and subsequent arguments are quoted when passed to the shell, in order to handle parameters which contain spaces. + + The ``--gcov-tool`` argument may be a *split_char* separated string - see ``man(4) lcovrc``. + + A common use for this option is to enable LLVM: + + :: + + geninfo --gcov-tool llvm-cov --gcov-tool gcov ... + geninfo --gcov-tool llvm-cov,gcov ... + + Note: 'llvm-cov gcov da_file_name' will generate output in gcov-compatible format as required by lcov. + + If not specified, 'gcov' is used by default. + +``-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 patterns. Multiple patterns can be specified by using multiple ``--include`` command line switches. The *patterns* will be interpreted as shell wildcard patterns (note that they may need to be escaped accordingly to prevent the shell from expanding them first). + + See the lcov man page for details. + +``--exclude`` *pattern* + Exclude source files matching *pattern*. + + Use this switch if you want to exclude coverage data from a particular 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 accordingly to prevent the shell from expanding them first). Note: The pattern must be specified to match the ``absolute`` path of each source file. + + Can be combined with the ``--include`` command line switch. If a given file matches both the include pattern and the exclude pattern, the exclude pattern will take precedence. + + See the lcov man page for details. + +``--erase-functions`` *regexp* + Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the --demangle-cpp option is used or not. + + Note that this option requires that you use a gcc version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the ``derive_function_end_line`` discussion in the ``lcovrc`` man page. + +``--substitute`` *regexp_pattern* + Apply Perl regexp *regexp_pattern* to source file names found during processing. This is useful when the path name reported by gcov does not match your source layout and the file is not found. See the lcov man page for more details. + +``--omit-lines`` *regexp* + Exclude coverage data from lines whose content matches *regexp*. + + Use this switch if you want to exclude line, branch, and MC/DC coverage data for some particular constructs in your code (*e.g.*, some complicated macro). See the lcov man page for details. + +``--forget-test-names`` + If non-zero, ignore testcase names in tracefile - *i.e.,* treat all coverage data as if it came from the same testcase. This may improve performance and reduce memory consumption if user does not need per-testcase coverage summary in coverage reports. + + This option can also be configured permanently using the configuration file option *forget_testcase_names*. + +``--msg-log`` [*log_file_name*] + Specify location to store error and warning messages (in addition to writing to STDERR). If *log_file_name* is not specified, then default location is used. + +``--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 errors after which ``geninfo`` should continue processing instead of aborting. Note that the tool will generate a warning (rather than a fatal error) unless you ignore the error two (or more) times: + + :: + + geninfo ... --ignore-errors unused,unused + + *errors* can be a comma-separated list of the following keywords: + + ``branch`` + branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. + + ``callback`` + Version script error. + + ``child`` + child process returned non-zero exit code during *--parallel* execution. This typically indicates that the child encountered an error: see the log file immediately above this message. In contrast: the ``parallel`` error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. + + ``corrupt`` + corrupt/unreadable file found. + + ``count`` + An excessive number of messages of some class have been reported - subsequent messages of that type will be suppressed. The limit can be controlled by the 'max_message_count' variable. See the lcovrc man page. + + ``deprecated`` + You are using a deprecated option. This option will be removed in an upcoming release - so you should change your scripts now. + + ``empty`` + the .info data file is empty (*e.g.*, because all the code was 'removed' or excluded. + + ``excessive`` + your coverage data contains a suspiciously large 'hit' count which is unlikely to be correct - possibly indicating a bug in your toolchain. + + See the *excessive_count_threshold* section in :manpage:`lcovrc(5)` for details. + + ``fork`` + Unable to create child process during *--parallel* execution. + If the message is ignored (*--ignore-errors fork*), then genhtml will wait a brief period and then retry the failed execution. + If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. + + ``format`` + Unexpected syntax or value found in .info file - for example, negative number or zero line number encountered. + + ``gcov`` + the gcov tool returned with a non-zero return code. + + ``graph`` + the graph file could not be found or is corrupted. + + ``inconsistent`` + your coverage data is internally inconsistent: it makes two or more mutually exclusive claims. For example, some expression is marked as both an exception branch and not an exception branch. (See :manpage:`genhtml(1)` for more details. + + ``internal`` + internal tool issue detected. Please report this bug along with a testcase. + + ``mismatch`` + Incorrect information found in coverage data and/or source code - for example, the source code contains overlapping exclusion directives. + + ``missing`` + File does not exist or is not readable. + + ``negative`` + negative 'hit' count found. + + Note that negative counts may be caused by a known GCC bug - see + + :: + + https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 + + and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. + + ``package`` + a required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. + + ``parallel`` + various types of errors related to parallelism - *i.e.,* a child process died due to an error. The corresponding error message appears in the log file immediately before the *parallel* error. + + If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the --parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. + + ``parent`` + the parent process exited while child was active during *--parallel* execution. This happens when the parent has encountered a fatal error - *e.g.* an error in some other child which was not ignored. This child cannot continue working without its parent - and so will exit. + + ``path`` + some file paths were not resolved - *e.g.*, .gcno file corresponding to some .gcda was not found see *--build-directory* option for additional information. + + ``range`` + Coverage data refers to a line number which is larger than the number of lines in the source file. This can be caused by a version mismatch or by an issue in the *gcov* data. + + ``source`` + the source code file for a data set could not be found. + + ``unreachable`` + a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the *retain_unreachable_coverpoints_if_executed* configuration parameter. See :manpage:`lcovrc(5)` and the *"Exclusion markers"* section, above. + + ``unsupported`` + the requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. + + ``unused`` + the include/exclude/erase/omit/substitute pattern did not match any file pathnames. + + ``usage`` + unsupported usage detected - *e.g.* an unsupported option combination. + + ``utility`` + a tool called during processing returned an error code (*e.g.*, 'find' encountered an unreadable directory). + + ``version`` + revision control IDs of the file which we are trying to merge are not the same - line numbering and other information may be incorrect. + + Also see the *--ignore-errors* section in :manpage:`genhtml(1)`. The description there may be more complete and/or more fully explained. + + See :manpage:`lcovrc(5)` for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. + +``--expect-message-count`` *message_type* = *expr* [,*message_type* = *expr*] + Give ``geninfo`` a constraint on the number of messages of one or more types which are expected to be produced during execution. If the constraint is not true, then generate an error of type *"count"* (see above). + + See :manpage:`genhtml(1)` for more details about the flag, as well as the *"expect_message_count"* section in :manpage:`lcovrc(5)` for a description of the equivalent configuration file option. + +``--keep-going`` + Do not stop if error occurs: attempt to generate a result, however flawed. + + This command line option corresponds to the *stop_on_error [0|1]* lcovrc option. See :manpage:`lcovrc(5)` for more details. + +``--fail-under-lines`` *percentage* + Use this option to tell geninfo to exit with a status of 1 if the total line coverage is less than *percentage.* See :manpage:`lcov(1)` for more details. + +``--preserve`` + Preserve intermediate data files (*e.g.*, for debugging). + + By default, intermediate files are deleted. + +``--filter`` *filters* + Specify a list of coverpoint filters to apply to input data. See the genhtml man page for details. + +``--demangle-cpp`` [param] + Demangle C++ method and function names in captured output. See the genhtml man page for details. + +``-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 correct even when not all object code files were loaded during the test. Also see the *--all* flag, below. + + Note: the ``--initial`` option is not supported for gcc versions less than 6, and does not generate branch coverage information for gcc versions less than 8. + +``--all`` + Capture coverage data from both compile time (.gcno) data files which do not have corresponding runtime (.gcda) data files, as well as from those that *do* have corresponding runtime data. There will be no runtime data unless some executable which links the corresponding object file has run to completion. + + Note that the execution count of coverpoints found only in files which do not have any runtime data will be zero. + + This flag is ignored if the *--initial* flag is set. + + Using the ``--all`` flag is equivalent to executing both *geninfo --initial ...* and *geninfo ...* and merging the result. + + Also see the *geninfo_capture_all* entry in ``man(5) lcovrc``. + +``--no-markers`` + Unless the *--no-markers* option is used, ``geninfo`` will apply both *region* and *branch_region* filters to the captured coverage data. Use this option if you want to get coverage data without regard to exclusion markers in the source code file. + + If any *--filter* options are applied, then the default region filters are not used. + + *--no-markers* should not be specified along with *--filter*. + +``--no-recursion`` + Use this option if you want to get coverage data for the specified directory only without processing subdirectories. + +``-o``, ``--output-filename`` *output-filename* + Write all data to *output-filename*. + + If you want to have all data written to a single file (for easier handling), use this option to specify the respective filename. By default, one tracefile will be created for each processed .gcda file. + +``--context-script`` *script* + Use *script* to collect additional tool execution context information - to aid in infrastructure debugging and/or tracking. + + See the genhtml man page for more details on the context script. + +``--criteria-script`` *script* + Use *script* to test for coverage acceptance criteria. + + See the genhtml man page for more details on the criteria script. Note that geninfo does not keep track of date and owner information (see the *--annotate-script* entry in the genhtml man page) - so this information is not passed to the geninfo callback. + +``--resolve-script`` *script* + Use *script* to find the file path for some source or GCNO file which appears in an input data file if the file is not found after applying *--substitute* patterns and searching the *--source-directory* or *--build-directory* list. + + This option is equivalent to the ``resolve_script`` config file option. In addition, the *geninfo_follow_path_links* config file option can be used to resolve source paths to their actual target. + + See :manpage:`lcovrc(5)` for details. + +``--version-script`` *script* + Use *script* to get a source file's version ID from revision control when extracting data. The ID is used for error checking when merging .info files. + + See the genhtml man page for more details on the version script. + +``--unreachable-script`` *module* + Use *module* to decide whether particular branch expressions and/or MC/DC conditions should be removed from the coverage report. This option is equivalent to the ``unreachable_script`` config file option. See :manpage:`lcovrc(5)` for details. + + Note that *"module"* is required to be a Perl module. + + See the genhtml man page and the *"Exclusion markers"* section, above, for more information. + +``-v``, ``--verbose`` + Increment informational message verbosity. This is mainly used for script and/or flow debugging - *e.g.*, to figure out which data file are found, where. Also see the ``--quiet`` flag. + + Messages are sent to stdout unless there is no output file (*i.e.*, if the coverage data is written to stdout rather than to a file) and to stderr otherwise. + +``-q``, ``--quiet`` + Decrement informational message verbosity. + + Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. + +``--debug`` + Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. + +``--comment`` *comment_string* + Append *comment_string* to list of comments emitted into output result file. This option may be specified multiple times. Comments are printed at the top of the file, in the order they were specified. + + Comments can be useful to document the conditions under which the trace file was generated: host, date, environment, *etc.* + +``--parallel`` [*integer*], ``-j`` [*integer*] + Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). + + The *--large-file* option described below may be necessary to enable parallelism to succeed in the presence of data files which consume excessive memory in ``gcov``. + + Also see the *memory, memory_percentage, max_fork_fails, fork_fail_timeout, geninfo_chunk_size* and *geninfo_interval_update* entries in :manpage:`lcovrc(5)` for a description of some options which may aid in parameter tuning and performance optimization. A previously generated execution profile may help to enable better utilization and faster parallel execution. See the *"--profile"* and *"--history-script"* sections of this man page. + +``--large-file`` *regexp* + GCDA files whose name matches a *--large-file* regexp are processed serially - not in parallel with other files - so that their ``gcov`` process can use all available system memory. + + Use this option is you see errors related to memory allocation from gcov. + + This feature is exactly as if you had moved the matching GCDA files to another location and processed them serially, then processed remaining GDCA files in parallel and merged the results. + + This option may be used multiple times to specify more than one regexp. + +``--memory`` *integer* + Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. + + This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does now know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. + + The configuration file *memory_percentage* option provided another way to set the maximum memory consumption. See :manpage:`lcovrc(5)` for details. + +``--rc`` *keyword* = *value* + Override a configuration directive. + + Use this option to specify a *keyword = value* statement which overrides the corresponding configuration statement in the lcovrc configuration file. You can specify this option more than once to override multiple configuration statements. See :manpage:`lcovrc(5)` for a list of available keywords and their meaning. + +``-t``, ``--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. + +``--version`` + Print version number, then exit. + +``--tempdir`` *dirname* + Write temporary and intermediate data to indicated directory. Default is "/tmp". + +TRACEFILE FORMAT +---------------- + +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 the ``---comment comment_string`` option is supplied, then: + +:: + + #comment_string + +will appear at the top of the tracefile. There is no space before or after the *#* character. + +If available, a tracefile begins with the *testname* which is stored in the following format: + +:: + + TN: + +For each source file referenced in the .gcda file, there is a section containing filename and coverage data: + +:: + + SF: + +An optional source code version ID follows: + +:: + + VER: + +If present, the version ID is compared before file entries are merged (see ``lcov --add-tracefile``), and before the 'source detail' view is generated by genhtml. See the ``--version-script callback_script`` documentation and the sample usage in the lcov regression test examples. + +Function coverage data follows. Note that the format of the function coverage data has changed from LCOV 2.2 onward. The tool continues to be able to read the old format but now writes only the new format. This change was made so that ``function`` filter outcome is persistent in the generated tracefile. + +Functions and their aliases are recorded contiguously: + +First, the leader: + +:: + + FNL:,[,line number of function end>] + +Then the aliases of the function; there will be at least one alias. All aliases of a particular function share the same index. + +:: + + FNA:,, + +The now-obsolete function data format is: + +:: + + FN:,[,] + +The 'end' line number is optional, and is generated only if the compiler/toolchain version is recent enough to generate the data (*e.g.*, gcc 9 or newer). This data is used to support the ``--erase-functions`` and ``--show-proportions`` options. If the function end line data is not available, then these features will not work. + +Next, there is a list of execution counts for each instrumented function: + +:: + + FNDA:, + +This list is followed by two lines containing the number of functions found and hit: + +:: + + FNF: + FNH: + +Note that, as of LCOV 2.2, these numbers count function groups - not the individual aliases. + +Branch coverage information is stored one line per branch: + +:: + + BRDA:,[][],, + +** + is the line number where the branch is found - and is expected to be a non-zero integer. + +** and ** + serve to uniquely define a particular edge in the expression tree of a particular conditional found on the associated line. + + Within a particular line, ** is an integer numbered from zero with no gaps. For some languages and some coding styles, there will only be one block (index value zero) on any particular line. + + ** is a string which serves to uniquely identify a particular edge. For some languages and tools - *e.g.*, C/C++ code compiled with gcc or llvm - ** is an ordered integer index related to expression tree traversal order of the associated conditional. For others, it may be a meaningful string - see below. ** appears in the 'tooltip' popup of the associated branch in the ``genhtml`` output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage. + +** + is either '-' if the corresponding expression was never evaluated (*e.g.*, the basic block containing the branch was never executed) or a number indicating how often that branch was taken. + +** + is 'e' (single character) if this is a branch related to exception handling - and is not present if the branch is not related to exceptions. Exception branch identification requires compiler support. geninfo will be able to identify exception branches only if your toolchain version is new enough to support the feature. + +** + is 'f' (single character) if this is a branch is marked as 'fallthrough' (*e.g.*, in the gcov output) - and is not present if the branch is not marked. Fallthrough branch identification requires compiler support. geninfo will be able to identify fallthrough branches only if your toolchain version is new enough to support the feature. A branch may be marked as '' or '* + is 'U' (single character) if this branch is associated with an 'unreachable directive, and is not present if the branch is reachable. Unreachability is intended to mark branch expressions which are should not appear in coverage reports - enabling users to ignore uncovered branches which can never be covered, to concentrate on other areas of the coverage report. + + See the *"--unreachable-script"* discussion in :manpage:`genhtml(1)` and the *"ignore_unreachable_flag"* discussion in :manpage:`lcovrc(5)` for more information on how branch exclusion markers are set and used. + +The following are example branch records whose ** expression values are human-readable strings. + +:: + + BRDA:10,0,enable,1 + BRDA:10,0,!enable,0 + +In this case, the corresponding code from line 10 is very likely similar to: + +:: + + if (enable) { + ... + } + +such that the associated testcase entered the block ('enable' evaluated to 'true'). + +Arbitrarily complicated branch expressions are supported - including branch expressions which contain commas (*e.g.,* in an expression containing a function call). + +Note that particular tools may or may not suppress expressions which are statically true or statically false - *e.g.,* expressions using template parameters. This makes it potentially complicated to compare coverage data generated by two different tools. + +A note on branch identification, matching, and merging: + +As noted previously: lcov merely presents coverage data which is identified by other tools such as gcov. Unfortunately, gcov (and other tools) do not produce sufficient information to uniquely identify branch expressions - so lcov is forced to use a heuristic solution based on the order of appearance as well as the number and type of individual branch elements - say, in the gcov output. + +lcov computes a 'signature' for each "". If the block ID and signature found while capturing data from multiple files or while merging coverage data - then the block is considered identical and corresponding expression counts are combined. + +Within a particular line, there may be one or more blocks with the same signature - for example, corresponding to independent branch expressions in function call arguments on that line, or to different macro or template expansion. lcov keeps track of the order that branch blocks were found (say, in the gcov output or in an lcov .info file). + +When merging branch data on a particular line: + +- Blocks which have different signatures are considered to be distinct. + +- Blocks which have identical signatures are matched in order: the zeroth block with signature *s1* in coverage DB A is merged with the zeroth block with signature *s1* in coverage DB B - and so on. + +- If one or the other DB does not contain some signature, or one DB contains more blocks with the same signature: then those non-matching blocks are simply copied to the merged output. + +This heuristic can cause ambiguity in the generated report - especially for cases that a particular line expands in different ways in different compilation units - *e.g.,* due to template or macro expansion. In such cases, it may not be possible for lcov to know that some block whose signature and order appear to match, is not actually the same block. It may be possible to refactor the code slightly to introduce explicit temporaries (on their own line) to resolve the ambiguity. + +Branch coverage summaries are stored in two lines: + +:: + + BRF: + +Note that this count does not include 'excluded' branches. Excluded branches *do* appear as BRDA records. + +:: + + BRH: + +Note that this count does not include 'excluded' branches. Excluded branches *do* appear as BRDA records. + +MC/DC information is stored one line per expression: + +:: + + MCDC:,[],,,, + +where: + +** + is the line number where the condition is found - and is expected to be a non-zero integer. + +** and ** + serve to uniquely define a particular element in the expression tree of a particular conditional found on the associated line. + + Within a particular line and group, + +** + is an integer numbered from zero to * - 1* with no gaps. For some languages and some coding styles, there will only be one group on any particular line. + +** + is either *"f"* or *"t"*, indicating whether the condition is sensitive to the indicated change - that is, does the condition outcome change if the corresponding changes from 'false' to 'true' or from 'true to false, respectively. + +** + is a count - 0 (zero) if the expression was not senstized, non-zero if it was senstized. Note that tome tools may treat ** as the number of times that the expression was sensitized where others may treat it as a boolean - 1:sensitized or 0: not sensitized. + +** + is an arbitrary string, intended to be a meaningful string which will help the user to understand the condition context - see below. ** appears in the 'tooltip' popup of the associated MC/DC condition in the ``genhtml`` output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage. + + For a given and , the should be identical for both "t" and "f" senses. + +** + is 'U' (single character) if this condition is associated with an 'unreachable directive, and is not present if the condition is reachable. Unreachability is intended to mark conditions which should not appear in coverage reports - enabling users to ignore uncovered conditions which can never be covered, to concentrate on other areas of the coverage report. + + See the *"--unreachable-script"* discussion in :manpage:`genhtml(1)` and the *"ignore_unreachable_flag"* discussion in :manpage:`lcovrc(5)` for more information on how branch exclusion markers are set and used. + +The following are example MC/DC records whose ** values are human-readable strings. + +:: + + MCDC:10,2,f,0,0,enable + MCDC:10,2,t,1,0,enable + ... + +In this case, the corresponding code from line 10 is very likely similar to: + +:: + + if (enable ...) { + ... + } + +such that the associated testcase was sensitive to a change of 'enable' from true to false (but not the converse). + +Arbitrarily complicated expressions are supported - including expressions which contain commas (*e.g.,* in an expression containing a function call). + +Note that particular tools may or may not suppress expressions which are statically true or statically false - *e.g.,* expressions using template parameters. This makes it potentially complicated to compare coverage data generated by two different tools. + +MCDC coverage summaries are stored in two lines: + +:: + + MCF: + +Note that this count does not include 'excluded' conditions. Excluded branches *do* appear as MCDC records. + +:: + + MCH: + +Note that this count does not include 'excluded' conditions. Excluded branches *do* appear as MCDC records. + +Then there is a list of execution counts for each instrumented line (*i.e.* a line which resulted in executable code): + +:: + + DA:,[,] + +Note that there may be an optional checksum present for each instrumented 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: + LF: + +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 interpreting the contents of the respective .gcno file (see :manpage:`gcov(1)` for more information on this file type). Relative filenames are prefixed with the directory in which the .gcno file is found. + +Note also that symbolic links to the .gcno file will be resolved so that the actual file path is used instead of the path to a link. This approach is necessary for the mechanism to work with the /proc/gcov files. + +FILES +----- + +*/etc/lcovrc* + The system-wide configuration file. + +*~/.lcovrc* + The per-user configuration file. + +``bin``/getp4version + Sample script for use with ``--version-script`` that obtains version IDs via Perforce. + +``bin``/get_signature + Sample script for use with ``--version-script`` that uses md5hash as version IDs. + +AUTHOR +------ + +Peter Oberparleiter + +Henry Cox + Filtering, error management, parallel execution sections. + +SEE ALSO +-------- + +:manpage:`genhtml(1)`, :manpage:`lcov(1)`, :manpage:`lcovrc(5)`, +:manpage:`gcov(1)`, +:manpage:`llvm2lcov(1)` + +https://github.com/linux-test-project/lcov diff --git a/docs/man/genpng.rst b/docs/man/genpng.rst new file mode 100644 index 00000000..48086239 --- /dev/null +++ b/docs/man/genpng.rst @@ -0,0 +1,81 @@ +====================================================== +genpng - generate overview PNG file from coverage data +====================================================== + +NAME +---- + +genpng + Generate an overview image from a source file (internal tool) + +:Manual section: 1 +:Manual group: |ToolName| 2.0 +:Date: 2023-05-12 + +SYNOPSIS +-------- + +:: + + genpng [ -h | --help ] + [ -v | --version ] + [ -t | --tab-size *tabsize* ] + [ -w | --width *width* ] + [ -d | --dark-mode ] + [ -o | --output-filename *output-filename* ] + source-file + +DESCRIPTION +----------- + +**genpng** creates an overview image for a given source code file of either +plain text or .gcov file format. + +Note that the *GD.pm* Perl module has to be installed for this script to work +(it may be obtained from http://www.cpan.org). + +Note also that **genpng** is called from within **genhtml** so that there is +usually no need to call it directly. + +OPTIONS +------- + +**-h**, **--help** + Print a short help text, then exit. + +**-v**, **--version** + Print version number, then exit. + +**-t** *tab-size*, **--tab-size** *tab-size* + Use *tab-size* spaces in place of tab. + + All occurrences of tabulator signs in the source code file will be replaced + by the number of spaces defined by *tab-size* (default is 4). + +**-w** *width*, **--width** *width* + Set width of output image to *width* pixel. + + The resulting image will be exactly *width* pixel wide (default is 80). + + Note that source code lines which are longer than *width* will be truncated. + +**-d**, **--dark-mode** + Use a light-display-on-dark-background color scheme rather than the default + dark-display-on-light-background. + +**-o** *filename*, **--output-filename** *filename* + Write image to *filename*. + + Specify a name for the resulting image file (default is *source-file*.png). + +AUTHOR +------ + +Peter Oberparleiter + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)`, :manpage:`gendesc(1)`, :manpage:`gcov(1)` + +https://github.com/linux-test-project/lcov diff --git a/docs/man/lcov.rst b/docs/man/lcov.rst new file mode 100644 index 00000000..e553eb19 --- /dev/null +++ b/docs/man/lcov.rst @@ -0,0 +1,1513 @@ +========================================================================= +lcov - capture and manipulate coverage data from lcov tracefiles or gcov. +========================================================================= + +NAME +---- + +lcov +Capture and manipulate coverage data from lcov tracefiles or gcov + +SYNOPSIS +-------- + +Capture coverage data tracefile (from compiler-generated data). +The lcov tracefile (".info" file) format is described in :manpage:`geninfo(1)`. + +:: + + lcov -c | --capture + [ -d | --directory *directory* ] + [ -k | --kernel-directory *directory* ] + [ -o | --output-file *tracefile* ] + [ -t | --test-name *testname* ] + [ -b | --base-directory *directory* ] + [ --build-directory *directory* ] + [ --source-directory *directory* ] + [ -i | --initial ] + [ --all ] + [ --gcov-tool *tool* ] + [ --branch-coverage ] + [ --mcdc-coverage ] + [ --demangle-cpp [ *param* ] ] + [ --checksum ] + [ --no-checksum ] + [ --no-recursion ] + [ -f | --follow ] + [ --sort-input ] + [ --compat-libtool ] + [ --no-compat-libtool ] + [ --msg-log [ *log_file_name* ] ] + [ --ignore-errors *errors* ] + [--expect-message-count *message_type=expr[,message_type=expr..]*] + [ --preserve ] + [ --to-package *package* ] + [ --from-package *package* ] + [ --no-markers ] + [ --external ] + [ --no-external ] + [ --compat *mode*\ =on|off|auto] + [ --context-script *script_file* ] + [ --criteria-script *script_file* ] + [ --history-script *callback* ] + [ --resolve--script *script_file* ] + [ --version-script *script_file* ] + [ --unreachable-script *callback* ] + [ --comment *comment_string* ] + [ --large-file *regexp* ] + +Generate tracefile (from compiler-generated data) with all counter values set to zero: + +:: + + lcov -z | --zerocounters + [ -d | --directory *directory* ] + [ --no-recursion ] + [ -f | --follow ] + +Show coverage counts recorded in previously generated tracefile: + +:: + + lcov -l | --list *tracefile* + [ --list-full-path ] + [ --no-list-full-path ] + +Aggregate multiple coverage tracefiles into one: + +:: + + lcov -a | --add-tracefile *tracefile_pattern* + [ -o | --output-file *tracefile* ] + [ --prune-tests ] + [ --forget-test-names ] + [ --map-functions ] + [ --branch-coverage ] + [ --mcdc-coverage ] + [ --checksum ] + [ --no-checksum ] + [ --sort-input ] + +Depending on your use model, it may not be necessary to create aggregate coverage data files. +For example, if your regression tests are split into multiple suites, you may want to keep separate suite data and to compare both per-suite and aggregate results over time. +``genhtml`` allows you specify tracefiles via one or more glob patterns - which enables you +generate aggregate reports without explicitly generating aggregated trace files. +See the ``genhtml`` man page. + +Generate new tracefile from existing tracefile, keeping only data from files matching pattern: + +:: + + lcov -e | --extract *tracefile pattern* + [ -o | --output-file *tracefile* ] + [ --checksum ] + [ --no-checksum ] + +Generate new tracefile from existing tracefile, removing data from files matching pattern: + +:: + + lcov -r | --remove *tracefile pattern* + [ -o | --output-file *tracefile* ] + [ --checksum ] + [ --no-checksum ] + +Generate new tracefile from existing tracefiles by performing set operations on coverage data: + +:: + + lcov --intersect *rh_glob_pattern* + [ -o | --output-file *tracefile* ] + lh_glob_pattern + +The output will reflect + + *(union of files matching lh_glob_patterns)* *intersect* *(union of files matching rh_glob_patterns)* + +such that coverpoints found in both sets are merged (summed) whereas coverpoints found in only one set are dropped. +Note that branch blocks are defined to be the same if and only if their block ID and the associated branch expressions list are identical. +Functions are defined to be the same if their name and location are identical. + +:: + + lcov --subtract *rh_glob_pattern* + [ -o | --output-file *tracefile* ] + lh_glob_pattern + +The output will reflect + + *(union of files matching lh_glob_patterns)* *subtract* *(union of files matching rh_glob_patterns)* + +such that coverpoints found only in the set on the left will be retained and all others are dropped. + +Summarize tracefile content: + +:: + + lcov --summary *tracefile* + +Print version or help message and exit: + +:: + + lcov [ -h | --help ] + [ --version ] + +Common lcov options - supported by all the above use cases: + +:: + + lcov [ --keep-going ] + [ --filter *type* ] + [ -q | --quiet ] + [ -v | --verbose ] + [ --comment *comment_string* ] + [ --debug ] + [ --parallel | -j [*integer*] ] + [ --memory *integer_num_Mb* ] + [ --tempdir *dirname* ] + [ --branch-coverage ] + [ --mcdc-coverage ] + [ --config-file *config-file* ] + [ --rc *keyword*\ =\ *value* ] + [ --profile [ *profile-file* ] ] + [ --include *glob_pattern* ] + [ --exclude *glob_pattern* ] + [ --erase-functions *regexp_pattern* ] + [ --substitute *regexp_pattern* ] + [ --omit-lines *regexp_pattern* ] + [ --fail-under-branches *percentage* ] + [ --fail-under-lines *percentage* ] + +DESCRIPTION +----------- + +``lcov`` is a graphical front-end for GCC's coverage testing tool gcov. It collects +line, function and branch coverage data for multiple source files and creates +HTML pages containing the source code annotated with coverage information. +It also adds overview pages for easy navigation within the file structure. + +Use ``lcov`` to collect coverage data and ``genhtml`` to create HTML pages. Coverage data can either be collected from the +currently running Linux kernel or from a user space application. To do this, +you have to complete the following preparation steps: + +For Linux kernel coverage: + + Follow the setup instructions for the gcov-kernel infrastructure: + *https://docs.kernel.org/dev-tools/gcov.html* + +For user space application coverage: + + Compile the application with GCC using the options + "-fprofile-arcs" and "-ftest-coverage" or "--coverage". + +Please note that this man page refers to the output format of +``lcov`` as ".info file" or "tracefile" and that the output of GCOV +is called ".da file". + +Also note that when printing percentages, 0% and 100% are only printed when +the values are exactly 0% and 100% respectively. Other values which would +conventionally be rounded to 0% or 100% are instead printed as nearest +non-boundary value. This behavior is in accordance with that of the +:manpage:`gcov(1)` tool. + +By default, +``lcov`` and related tools generate and collect line and function coverage data. +Branch data is not collected or displayed by default; all tools support the +``--branch-coverage`` +and +``--mcdc-coverage`` +options to enable branch and MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate +settings to your personal, group, or site lcov configuration file. See man +:manpage:`lcovrc(5)` for details. + +OPTIONS +------- + +In general, (almost) all +``lcov`` +options can also be specified in a configuration file - see man +:manpage:`lcovrc(5)` for details. + +``-a`` *tracefile_pattern* +``--add-tracefile`` *tracefile_pattern* + + Add contents of all files matching glob pattern *tracefile_pattern*. + + Specify several tracefiles using the -a switch to combine the coverage data + contained in these files by adding up execution counts for matching test and + filename combinations. + + The result of the add operation will be written to stdout or the tracefile + specified with -o. + + Only one of -z, -c, -a, -e, -r, -l or --summary may be + specified at a time. + +``-b`` *directory* +``--base-directory`` *directory* + + Use *directory* as base directory for relative paths. + + Use this option to specify the base directory of a build-environment + when lcov produces error messages like: + + :: + + ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c + + In this example, use /home/user/project as base directory. + + This option is required when using lcov on projects built with libtool or + similar build environments that work with a base directory, *i.e.* environments, + where the current working directory 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 multiple base + directories are used. In that case use configuration file setting + ``geninfo_auto_base=1`` + (see man + :manpage:`lcovrc(5)`). + +``--build-directory`` *build_directory* + + search for .gcno data files from build_directory rather than + adjacent to the corresponding .gcda file. + + See man + :manpage:`geninfo(1)`) + for details. + +``--source-directory`` *dirname* + + Add 'dirname' to the list of places to look for source files. + + For relative source file paths listed in + *e.g.* + paths found in + *tracefile*, + or found in gcov output during + *--capture* + - possibly after substitutions have been applied - + ``lcov`` + will first look for the path from 'cwd' (where genhtml was + invoked) and + then from each alternate directory name in the order specified. + The first location matching location is used. + + This option can be specified multiple times, to add more directories to the source search path. + +``-c`` +``--capture`` + + Capture runtime coverage data. + + By default captures the current kernel execution counts and writes the + resulting coverage data to the standard output. Use the --directory + option to capture counts for a user space program. + + The result of the capture operation will be written to stdout or the tracefile + specified with -o. + + When combined with the + ``--all`` + flag, both runtime and compile-time coverage will be extracted in one step. + See the description of the + ``--initial`` + flag, below. + + See man + :manpage:`geninfo(1)`) + for more details about the capture process and available options and parameters. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``--branch-coverage`` + + Collect and/or retain branch coverage data. + + This is equivalent to using the option "--rc branch_coverage=1"; the option was added to better match the genhtml interface. + +``--mcdc-coverage`` + + Collect retain MC/DC data. + + This is equivalent to using the option "--rc mcdc_coverage=1". + MC/DC coverage is supported for GCC versions 14.2 and higher, or + LLVM 18.1 and higher. + + See + *llvm2lcov --help* + for details on MC/DC data capture in LLVM. + + See the MC/DC section of man + :manpage:`genhtml(1)` + for more details + +``--checksum`` +``--no-checksum`` + + Specify whether to generate checksum data when writing tracefiles and/or to + verify matching checksums when combining 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 generated for each + source code line and stored along with the coverage data. This checksum will + be used to prevent attempts to combine 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. + + Note that this options is somewhat subsumed by the + ``--version-script`` + option - which does something similar, but at the 'whole file' level. + +``--compat`` *mode*\ =\ *value*[,*mode*\ =\ *value*,...] + + Set compatibility mode. + + Use --compat to specify that lcov should enable one or more compatibility + modes when capturing coverage data. You can provide 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 versions. 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 lcov 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, lcov will assume that the source + code relating to a .da file located in a directory 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. + See man + :manpage:`lcovrc(5)` + for details of the file format and options. Also see the + *config_file* + entry in the same man page for details on how to include one config file into + another. + + When this option is specified, neither the system-wide configuration 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 + ``lcov`` + with different configuration file options in parallel. + + Note that this option must be specified in full - abbreviations are not supported. + +``--profile`` [*profile-data-file*] + + Tell the tool to keep track of performance and other configuration data. + If the optional + *profile-data-file* + is not specified, then the profile data is written to a file named with the same + basename as the + *--output-filename*, with suffix + *".json"* + appended. + Profile data is useful if you are trying to optimize the + ``lcov`` + implementation (see ``$LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py``), and can also enable faster + *--parallel* execution (see the + *"--history-script"* + section of this man page). + +``--history-script`` *callback* + + Use + *callback* + to predict current runtime cost using observed cost from prior execution. + + See man + :manpage:`genhtml(1)` + for more information. + +Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be +specified at a time. + +``-d`` *directory* +``--directory`` *directory* + + Use .da files in + *directory* + instead of kernel. + + If you want to work on coverage data for a user space program, use this + option to specify the location where the program was compiled (that's + where the counter files ending with .da will be stored). + + Note that you may specify this option more than once. + +``--exclude`` *pattern* + + Exclude source files matching + *pattern*. + + Use this switch if you want to exclude coverage data for a particular 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 accordingly to prevent the shell from expanding them first). + + Note: The pattern must be specified to match the + ``absolute`` + path of each source file. + If you specify a pattern which does not seem to be correctly applied - files that you expected to be excluded still appear in the output - you can look for warning messages in the log file. + ``lcov`` + will emit a warning for every pattern which is not applied at least once. + + Can be combined with the + ``--include`` + command line switch. If a given file matches both the include pattern and the + exclude pattern, the exclude pattern will take precedence. + +``--erase-functions`` *regexp* + + Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the --demangle-cpp option is used or not. + + Note that this option requires that you use a gcc version which is new enough to support function begin/end line reports or that you configure the tool to derive the required dta - see the + ``derive_function_end_line`` + discussion in man + :manpage:`lcovrc(5)`. + +``--substitute`` *regexp_pattern* + + Apply Perl regexp + *regexp_pattern* + to source file names found during processing. This is useful, for example, when the path name reported by gcov does not match your source layout and the file is not found, or in more complicated environments where the build directory structure does not match the source code layout or the layout in the projects's revision control system. + + Use this option in situations where geninfo cannot find the correct + path to source code files of a project. By providing a + *regexp_pattern* + in Perl regular expression format (see man + :manpage:`perlre(1)`), you can instruct geninfo to + remove or change parts of the incorrect source path. + Also see the + ``--resolve-script`` + option. + + One or more + *--substitution* + patterns and/or a + *--resolve-script* + may be specified. When multiple patterns are specified, they are applied in the order specified, substitution patterns first followed by the resolve callback. + The file search order is: + + 1. Look for file name (unmodified). + + If the file exits: return it. + + 2. Apply all substitution patterns in order - the result of the first pattern is used as the input of the second pattern, and so forth. + + If a file corresponding to the resulting name exists: return it. + + 3. Apply the 'resolve' callback to the final result of pattern substitutions. + + If a file corresponding to the resulting name exists: return it. + + 4. Otherwise: return original (unmodified) file name. + + Depending on context, the unresolved file name may or may not result in an error. + + Substitutions are used in multiple contexts by lcov/genhtml/geninfo: + + - during + *--capture*, + applied to source file names found in gcov-generated coverage data files (see man + :manpage:`gcov(1)`). + + - during + *--capture*, + applied to alternate + *--build-dir* + paths, when looking for the + *.gcno* + (compile time) data file corresponding to some + *.gcda* + (runtime) data file. + + - applied to file names found in lcov data files (".info" files) - + *e.g.*, + during lcov data aggregation or HTML and text report generation. + + For example, substituted names are used to find source files for + text-based filtering (see the + *--filter* + section, below) and are passed to + *--version-script, --annotate-script,* + and + *-criteria-script* + callbacks. + + - applied to file names found in the + *--diff-file* + passed to genhtml. + +**Example:** + +1. When geninfo reports that it cannot find source file + + :: + + /path/to/src/.libs/file.c + + while the file is actually located in + + :: + + /path/to/src/file.c + + use the following parameter: + + :: + + --substitute 's#/.libs##g' + + This will remove all "/.libs" strings from the path. + +2. When geninfo reports that it cannot find source file + + :: + + /tmp/build/file.c + + while the file is actually located in + + :: + + /usr/src/file.c + + use the following parameter: + + :: + + --substitute 's#/tmp/build#/usr/src#g' + + This will change all "/tmp/build" strings in the path to "/usr/src". + +``--omit-lines`` *regexp* + + Exclude coverage data from lines whose content matches + *regexp*. + + Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (*e.g.*, some complicated macro). Multiple patterns can be + specified by using multiple + ``--omit-lines`` command line switches. The + *regexp* + will be interpreted as perl regular expressions (note that they may need to be + escaped accordingly to prevent the shell from expanding them first). + If you want the pattern to explicitly match from the start or end of the line, your regexp should start and/or end with "^" and/or "$". + + Note that the + ``lcovrc`` + config file setting + ``lcov_excl_line = regexp`` + is similar to + ``--omit-lines.``. + ``--omit-lines`` + is useful if there are multiple teams each of which want to exclude certain patterns. + ``--omit-lines`` + is additive and can be specified across multiple config files whereas each call to + ``lcov_excl_line`` + overrides the previous value - and thus teams must coordinate. + +``--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 + coverpoints in external source files while capturing coverage data or + *--no-external* + to exclude them. + If your + *--directory* + or + *--base-directory* + path contains a soft link, then actual target directory is not considered to be + "internal" unless the + *--follow* + option is used. + + The + *--no-external* + option is somewhat of a blunt instrument; the + *--exclude* + and + *--include* + options provide finer grained control over which coverage data is and is not + included if your project structure is complex and/or + *--no-external* + does not do what you want. + + Data for external source files is + ``included`` + by default. + +``--forget-test-names`` + + If non-zero, ignore testcase names in .info file - + *i.e.*, + treat all coverage data as if it came from the same testcase. + This may improve performance and reduce memory consumption if user does + not need per-testcase coverage summary in coverage reports. + + This option can also be configured permanently using the configuration file + option + *forget_testcase_names*. + +``--prune-tests`` + + Determine list of unique tracefiles. + + Use this option to determine a list of unique tracefiles from the list + specified by + ``--add-tracefile``. + A tracefile is considered to be unique if it is the only tracefile that: + + 1. contains data for a specific source file + + 2. contains data for a specific test case name + + 3. contains non-zero coverage data for a specific line, function or branch + + Note that the list of retained files may depend on the order they are processed. For example, if + *A* + and + *B* + contain identical coverage data, then the first one we see will be retained and the second will be pruned. + The file processing order is nondeterministic when the + ``--parallel`` + option is used - implying that the pruned result may differ from one execution to the next in this case. + + ``--prune-tests`` must be specified together with + ``--add-tracefile``. + When specified, + ``lcov`` + will emit the list of unique files rather than combined tracefile data. + +``--map-functions`` + + List tracefiles with non-zero coverage for each function. + + Use this option to determine the list of tracefiles that contain non-zero + coverage data for each function from the list of tracefiles specified by + ``--add-tracefile``. + + This option must be specified together with + ``--add-tracefile``. + When specified, + ``lcov`` + will emit the list of functions and associated tracefiles rather than combined tracefile data. + +``--context-script`` *script* + + Use + *script* + to collect additional tool execution context information - to aid in + infrastructure debugging and/or tracking. + + See the genhtml man page for more details on the context script. + +``--criteria-script`` *script* + + Use + *script* + to test for coverage acceptance criteria. + + See the genhtml man page for more details on the criteria script. + Note that lcov does not keep track of date and owner information (see the + *--annotate-script* + entry in the genhtml man page) - so this information is not passed to the lcov callback. + +``--resolve-script`` *script* + + Use + *script* + to find the file path for some source file which appears in + an input data file if the file is not found after applying + *--substitute* + patterns and searching the + *--source-directory* + list. This option is equivalent to the + ``resolve_script`` + config file option. See man + :manpage:`lcovrc(5)` + for details. + +``--version-script`` *script* + + Use + *script* + to get a source file's version ID from revision control when + extracting data and to compare version IDs for the purpose of error checking when merging .info files. + + See the genhtml man page for more details on the version script. + +``--unreachable-script`` *module* + + Use + *module* + to decide whether particular branch expressions and/or MC/DC conditions + should be removed from the coverage report. + This option is equivalent to the + ``unreachable_script`` + config file option. See man + :manpage:`lcovrc(5)` + for details. + + Note that + *"module"* + is required to be a Perl module. + + See the genhtml man page for more details. + +``--comment`` *comment_string* + + Append + *comment_string* + to list of comments emitted into output result file. + This option may be specified multiple times. + Comments are printed at the top of the file, in the order they were specified. + + Comments may be useful to document the conditions under which the trace file was + generated: host, date, environment, + *etc.* + + Note that this option has no effect for lcov overations which do not write an + output result file: + *--list* + *--summary*, + *--prune-tests*, + and + *--map-functions*. + + See the + ``geninfo`` + man page for a description of the comment format in the result file. + +``-e`` *tracefile pattern* +``--extract`` *tracefile pattern* + + Extract data from + *tracefile*. + + Use this switch if you want to extract coverage data for only a particular + set of files from a tracefile. Additional command line parameters will be + interpreted as shell wildcard patterns (note that they may need to be + escaped accordingly to prevent the shell from expanding them first). + Every file entry in + *tracefile* + which matches at least one of those patterns will be extracted. + + Note: The pattern must be specified to match the + ``absolute`` + path of each source file. + + The result of the extract operation will be written to stdout or the tracefile + specified with -o. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``-f`` +``--follow`` + + Follow links when searching for .da files. + +``--large-file`` *regexp* + + See the + *--large-file* + section of man + :manpage:`geninfo(1)` + for details. + +``--from-package`` *package* + + Use .da files in + *package* + instead of kernel or directory. + + Use this option if you have separate machines for build and test and + want to perform the .info file creation on the build machine. See + --to-package for more information. + +``--sort-input`` + + Specify whether to sort file names before capture and/or aggregation. + Sorting reduces certain types of processing order-dependent output differences. + See the + ``sort_input`` + section in + man + :manpage:`lcovrc(5)`. + +``--gcov-tool`` *tool* + + Specify the location of the gcov tool. + + See the geninfo man page for more details. + +``-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 patterns. Multiple patterns can be + specified by using multiple + ``--include`` command line switches. The + *patterns* + will be interpreted as shell wildcard patterns (note that they may need to be + escaped accordingly to prevent the shell from expanding them first). + + Note: The pattern must be specified to match the + ``absolute`` + path of each source file. + + If you specify a pattern which does not seem to be correctly applied - files that you expected to be included in the output do not appear - lcov will generate an error message of type 'unused'. See the --ignore-errors option for how to make lcov ignore the error or turn it into a warning. + +``--msg-log`` [*log_file_name*] + + Specify location to store error and warning messages (in addition to writing to STDERR). + If + *log_file_name* + is not specified, then default location is used. + +``--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 errors after which + lcov should continue processing instead of aborting. + Note that the tool will generate a warning (rather than a fatal error) unless you ignore the error two (or more) times: + + :: + + lcov ... --ignore-errors source,source ... + + *errors* + can be a comma-separated list of the following keywords: + + ``branch`` + + branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. + + ``callback`` + + Version script error. + + ``child`` + + child process returned non-zero exit code during + *--parallel* + execution. This typically indicates that the child encountered an error: see the log file immediately above this message. + In contrast: the + ``parallel`` + error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. + + ``corrupt`` + + corrupt/unreadable file found. + + ``count`` + + An excessive number of messages of some class have been reported - subsequent messages of that type will be suppressed. + The limit can be controlled by the 'max_message_count' variable. See man + :manpage:`lcovrc(5)`. + + ``deprecated`` + + You are using a deprecated option. + This option will be removed in an upcoming release - so you should change your + scripts now. + + ``empty`` + + the .info data file is empty (*e.g.*, because all the code was 'removed' or excluded. + + ``excessive`` + + your coverage data contains a suspiciously large 'hit' count which is unlikely + to be correct - possibly indicating a bug in your toolchain. + See the + *excessive_count_threshold* + section in man + :manpage:`lcovrc(5)` + for details. + + ``fork`` + + Unable to create child process during + *--parallel* + execution. + + If the message is ignored ( + *--ignore-errors fork* + ), then genhtml + will wait a brief period and then retry the failed execution. + + If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. + + ``format`` + + Unexpected syntax or value found in .info file - for example, negative number or + zero line number encountered. + + ``gcov`` + + the gcov tool returned with a non-zero return code. + + ``graph`` + + the graph file could not be found or is corrupted. + + ``inconsistent`` + + your coverage data is internally inconsistent: it makes two or more mutually + exclusive claims. For example, some expression is marked as both an exception branch and not an exception branch. (See man + :manpage:`genhtml(1)` + for more details. + + ``internal`` + + internal tool issue detected. Please report this bug along with a testcase. + + ``mismatch`` + + Inconsistent entries found in trace file: + + - branch expression (3rd field in the .info file 'BRDA' entry) of merge data does not match, or + + - function execution count (FNDA:...) but no function declaration (FN:...). + + ``missing`` + + File does not exist or is not readable. + + ``negative`` + + negative 'hit' count found. + + Note that negative counts may be caused by a known GCC bug - see + + https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 + + and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. + + ``package`` + + a required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. + + ``parallel`` + + various types of errors related to parallelism - + *i.e.*, + a child process died due to an error. The corresponding error message appears in the log file immediately before the + *parallel* + error. + + If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the --parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. + + ``parent`` + + the parent process exited while child was active during + *--parallel* + execution. This happens when the parent has encountered a fatal error - + *e.g.* + an error in some other child which was not ignored. This child cannot continue working without its parent - and so will exit. + + ``range`` + + Coverage data refers to a line number which is larger than the number of + lines in the source file. This can be caused by a version mismatch or + by an issue in the + *gcov* + data. + + ``source`` + + the source code file for a data set could not be found. + + ``unreachable`` + + a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. + If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the + *retain_unreachable_coverpoints_if_executed* + configuration parameter. + See man + :manpage:`lcovrc(5)` + and the + *"Exclusion markers"* + section of man + :manpage:`geninfo(1)` + for more information. + + ``unsupported`` + + the requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. + + ``unused`` + + the include/exclude/erase/omit/substitute pattern did not match any file pathnames. + + ``usage`` + + unsupported usage detected - *e.g.* an unsupported option combination. + + ``utility`` + + a tool called during processing returned an error code (*e.g.*, 'find' encountered an unreadable directory). + + ``version`` + + revision control IDs of the file which we are trying to merge are not the same - line numbering and other information may be incorrect. + + Also see man + :manpage:`lcovrc(5)` + for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. + +``--expect-message-count message_type:expr[,message_type:expr]`` + + Give + ``lcov`` + a constraint on the number of messages of one or more types which are expected to + be produced during execution. If the constraint is not true, then generate an + error of type + *"count"* + (see above). + + See man + :manpage:`genhtml(1)` + for more details about the flag, as well as the + *"expect_message_count"* + section in man + :manpage:`lcovrc(5)` + for a description of the equivalent configuration file option. + +``--keep-going`` + + Do not stop if error occurs: attempt to generate a result, however flawed. + + This command line option corresponds to the + *stop_on_error [0|1]* + lcovrc option. See man + :manpage:`lcovrc(5)` + for more details. + +``--preserve`` + + Preserve intermediate data files generated by various steps in the tool - *e.g.*, for debugging. By default, these files are deleted. + +``--filter`` *filters* + + Specify a list of coverpoint filters to apply to input data. + See the genhtml man page for details. + +``--demangle-cpp`` [*param*] + + Demangle C++ function names. See the genhtml man page for details. + +``-i`` +``--initial`` + + Capture initial zero coverage data - *i.e.*, from the compile-time '.gcno' data + files. + Also see the + ``--all`` + flag, which tells the tool to capture both compile-time ('.gcno') and runtime + ('.gcda') data at the same time. + + Run lcov with -c and 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. + 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 + correct even when not all source code files were loaded during the test. + + Recommended procedure when capturing data for a test case: + + 1. create baseline coverage data file + + :: + + # lcov -c -i -d appdir -o app_base.info + + 2. perform test + + :: + + # appdir/test + + 3. create test coverage data file + + :: + + # lcov -c -d appdir -o app_test.info + + 4. combine baseline and test coverage data + + :: + + # lcov -a app_base.info -a app_test.info -o app_total.info + + The above 4 steps are equivalent to + + :: + + # lcov --capture --all -o app_total.info -d appdir + + The combined compile- and runtime data will produce a different result than + capturing runtime data alone if your project contains some compilation units + which are not used in any of your testcase executables or shared libraries - + that is, there are some '.gcno' (compile time) data files that do not + have matching '.gcda' (runtime) data files. + In that case, the runtime-only report will not contain any coverpoints from + the unused files, whereas those coverpoints will appear (with all zero 'hit' + counts) in the combined report. + + The + ``--initial`` + flag is ignored except in + ``--capture`` + mode. The + ``--all`` + flag is ignored if the + ``--initial`` + flag is specified. + +``-k`` *subdirectory* +``--kernel-directory`` *subdirectory* + + Capture kernel coverage data only from + *subdirectory*. + + Use this option if you don't want to get coverage data for all of the + kernel, but only for specific subdirectories. This option may be specified + more than once. + + Note that you may need to specify the full path to the kernel subdirectory + depending on the version of the kernel gcov support. + +``-l`` *tracefile* +``--list`` *tracefile* + + List the contents of the + *tracefile*. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``--list-full-path`` +``--no-list-full-path`` + + Specify whether to show full paths during list operation. + + Use --list-full-path to show full paths during list operation + or --no-list-full-path to show shortened paths. Paths are + ``shortened`` + by default. + +``--no-markers`` + + Use this option if you want to get coverage data without regard to exclusion + markers in the source code file. See + ``geninfo (1)`` + for details on exclusion markers. + +``--no-recursion`` + + Use this option if you want to get coverage data for the specified directory + only without processing subdirectories. + +``-o`` *tracefile* +``--output-file`` *tracefile* + + Write data to + *tracefile* + instead of stdout. + + Specify "-" as a filename to use the standard output. + + By convention, lcov-generated coverage data files are called "tracefiles" and + should have the filename extension ".info". + +``-v`` +``--verbose`` + + Increment informational message verbosity. This is mainly used for script and/or flow debugging - *e.g.*, to figure out which data file are found, where. + Also see the --quiet flag. + + Messages are sent to stdout unless there is no output file (*i.e.*, if the coverage data is written to stdout rather than to a file) and to stderr otherwise. + +``-q`` +``--quiet`` + + Decrement informational message verbosity. + + Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. + +``--debug`` + + Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. + +``--parallel`` [*integer*] +``-j`` [*integer*] + + Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). + + Also see the + *memory, memory_percentage, max_fork_fails* + and + *fork_fail_timeout* + entries in man + :manpage:`lcovrc(5)`. + A previously generated execution profile may help to enable better utilization + and faster parallel execution. See the + *"--profile"* + and + *"--history"* + sections of this man page. + +``--memory`` *integer* + + Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. + + This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does now know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. + + The configuration file + *memory_percentage* + option provided another way to set the maximum memory consumption. + See man + :manpage:`lcovrc(5)` + for details. + +``--rc`` *keyword*\ =\ *value* + + Override a configuration directive. + + Use this option to specify a + *keyword*\ =\ *value* + statement which overrides the corresponding configuration statement in + the lcovrc configuration file. You can specify this option more than once + to override multiple configuration statements. + See man + :manpage:`lcovrc(5)` + for a list of available keywords and their meaning. + +``-r`` *tracefile pattern* +``--remove`` *tracefile pattern* + + Remove data from + *tracefile*. + + Use this switch if you want to remove coverage data for a particular + set of files from a tracefile. Additional command line parameters will be + interpreted as shell wildcard patterns (note that they may need to be + escaped accordingly to prevent the shell from expanding them first). + Every file entry in + *tracefile* + which matches at least one of those patterns will be removed. + + Note: The pattern must be specified to match the + ``absolute`` + path of each source file. + + The result of the remove operation will be written to stdout or the tracefile + specified with -o. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``--summary`` *tracefile* + + Show summary coverage information for the specified tracefile. + + Note that you may specify this option more than once. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``--fail-under-branches`` *percentage* + + Use this option to tell lcov to exit with a status of 1 if the total + branch coverage is less than + *percentage*. + +``--fail-under-lines`` *percentage* + + Use this option to tell lcov to exit with a status of 1 if the total + line coverage is less than + *percentage*. + +``-t`` *testname* +``--test-name`` *testname* + + Specify test name to be stored in the tracefile. + + This name identifies a coverage data set when more than one data set is merged + into a combined tracefile (see option -a). + + Valid test names can consist of letters, decimal digits and the underscore + character ("_"). + +``--to-package`` *package* + + Store .da files for later processing. + + Use this option if you have separate machines for build and test and + want to perform the .info file creation on the build machine. To do this, + follow these steps: + + On the test machine: + + - run the test + - run lcov -c [-d directory] --to-package *file* + - copy *file* to the build machine + + On the build machine: + + - run lcov -c --from-package *file* [-o and other options] + + This works for both kernel and user space coverage data. Note that you might + have to specify the path to the build directory using -b with + either --to-package or --from-package. Note also that the package data + must be converted to a .info file before recompiling the program or it will + become invalid. + +``--version`` + + Print version number, then exit. + +``-z`` +``--zerocounters`` + + Reset all execution counts to zero. + + By default tries to reset kernel execution counts. Use the --directory + option to reset all counters of a user space program. + + Only one of -z, -c, -a, -e, -r, -l, --diff or --summary may be + specified at a time. + +``--tempdir`` *dirname* + + Write temporary and intermediate data to indicated directory. Default is "/tmp". + +FILES +----- + +*/etc/lcovrc* + + The system-wide configuration file. + +*~/.lcovrc* + + The per-user configuration file. + +AUTHOR +------ + +Peter Oberparleiter + +Henry Cox + + Filtering, error management, parallel execution sections. + +SEE ALSO +-------- + +:manpage:`lcovrc(5)`, +:manpage:`genhtml(1)`, +:manpage:`geninfo(1)`, +:manpage:`gendesc(1)`, +:manpage:`gcov(1)` +:manpage:`llvm2lcov(1)` +:manpage:`py2lcov(1)` +:manpage:`perl2lcov(1)` + +*https://github.com/linux-test-project/lcov* diff --git a/docs/man/lcovrc.rst b/docs/man/lcovrc.rst new file mode 100644 index 00000000..b1404b4f --- /dev/null +++ b/docs/man/lcovrc.rst @@ -0,0 +1,1862 @@ +=========================================================================================== +lcovrc - configuration file for |ToolName| tools containing default options and settings. +=========================================================================================== + +:Manual section: 5 +:Manual group: |ToolName| Configuration + +NAME +---- + +lcovrc + Configuration file for |ToolName| tools containing default options and settings. + +DESCRIPTION +----------- + +The *lcovrc* file contains configuration information for the ``lcov`` code coverage tool (see ``lcov``\(1)). + +The system-wide configuration file is located at *$|TOOL_NAME|_HOME/etc/lcovrc*. This is typically either */etc/lcovrc* or */usr/local/etc/lcovrc* but may be wherever you have installed the lcov package. To change settings for a single user, place a customized copy of this file at location *\~/.lcovrc*. Where available, command-line options override configuration file settings. + +The *genhtml, lcov,* and *geninfo* commands also support the *\-\-config\-file* option, which can be used to specify one or more files which should be used instead of the system or user default rc files. Multiple options files may be useful if you have both project- and team-specific common options and want to ensure consistency across multiple users. If multiple \-\-config\-file options are applied in the order they appear. Note that the "\-\-config\-file" option name must be specified in full and cannot be abbreviated. An error will occur if the option is not recognized. + +Lines in a configuration file can either be: + +- empty lines or lines consisting only of white space characters. These lines are ignored. + +- comment lines which start with a hash sign ('#'). These are treated like empty lines and will be ignored. + +- statements in the form 'key = value'. + +- Values may be taken from environment variables via the syntax 'key = ... $ENV{ENV_VAR_NAME} ...'. + + The substring '$ENV{ENV_VAR_NAME}' is replaced by the value of the environment variable. + + One or more environment variables may be used to set the RC value. 'key' is ignored if any of the environment variables are not set in your user environment. + +A list of valid statements and their description can be found in section 'OPTIONS' below. + +``NOTE`` that there is no error checking of keys in the options file: spelling errors are simply seen as values which are not used by some particular tool. If you are unsure of whether your options file is read or its values applied, you can use the *\-\-verbose \-\-verbose* flag to enable printing of option value overrides. (The option appears twice to enable a higher level of verbosity.) + +Both 'list' and 'scalar' (non list) options are supported in the lcovrc file. + +For scalar (non list) options: + +- if specified on the command line and in the lcovrc file, the value specified on the command line wins. The value from the RC file is ignored. + +- Scalar options include: 'criteria\_script = ...', 'genhtml\_annotate\_script = ...', 'version\_script = ...', etc. + +For list options: + +- the RC file entry can be used multiple times; each use appends to the list. For example, the entry below will result in two 'omit' patterns which will both be checked: + + :: + + # note explicit start/end line markers in the regexp + omit_lines = ^\\s+//\\s*MY_EXCLUDE_MARKER\\s*$ + # Note that the regexp below matches anywhere on the line + omit_lines = NR_CM_DBG_PRINT + +- If entries are specified on the command line, then the RC file entries are ignored: command line wins. If entries are specified in more than one RC file (*i.e.*, multiple \-\-config\-file arguments are supplied), then RC files are applied in order of appearance, and list entries are appended in order. For most list-type options, order is not important. + +- list options include: + + :: + + filter = ... + exclude = ... + ignore = ... + substitute = ... + omit_lines = ... + erase_functions = ... + genhtml_annotate_script = ... + + *etc.* For a complete set of list options, see the documentation of each configuration option, below. + +**Example configuration:** + +Note that this example does not include all possible configuration options. In general: (almost) all command line options can be specified in the configuration file instead, whereas some configuration file options have no command line equivalent. + +See the OPTIONS section below for details. + +:: + + # + # Example |ToolName| configuration file + # + # include some other config file + # e.g, user-specific options. Note the environment variable expansion + # config_file = $ENV{HOME}/.user_lcovrc + # or project specific - hard-coded from environment variable + # config_file = /path/to/myproject/.lcovrc + # or in the current run directory + # config_file = $ENV{PWD}/.lcovrc + + # External style sheet file + #genhtml_css_file = gcov.css + + # Use 'dark' mode display (light foreground/dark background) + # rather than default + #genhtml_dark_mode = 1 + + # Alternate header text to use at top of each page + #genhtml_header = Coverage report for my project + + # Alternate footer text to use at the bottom of each page + #genhtml_footer = My footer text + + # Coverage rate limits + genhtml_hi_limit = 90 + genhtml_med_limit = 75 + + # Ignore some errors (comma-separated list) + #ignore_errors = empty,mismatch + + # Stop emitting message after this number have been printed + # 0 == no limit + max_message_count = 100 + + # If nonzero, do not stop when an 'ignorable error' occurs - try + # to generate a result, however flawed. This is equivalent to + # the '--keep-going' command line switch. + # Default is 1: stop when error occurs + #stop_on_error = 1 + + # If nonzero, treat warnings as error + # note that ignored messages will still appear as warnings + # Default is 0 + #treat_warning_as_error = 1 + + # If set to non-zero, only issue particular warning once per file + # Default is 1 + #warn_once_per_file = 1 + + # extension associated with lcov trace files - glob match pattern + # used as argument to 'find' - to find coverage files contained in + # a directory argument + #info_file_pattern = *.info + + # list of file extensions which should be treated as C/C++ code + # (comma-separated list) + #c_file_extensions = h,c,cpp,hpp + + # list of file extensions which should be treated as RTL code + # (*e.g.*, Verilog) (comma-separated list) + #rtl_file_extensions = v,vh,sv + + # list of file extensions which should be treated as Java code + #java_file_extensions = java + + # list of file extensions which should be treated as perl code + #perl_file_extensions = pl,pm + + # list of file extensions which should be treated as python code + #python_file_extensions = py + + # maximum number of lines to look at, when filtering bogus branch expressions + #filter_lookahead = 5 + + # if nonzero, bitwise operators '|', '&', '~' indicate conditional expressions + #filter_bitwise_conditional = 1 + + # if nonzero, '--filter blank' is applied to blank lines, regardless + # of their hit count + #filter_blank_aggressive = 1 + + # Width of line coverage field in source code view + genhtml_line_field_width = 12 + + # Width of branch coverage field in source code view + genhtml_branch_field_width = 16 + + # Width of MC/DC coverage field in source code view + genhtml_mcdc_field_width = 14 + + # width of 'owner' field in source code view - default is 20 + genhtml_owner_field_width = 20 + # width of 'age' field in source code view - default is 5 + genhtml_age_field_width = 5 + + # Width of overview image + genhtml_overview_width = 80 + + # Resolution of overview navigation + genhtml_nav_resolution = 4 + + # Offset for source code navigation + genhtml_nav_offset = 10 + + # Do not remove unused test descriptions if non-zero + genhtml_keep_descriptions = 0 + + # Do not remove prefix from directory names if non-zero + genhtml_no_prefix = 0 + + # Do not create source code view if non-zero + genhtml_no_source = 0 + + # Specify size of tabs + genhtml_num_spaces = 8 + + # Include color legend in HTML output if non-zero + genhtml_legend = 0 + + # Include HTML file at start of HTML output + #genhtml_html_prolog = prolog.html + + # Include HTML file at end of HTML output + #genhtml_html_epilog = epilog.html + + # Use custom HTML file extension + #genhtml_html_extension = html + + # Compress all generated html files with gzip. + #genhtml_html_gzip = 1 + + # Include sorted overview pages + genhtml_sort = 1 + + # Display coverage data in hierarchical directory structure + # (rather than flat/3 level) + #genhtml_hierarchical = 1 + + # Display coverage data using 'flat' view + #genhtml_flat_view = 1 + + # Specify the character set of all generated HTML pages + genhtml_charset=UTF-8 + + # Allow HTML markup in test case description text if non-zero + genhtml_desc_html=0 + + # Specify the precision for coverage rates + #genhtml_precision=1 + + # Show missed counts instead of hit counts + #genhtml_missed=1 + + # group function aliases in report - see '--merge' section in man(1) genhtml + #merge_function_aliases = 1 + + # If set, suppress list of aliases in function detail table + #suppress_function_aliases = 1 + + # If set, derive function end line from line coverpoint data - default ON + #derive_function_end_line = 1 + + # If set, derive function end lines for all file types. + # By default, we derive end lines for C/C++ files only + # + #derive_end_line_all_files = 0 + + # Maximum size of function (number lines) which will be checked by '--filter trivial' + #trivial_function_threshold = 5 + + # Set threshold for hit count which tool should deem likely to indicate + # a toolchain bug (corrupt coverage data) + # excessive_count_threshold = number + + # Demangle C++ symbols + # Call multiple times to specify command and command line arguments + # ('-Xlinker'-like behaviour) + #demangle_cpp = c++filt + + # Location of the gcov tool + #geninfo_gcov_tool = gcov + + # Adjust test names if non-zero + #geninfo_adjust_testname = 0 + + # Ignore testcase names in .info file + forget_testcase_names = 0 + + # Calculate and/or compute checksum for each line if non-zero + checksum = 0 + + # Enable libtool compatibility mode if non-zero + geninfo_compat_libtool = 0 + + # Specify whether to capture coverage data for external source + # files + #geninfo_external = 1 + + # Specify whether to capture coverage data from compile-time data files + # which have no corresponding runtime data. + #geninfo_capture_all = 1 + + # Use gcov's --all-blocks option if non-zero + #geninfo_gcov_all_blocks = 1 + + # Adjust 'executed' non-zero hit count of lines which contain no branches + # and have attribute '"unexecuted_blocks": true' + #geninfo_unexecuted_blocks = 0 + + # Specify compatibility modes (same as \-\-compat option + # of geninfo) + #geninfo_compat = libtool=on, hammer=auto, split_crc=auto + + # Specify if geninfo should try to automatically determine + # the base-directory when collecting coverage data. + geninfo_auto_base = 1 + + # Use gcov intermediate format? Valid values are 0, 1, auto + geninfo_intermediate = auto + + # Specify if exception branches should be excluded from branch coverage. + no_exception_branch = 0 + + # Directory containing gcov kernel files + lcov_gcov_dir = /proc/gcov + + # Location for temporary directories + lcov_tmp_dir = /tmp + + # Show full paths during list operation if non-zero + lcov_list_full_path = 0 + + # Specify the maximum width for list output. This value is + # ignored when lcov_list_full_path is non-zero. + lcov_list_width = 80 + + # Specify the maximum percentage of file names which may be + # truncated when choosing a directory prefix in list output. + # This value is ignored when lcov_list_full_path is non-zero. + lcov_list_truncate_max = 20 + + # Specify if function coverage data should be collected, processed, and + # displayed. + function_coverage = 1 + + # Specify if branch coverage data should be collected, processed, and + # displayed. + branch_coverage = 0 + + # Specify if Modified Condition / Decision Coverage data should be collected, + # processed, and displayed. + mcdc_coverage = 0 + + # Ask lcov/genhtml/geninfo to return non-zero exit code if branch coverage is + # below specified threshold percentage. + fail_under_branches = 75.0 + + # Ask lcov/genhtml/geninfo to return non-zero exit code if line coverage is + # below specified threshold percentage. + #fail_under_lines = 97.5 + + # Specify JSON module to use, or choose best available if + # set to auto + lcov_json_module = auto + + # Specify maximum number of parallel slaves + # default: 1 (no parallelism) + #parallel = 1 + + # Specify maximum memory to use during parallel processing, in Mb. + # Do not fork if estimated memory consumption exceeds this number. + # default: 0 (no limit) + #memory = 1024 + + # Specify the number of consecutive fork() failures to allow before + # giving up + # max_fork_fails = 5 + + # Seconds to wait after failing to fork() before retrying + # fork_fail_timeout = 10 + + # Throttling control: specify a percentage of system memory to use as + maximum during parallel processing. + # Do not fork if estimated memory consumption exceeds the maximum. + # this value is used only if the maximum memory is not set. + # default: not set + #memory_percentage = 75 + + # Character used to split list-type parameters + # - for example, the list of "--ignore_errors source,mismatch" + # default: , (comma) + #split_char = , + + # use case insensitive compare to find matching files, for include/exclude + # directives, etc + #case_insensitive = 0 + + # override line default line exclusion regexp + #lcov_excl_line = LCOV_EXCL_LINE + + # override branch exclusion regexp + #lcov_excl_br_line = LCOV_EXCL_BR_LINE + + # override exception branch exclusion regexp + #lcov_excl_exception_br_line = LCOV_EXCL_EXCEPTION_BR_LINE + + # override start of exclude region regexp + #lcov_excl_start = LCOV_EXCL_START + + # override end of exclude region regexp + #lcov_excl_stop = LCOV_EXCL_STOP + + # override unreachable line default line exclusion regexp + #lcov_unreachable_line = LCOV_UNREACHABLE_LINE + + # override start of unreachable region regexp + #lcov_unreachable_start = LCOV_UNREACHABLE_START + + # override end of unreachable region regexp + #lcov_unreachable_stop = LCOV_UNREACHABLE_STOP + + # override start of branch exclude region regexp + #lcov_excl_br_start = LCOV_EXCL_BR_START + + # override start of exclude region regexp + #lcov_excl_br_stop = LCOV_EXCL_BR_STOP + + # override start of exclude region regexp + #lcov_excl_exception_br_start = LCOV_EXCL_EXCEPTION_BR_START + + # override start of exclude region regexp + #lcov_excl_exception_br_stop = LCOV_EXCL_EXCEPTION_BR_STOP + + +OPTIONS +------- + +``config_file`` = *filename* +---------------------------- + +Include another config file. + +Inclusion is equivalent to inserting the text from *filename* at this point in the current file. As a result, settings from the included file are processed after earlier settings in the current file, but before later settings from the current file. As a result: + +**Scalar options** set earlier in the current file are overridden by settings from the included file, and scalar options from the included file are overridden by later setting in the current file. + +**Array options** from earlier in the current file appear before setting from the included file, and array options from later in the current file appear after. + +Config file inclusion is recursive: an included config file may include another file - and so on. Inclusion loops are not supported and will result in a *usage* error. + +The most common usecase for config file inclusion is so that a site-wide or project-wide options file can include a user-specific or module-specific options file - for example, as + +:: + + ... + config_file = $ENV{HOME}/.lcovrc_user + ... + + +``genhtml_css_file`` = *filename* +---------------------------------- + +Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by ``genhtml``. During output generation, a copy of this file will be placed in the output directory. + +This option corresponds to the \-\-css\-file command line option of ``genhtml``. + +By default, a standard CSS file is generated. + +``genhtml_header`` = *string* +----------------------------- + +Specify header text to use ta top of each HTML page. + +This option corresponds to the \-\-header\-title command line option of ``genhtml``. + +Default is "|ToolName| - (differential )? coverage report" + +``genhtml_footer`` = *string* +----------------------------- + +Specify footer text to use at bottom of each HTML page. + +This option corresponds to the \-\-footer command line option of ``genhtml``. + +Default is |ToolName| tool version string. + +``genhtml_dark_mode`` = *0 | 1* +------------------------------- + +If non-zero, display using light text on dark background rather than dark text on light background. + +This option corresponds to the \-\-dark\-mode command line option of ``genhtml``. + +By default, a 'light' palette is used. + +``genhtml_hi_limit`` = *hi_limit* +``genhtml_med_limit`` = *med_limit* +----------------------------------- + +Specify coverage rate limits for classifying file entries. Use this option to modify the coverage rates (in percent) for line, function and branch coverage at which a result is classified as high, medium or low coverage. This classification affects the color of the corresponding entries on the overview pages of the HTML output: + +:: + + High: hi_limit <= rate <= 100 default color: green + Medium: med_limit <= rate < hi_limit default color: yellow + Low: 0 <= rate < med_limit default color: red + +Defaults are 90 and 75 percent. + +There are also options to configure different thresholds for line, branch, and function coverages. See below. + +``genhtml_line_hi_limit`` = *line_hi_limit* +``genhtml_line_med_limit`` = *line_med_limit* +---------------------------------------------- + +Specify specific threshold for line coverage limits used to decide whether a particular line coverage percentage is classified as high, medium, or low coverage. If the line-specific values are not specified, then the default *genhtml\_med\_limit* or *genhtml\_hi\_limit* values are used. + +``genhtml_branch_hi_limit`` = *branch_hi_limit* +``genhtml_branch_med_limit`` = *branch_med_limit* +-------------------------------------------------- + +Specify specific threshold for branch coverage limits used to decide whether a particular branch coverage percentage is classified as high, medium, or low coverage. If the branch-specific values are not specified, then the default *genhtml\_med\_limit* or *genhtml\_hi\_limit* values are used. + +``genhtml_function_hi_limit`` = *function_hi_limit* +``genhtml_function_med_limit`` = *function_med_limit* +------------------------------------------------------ + +Specify specific threshold for function coverage limits used to decide whether a particular function coverage percentage is classified as high, medium, or low coverage. If the function-specific values are not specified, then the default *genhtml\_med\_limit* or *genhtml\_hi\_limit* value is used. + +``rtl_file_extensions`` = *str[,str]+* +-------------------------------------- + +Specify a comma-separated list of file extensions which should be assumed to be RTL code (*e.g.*, Verilog). + +If not specified, the default set is 'v,vh,sv,vhdl?'. There is no command line option equivalent. + +This option is used by genhtml and lcov. + +``info_file_pattern`` = *str* +----------------------------- + +Specify a glob-match pattern associated with lcov trace files (suitable as an argument to 'find'. If not specified, the default is '\*.info'. + +``c_file_extensions`` = *str[,str]+* +------------------------------------ + +Specify a comma-separated list of file extensions which should be assumed to be C/C++ code. + +If not specified, the default set is 'c,h,i,C,H,I,icc,cpp,cc,cxx,hh,hpp,hxx'. If you want all files to be treated as C/C++ code, you can use: *c\_file\_extensions = .\** + +This parameter must be set from the lcovrc file or via the *\-\-rc name=value* command line option; note that you may need to protect the value from shell expansion in the latter case. + +``java_file_extensions`` = *str[,str]+* +--------------------------------------- + +Specify a comma-separated list of file extensions which should be assumed to be Java code. + +If not specified, the default set is 'java'. If you want all files to be treated as Java code, you can use: *java\_file\_extensions = .\** + +This parameter must be set from the lcovrc file or via the *\-\-rc name=value* command line option; note that you may need to protect the value from shell expansion in the latter case. + +``perl_file_extensions`` = *str[,str]+* +--------------------------------------- + +Specify a comma-separated list of file extensions which should be assumed to be Perl code. + +If not specified, the default set is 'pl,pm'. If you want all files to be treated as Perl code, you can use: *perl\_file\_extensions = .\** + +This parameter must be set from the lcovrc file or via the *\-\-rc name=value* command line option; note that you may need to protect the value from shell expansion in the latter case. + +``python_file_extensions`` = *str[,str]+* +----------------------------------------- + +Specify a comma-separated list of file extensions which should be assumed to be Python code. + +If not specified, the default set is 'py'. If you want all files to be treated as Python code, you can use: *python\_file\_extensions = .\** + +This parameter must be set from the lcovrc file or via the *\-\-rc name=value* command line option; note that you may need to protect the value from shell expansion in the latter case. + +``filter_lookahead`` = *integer* +-------------------------------- + +Specify the maximum number of lines to look at when filtering bogus branch expressions. A larger number may catch more cases, but will increase execution time. + +If not specified, the default set is 10. There is no command line option equivalent. + +This option is used by genhtml and lcov. + +``filter_bitwise_conditional`` = *0|1* +--------------------------------------- + +If set to non-zero value, bogus branch filtering will assume that expressions containing bitwise operators '&', '|', '~' are conditional expressions - and will not filter them out. + +If not specified, the default set is 0 (do not treat them as conditional). There is no command line option equivalent. + +This option is used by genhtml and lcov. + +``filter_blank_aggressive`` = *0|1* +----------------------------------- + +If set to non-zero value, then blank source lines will be ignored whether or not their 'hit' count is zero. See the *\-\-filter blank* section in :manpage:`genhtml(1)`. + +If not specified, the default set is 0 (filter blank lines only if they are not hit). There is no command line option equivalent. + +``ignore_errors`` = *message_type(,message_type)\** +---------------------------------------------------- + +Specify a message type which should be ignored. + +This option can be used multiple times in the lcovrc file to ignore multiple message types. + +This option is equivalent to the \-\-ignore\-errors option to geninfo, genhtml, or lcov. Note that the lcovrc file message list is not applied (those messages NOT ignored) if the '\-\-ignore\-errors' command line option is specified. + +This option is used by genhtml, lcov, and geninfo. + +``ignore_unreachable_flag`` = *0 | 1* +------------------------------------- + +When parsing a trace file, ignore 'unreachable' flags on branch expressions and MC/DC conditions - effectively, treating them as reachable. + +Note that the *ignore\_unreachable\_flag* is used only when reading a trace file. It has no effect on unreachable flags set by your *unreachable\_script* callback. See the *unreachable\_script* section, below. + +This option is used by genhtml, lcov, and geninfo. + +``expect_message_count`` = *message_type:expr(,message_type:expr)\** +--------------------------------------------------------------------- + +Specify a constraint on the number of messages of one or more types which are expected to be produced during tool execution. If the constraint is not true, an error of type *count* will be generated. + +Multiple constraints can be specified using a comma-separated list or by using the option multiple times. + +Substitutions are performed on the expression before it is evaluated: + +For example: + +- ``expect_message_count = inconsistent : %C == 5`` + + says that you expect exactly 5 messages of this type + +- ``expect_message_count inconsistent : %C > 6 && %C <= 10`` + + says that you expect the number of messages to be in the range (6:10]. + +This option is useful if errors are caused by conditions that you cannot fix - for example, due to inconsistent coverage data generated by your toolchain. In those scenarios, you may decide: + +- to exclude the offending code, or + +- to exclude the entire offending file(s), or + +- to ignore the messages, either by converting them to warnings or suppressing them entirely. + +In the latter case, this option provides some additional safety by warning you when the count differs due to some change which occurred, giving you the opportunity to diagnose the change and/or to review message changes. + +This option is equivalent to the *\-\-expect\-message\-count* command line flag. + +``max_message_count`` = *integer* +--------------------------------- + +Set the maximum number of warnings of any particular type which should be emitted. This can be used to reduce the size of log files. + +No more warnings will be printed after this number is reached. 0 (zero) is interpreted as 'no limit'. + +This option is used by genhtml, lcov, and geninfo. + +``message_log`` = *filename* +---------------------------- + +Specify location to store error and warning messages (in addition to writing to STDERR). If not specified, then the default location is used. + +This attribute is equivalent to the *\-\-msg\-log* command line option. The command line option takes precedence if both are specified. + +``stop_on_error`` = *0|1* +-------------------------- + +If set to 0, tell the tools to ignore errors and keep going to try to generate a result - however flawed or incomplete that result might be. Note that some errors cannot be ignored and that ignoring some errors may lead to other errors. + +The tool will return a non-zero exit code if one or more errors are detected during execution when *stop\_on\_error* is disabled. That is, the tool will continue execution in the presence of errors but will return an exit status. + +This is equivalent to the *'\-\-keep\-going'* command line option. + +Default is 1: stop when error occurs. + +If the *'ignore\_error msgType'* option is also used, then those messages will be treated as warnings rather than errors (or will be entirely suppressed if the message type appears multiple times in the ignore_messages option). Warnings do not cause a non-zero exit status. + +This option is used by genhtml, lcov, and geninfo. + +``treat_warning_as_error`` = *0|1* +----------------------------------- + +If set to 1, tell the tools that messages which are normally treated as warnings (*e.g.,* certain usage messages) should be treated as errors. + +Note that ignored messages will still appear as warnings: see the *ignore\_errors* entry, above. + +This option is used by genhtml, lcov, and geninfo. + +``warn_once_per_file`` = *0|1* +-------------------------------- + +If set to 1, tell the tools to emit certain errors only once per file (rather than multiple times, if the issue occurs multiple times in the same file). + +Default is 1: do not report additional errors. + +This option is used by genhtml, lcov, and geninfo. + +``check_data_consistency`` = *0|1* +----------------------------------- + +If set to 1, tell the tools to execute certain data consistency checks - *e.g.,* that function with a non-zero hit count contains at least one line with a non-zero hit count - and vice versa. + +It may be useful to use this option to disable checking if you have inconsistent legacy data and have no way to correct or exclude it. + +Default is 1: execute consistency checks. + +``genhtml_line_field_width`` = *number_of_characters* +------------------------------------------------------ + +Specify the width (in characters) of the source code view column containing line coverage information. + +Default is 12. + +``genhtml_branch_field_width`` = *number_of_characters* +-------------------------------------------------------- + +Specify the width (in characters) of the source code view column containing branch coverage information. + +Default is 16. + +``genhtml_mcdc_field_width`` = *number_of_characters* +------------------------------------------------------ + +Specify the width (in characters) of the source code view column containing MC/DC coverage information. + +Default is 14. + +``genhtml_owner_field_width`` = *number_of_characters* +------------------------------------------------------- + +Specify the width (in characters) of the source code view column containing owner information (as reported by your annotation script. This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page. + +Default is 20. + +``genhtml_age_field_width`` = *number_of_characters* +------------------------------------------------------ + +Specify the width (in characters) of the source code view column containing age of the corresponding block (as reported by your annotation script). This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page. + +Default is 5. + +``genhtml_frames`` = *0 | 1* +---------------------------- + +Specify whether source detail view should contain a navigation image. See the *\-\-frame* entry in the ``genhtml`` man page. + +``genhtml_overview_width`` = *pixel_size* +------------------------------------------ + +Specify the width (in pixel) of the overview image created when generating HTML output using the \-\-frames option of ``genhtml``. + +Default is 80. + +``genhtml_nav_resolution`` = *lines* +------------------------------------ + +Specify the resolution of overview navigation when generating HTML output using the \-\-frames option of ``genhtml``. This number specifies the maximum difference in lines between the position a user selected from the overview and the position the source code window is scrolled to. + +Default is 4. + +``genhtml_nav_offset`` = *lines* +-------------------------------- + +Specify the overview navigation line offset as applied when generating HTML output using the \-\-frames option of ``genhtml``. + +Clicking a line in the overview image should show the source code view at a position a bit further up, so that the requested line is not the first line in the window. This number specifies that offset. + +Default is 10. + +``genhtml_keep_descriptions`` = *0 | 1* +--------------------------------------- + +If non-zero, keep unused test descriptions when generating HTML output using ``genhtml``. + +This option corresponds to the \-\-keep\-descriptions option of ``genhtml``. + +Default is 0. + +``genhtml_no_prefix`` = *0 | 1* +-------------------------------- + +If non-zero, do not try to find and remove a common prefix from directory names. + +This option corresponds to the \-\-no\-prefix option of ``genhtml``. + +Default is 0. + +``genhtml_no_source`` = *0 | 1* +-------------------------------- + +If non-zero, do not create a source code view when generating HTML output using ``genhtml``. + +This option corresponds to the \-\-no\-source option of ``genhtml``. + +Default is 0. + +``genhtml_num_spaces`` = *num* +------------------------------- + +Specify the number of spaces to use as replacement for tab characters in the HTML source code view as generated by ``genhtml``. + +This option corresponds to the \-\-num\-spaces option of ``genhtml``. + +Default is 8. + +``genhtml_legend`` = *0 | 1* +----------------------------- + +If non-zero, include a legend explaining the meaning of color coding in the HTML output as generated by ``genhtml``. + +This option corresponds to the \-\-legend option of ``genhtml``. + +Default is 0. + +``genhtml_html_prolog`` = *filename* +------------------------------------ + +If set, include the contents of the specified file at the beginning of HTML output. + +This option corresponds to the \-\-html\-prolog option of ``genhtml``. + +Default is to use no extra prolog. + +``genhtml_html_epilog`` = *filename* +------------------------------------ + +If set, include the contents of the specified file at the end of HTML output. + +This option corresponds to the \-\-html\-epilog option of ``genhtml``. + +Default is to use no extra epilog. + +``genhtml_html_extension`` = *extension* +---------------------------------------- + +If set, use the specified string as filename extension for generated HTML files. + +This option corresponds to the \-\-html\-extension option of ``genhtml``. + +Default extension is "html". + +``genhtml_html_gzip`` = *0 | 1* +-------------------------------- + +If set, compress all html files using gzip. + +This option corresponds to the \-\-html\-gzip option of ``genhtml``. + +Default extension is 0. + +``genhtml_sort`` = *0 | 1* +--------------------------- + +If non-zero, create overview pages sorted by coverage rates when generating HTML output using ``genhtml``. + +This option can be set to 0 by using the \-\-no\-sort option of ``genhtml``. + +Default is 1. + +``genhtml_hierarchical`` = *0 | 1* +----------------------------------- + +If non-zero, the HTML report will follow the hierarchical directory structure of the source code. + +This option is equivalent to using the \-\-hierarchical command line option of ``genhtml``. 'Hierarchical' and 'flat' views are mutually exclusive. + +Default is 0. + +``genhtml_flat_view`` = *0 | 1* +-------------------------------- + +If non-zero, the top-level HTML table will contain all of the files in the project and there will be no intermediate directory pages. + +This option is equivalent to using the \-\-flat command line option of ``genhtml``. 'Hierarchical' and 'flat' views are mutually exclusive. + +Default is 0. + +``genhtml_show_navigation`` = *0 | 1* +-------------------------------------- + +If non-zero, the 'source code' view summary table will contain hyperlinks from the number to the first source line in the corresponding category ('Hit' or 'Not hit') in the non-differential coverage report. Source code hyperlinks are always enabled in differential coverage reports. + +This option is equivalent to using the \-\-show\-navigation command line option of ``genhtml``. + +Default is 0. + +``genhtml_show_owner_table`` = *0 | 1 | all* +--------------------------------------------- + +If non-zero, equivalent to the genhtml *\-\-shwow\-owners* flag: see :manpage:`genhtml(1)` for details. + +Default is 0. + +``compact_summary_tables`` = *0 | 1* +------------------------------------ + +If non-zero, suppress the 'Total' row in the 'date' and 'owner' summary table if there is only one element in the corresponding bin. + +When there are a large number of files with a single author, this can cut the summary table size by almost half. + +Default is 1 (enabled). + +``owner_table_entries`` = *integer* +----------------------------------- + +This option is used to tell genhtml the number of 'owner' table entries to retain in the summary table (at the top of the page) if owner table truncation is requested. Authors are sorted by quantity of un-exercised code - so elided entries will be smaller offenders: maximal offenders are retained. If the option is not set, then owner tables are not truncated. + +This option has no effect unless *genhtml \-\-show\-owners* is enabled. See the *\-\-show-owners* option in :manpage:`genhtml(1)` for details. + +Default is not set (*i.e.,* do not truncate owner tables). + +``truncate_owner_table`` = *comma_separated_list* +-------------------------------------------------- + +This option is used to tell genhtml whether to truncate the 'owner' table at the top, directory, or file level. This option acts together with the *owner\_table\_entries* parameter to determine how many author entries are retained. + +This option has no effect unless *genhtml \-\-show\-owners* is enabled and and the *owner\_table\_entries* configuration is set. + +If this option is set multiple times in the lcovrc file, the values are combined to form the list of levels where truncation will occur. Similarly, if this option is not set and *owner\_table\_entries* is set, then the table will be truncated everywhere. + +See the *\-\-show-owners* option in :manpage:`genhtml(1)` for details. + +Default is to not truncate the list. + +``genhtml_show_noncode_owners`` = *0 | 1* +----------------------------------------- + +If non-zero, equivalent to the genhtml *\-\-shwow\-noncode* flag: see :manpage:`genhtml(1)` for details. + +Default is 0. + +``genhtml_show_function_proportion`` = *0 | 1* +---------------------------------------------- + +If nonzero, add column to "function coverage detail" table to show the proportion of lines and branches within the function which are exercised. + +This option is equivalent to using the \-\-show\-proportion command line option of ``genhtml``. + +Default is 0. + +``genhtml_synthesize_missing`` = *0 | 1* +---------------------------------------- + +If non-zero, equivalent to the genhtml *\-\-synthesize\-missing* flag: see :manpage:`genhtml(1)` for details. + +Default is 0. + +``genhtml_charset`` = *charset* +-------------------------------- + +Specify the character set of all generated HTML pages. + +Use this option if the source code contains characters which are not part of the default character set. Note that this option is ignored when a custom HTML prolog is specified (see also ``genhtml_html_prolog``). + +Default is UTF-8. + +``demangle_cpp`` = *c++filt* +----------------------------- + +If set, this option tells genhtml/lcov/geninfo to demangle C++ function names in function overviews, and gives the name of the tool used for demangling. Set this option to one if you want to convert C++ internal function names to human readable format for display on the HTML function overview page. + +If the *demangle\_cpp* option is used multiple times, then the arguments are concatenated when the callback is executed - similar to how the gcc *\-Xlinker* parameter works. This provides a possibly easier way to pass arguments to your tool, without requiring a wrapper script. In that case, your callback will be executed as: *| tool\-0 'tool\-1; ...* Arguments are quoted when passed to the shell, in order to handle parameters which contain spaces. + +Note that the demangling tool is called via a pipe, and is expected to read from stdin and write to stdout. + +This option corresponds to the \-\-demangle\-cpp command line option of ``genhtml``. + +Default is not set (C++ demangling is disabled). + +``genhtml_desc_html`` = *0 | 1* +-------------------------------- + +If non-zero, test case descriptions may contain HTML markup. + +Set this option to one if you want to embed HTML markup (for example to include links) in test case descriptions. When set to zero, HTML markup characters will be escaped to show up as plain text on the test case description page. + +Default is 0. + +``genhtml_precision`` = *1 | 2 | 3 | 4* +----------------------------------------- + +Specify how many digits after the decimal-point should be used for displaying coverage rates. + +Default is 1. + +``merge_function_aliases`` = *0 | 1* +------------------------------------- + +If non-zero, group function aliases in the function detail tabile. See man(1) genhtml. + +Default is 0. + +``genhtml_missed`` = *0 | 1* +------------------------------ + +If non-zero, the count of missed lines, functions, or branches is shown as negative numbers in overview pages. + +Default is 0. + +``suppress_function_aliases`` = *0 | 1* +--------------------------------------- + +If non-zero, do not show aliases in the function detail table. + +If nonzero, implies that ``merge_function_aliases`` is enabled. See the genhtml man page for more details. + +Default is 0. + +``derive_function_end_line`` = *0 | 1* +---------------------------------------- + +If non-zero, use 'line' coverage data to deduce the end line of each function definition. This is useful when excluding certain functions from your coverage report. See the *\-\-erase\-functions,* *\-\-filter trivial* and *\ \-\-show\-proportion* options. + +Default is 1. + +This option is not required if you are using gcc/9 or newer; these versions report function begin/end lines directly. + +Note that end lines are derived only for C/C++ files unless the *derive\_function\_end\_lines\_all\_files* option is enabled; see the *c\_file\_extensions* setting, above, for the list of extensions used to identify C/C++ these files. + +Lambda functions are ignored during end line computation. Note that lambdas are identified via function name matching - so you must enable demangling if your toolchain is too old to report demangled names in the GCOV output. See the *demangle\_cpp* setting, above. + +For languages other than C/C++: end-line derivation may compute the wrong value - *e.g.,* in cases where there are lines of code in global scope following some function definition. In this case, lcov will incorrectly associate the following code with the preceding function. + +If this creates problems - for example, causes lcov to warn about inconsistent coverage data - then there are several possible workarounds: + +- disable end-line derivation - *e.g.,* via *\-\-rc derive_function_end_line=0*. + +- exclude the offending code and/or then entire associated file. + +- ignore the error message, *e.g.,* via the *\-\-ignore\-errors* command line option + +- disable coverage DB consistency checks - *e.g.,* via *\-\-rc check_data_consistency=0*. + +``derive_function_end_line_all_files`` = *0 | 1* +------------------------------------------------- + +If non-zero, derive end lines for all functions, regardless of source language. By default, end lines are computed only in C/C++ files. + +This option has no effect if *derive\_function\_end\_lines* is disabled. + +Default is 0 (disabled). + +``trivial_function_threshold`` = *integer* +------------------------------------------- + +Set the maximum size of function (in number of lines) which will be checked by *\-\-filter trivial filter.* + +Default is 5. + +``excessive_count_threshold`` = *number* +---------------------------------------- + +Set the threshold for hit count that lcov deems excessive/unlikely/indicating a bug somewhere in your toolchain. + +For example, it is unlikely that your job can run long enough to rack up tens of billions of hits. + +Message type ``excessive`` is used to report potential issue - see the ``genhtml(1), lcov(1), geninfo(1)`` man pages. + +Default is not set. (Do not check for excessive counts.) + +``geninfo_gcov_tool`` = *path_to_gcov* +--------------------------------------- + +Specify the location of the gcov tool (see ``gcov``\(1)) which is used to generate coverage information from data files. + +This option can be used multiple times - *e.g.*, to add arguments to the gcov callback. See the geninfo man page for details. + +``geninfo_adjust_testname`` = *0 | 1* +------------------------------------- + +If non-zero, adjust test names to include operating system information when capturing coverage data. + +Default is 0. + +``forget_testcase_names`` = *0 | 1* +----------------------------------- + +If non-zero, ignore testcase names in .info file. This may improve performance and reduce memory consumption if user does not need per-testcase coverage summary in coverage reports. + +This is equivalent to the "\-\-forget\-test\-names" lcov/genhtml option. + +Default is 0. + +``checksum`` = *0 | 1* +----------------------- + +If non-zero, generate source code checksums when capturing coverage data. Checksums are useful to prevent merging coverage data from incompatible source code versions but checksum generation increases the size of coverage files and the time used to generate those files. + +This option can be overridden by the \-\-checksum and \-\-no\-checksum command line options. + +Default is 0. + +Note that this options is somewhat subsumed by the *version\_script* option - which does something similar, but at the 'whole file' level. + +``geninfo_compat_libtool`` = *0 | 1* +------------------------------------- + +If non-zero, enable libtool compatibility mode. When libtool compatibility mode is enabled, lcov will assume that the source code relating to a .da file located in a directory named ".libs" can be found in its parent directory. + +This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool command line option of ``geninfo``. + +Default is 1. + +``geninfo_external`` = *0 | 1* +-------------------------------- + +If non-zero, capture coverage data for external source files. + +External source files are files which are not located in one of the directories (including sub-directories) specified by the \-\-directory or \-\-base\-directory options of ``lcov / geninfo``. Also see the *\-\-follow* option and the *geninfo\_follow\_symlinks* and *geninfo\_follow\_file\_links* for additional path controls. + +Default is 1. + +``geninfo_capture_all`` = *0 | 1* +--------------------------------- + +If non-zero, capture coverage data from both runtime data files as well as compile time data files which have no corresponding runtime data. See the *\-\-all* flag description in ``man(1) geninfo`` for more information. + +Default is 0: do not process bare compile-time data files. + +``geninfo_external`` = *0 | 1* +-------------------------------- + +If non-zero, capture coverage data for external source files. + +External source files are files which are not located in one of the directories (including sub-directories) specified by the \-\-directory or \-\-base\-directory options of ``lcov / geninfo``. Also see the *\-\-follow* option and the *geninfo\_follow\_file\_links* for additional path controls. + +Default is 1. + +``geninfo_follow_symlinks`` = *0 | 1* +-------------------------------------- + +Equivalent to the lcov/geninfo *\-\-follow* command line option. See :manpage:`geninfo(1)` for details. + +Default is 0: do not modify follow symbolic links. + +``geninfo_follow_file_links`` = *0 | 1* +---------------------------------------- + +If non-zero and the lcov/geninfo *\-\-follow* command line option is specified, then source file pathnames which contain symlinks are resolved to their actual target. Note that the parent directory of the link target may be considered 'external' and thus be removed by the *\-\-no\-external* flag. + +Default is 0: do not modify pathnames. + +``geninfo_gcov_all_blocks`` = *0 | 1* +-------------------------------------- + +If non-zero, call the gcov tool with option --all-blocks. + +Using --all-blocks will produce more detailed branch coverage information for each line. Set this option to zero if you do not need detailed branch coverage information to speed up the process of capturing code coverage or to work around a bug in some versions of gcov which will cause it to endlessly loop when analyzing some files. + +Default is 1. + +``geninfo_unexecuted_blocks`` = *0 | 1* +----------------------------------------- + +If non-zero, adjust the 'hit' count of lines which have attribute *"unexecuted\_block": true* but which contain no branches and have a non-zero count. Assume that these lines are not executed. + +Note that this option is effective only for gcov versions 9 and newer. + +Default is 0. + +``geninfo_compat`` = *mode=value[, mode=value,...]* +---------------------------------------------------- + +Specify that geninfo should enable one or more compatibility modes when capturing coverage data. + +This option corresponds to the \-\-compat command line option of ``geninfo``. + +Default is 'libtool=on, hammer=auto, split_crc=auto'. + +``geninfo_adjust_src_path`` = *pattern* ``=>`` *replacement* +``geninfo_adjust_src_path`` = *pattern* +---------------------------------------- + +Adjust source paths when capturing coverage data. + +Use this option in situations where geninfo cannot find the correct path to source code files of a project. By providing a *pattern* in Perl regular expression format (see ``perlre``\(1)) and an optional replacement string, you can instruct geninfo to remove or change parts of the incorrect source path. + +**Example:** + +1. When geninfo reports that it cannot find source file + + :: + + /path/to/src/.libs/file.c + + while the file is actually located in + + :: + + /path/to/src/file.c + + use the following parameter: + + :: + + geninfo_adjust_src_path = /.libs + + This will remove all "/.libs" strings from the path. + +2. When geninfo reports that it cannot find source file + + :: + + /tmp/build/file.c + + while the file is actually located in + + :: + + /usr/src/file.c + + use the following parameter: + + :: + + geninfo_adjust_src_path = /tmp/build => /usr/src + + This will change all "/tmp/build" strings in the path to "/usr/src". + +The *adjust\_src\_path* option is similar to the *substitution = ...* option - which is somewhat more general and allows you to specify multiple substitution patterns. Also see the *resolve\_script* option. + +``source_directory`` = *dirname* +-------------------------------- + +Add 'dirname' to the list of places to look for source files. Also see the *\-\-source\-directory* entry in the ``lcov, geninfo,`` and ``genhtml`` man pages. + +For relative source file paths *e.g.,* found in some *tracefile* or in gcov output, first look for the path from 'cwd' (where genhtml was invoked) and then from each alternate directory name in the order specified. The first location matching location is used. + +This option can be specified multiple times, to add more directories to the source search path. + +Note that the command line option overrides the RC file entries (if any). + +``build_directory`` = *dirname* +-------------------------------- + +Add 'dirname' to the list of places to look for matching GCNO files (geninfo) or source file soft links (genhtml). See the *\-\-build\-directory* description in the ``geninfo`` and in the ``genhtml`` man page. + +This option can be specified multiple times, to add more directories to the source search path. + +Note that the command line option overrides the RC file entries (if any). + +``geninfo_auto_base`` = *0 | 1* +-------------------------------- + +If non-zero, apply a heuristic to determine the base directory when collecting coverage data. + +Use this option when using geninfo on projects built with libtool or similar build environments that work with multiple base directories, *i.e.* environments, where the current working directory when invoking the compiler is not the same directory in which the source code file is located, and in addition, is different between files of the same project. + +Default is 1. + +``geninfo_intermediate`` = *0 | 1 | auto* +------------------------------------------ + +Specify whether to use gcov intermediate format + +Use this option to control whether geninfo should use the gcov intermediate format while collecting coverage data. The use of the gcov intermediate format should increase processing speed. It also provides branch coverage data when using the \-\-initial command line option. + +Valid values are 0 for off, 1 for on, and "auto" to let geninfo automatically use immediate format when supported by gcov. + +Default is "auto". + +``no_exception_branch`` = *0 | 1* +--------------------------------- + +Specify whether to exclude exception branches from branch coverage. Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data. + +This option is used by lcov, geninfo, genhtml. + +The value *no\_exception\_branch = 1* is equivalent to the *\-\-filter exception* command line option. + +Default is 0. + +``geninfo_chunk_size`` = *integer [%]* +-------------------------------------- + +Specify the number of GCDA files which should be processed per-call in each child process. This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism. + +The default is 80% of *total\_number\_of\_gcda\_files / maximum\_number\_of\_parallel\_children,* the average number of files expected to be processed by each child. See the *\-\-parallel* entry in the ``geninfo`` man page. + +The argument may be either an integer value to be used as the chunk size or a percentage of the average number files processed per child. + +This option has no effect unless the *\-\-parallel* option has been specified. + +``geninfo_interval_update`` = *integer* +--------------------------------------- + +Seet the percentage of GCDA files which should be processed between console/progress updates. This setting may be useful for parameter tuning and debugging apparent performance issues. + +The default is 5%. + +This option has no effect unless the *\-\-parallel* option has been specified. + +``lcov_filter_chunk_size`` = *integer [%]* +------------------------------------------- + +Specify the number of source files which should be processed per-call in each child process when applying coverpoint filters - see the ``filter = ...`` parameter, below. This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism. + +The default is 80% of *total\_number\_of\_source\_files / maximum\_number\_of\_parallel\_children.* + +The argument may be either an integer value to be used as the chunk size or a percentage of the average number files processed per child. + +This option has no effect unless the *\-\-parallel* option has been specified and ``lcov_filter_parallel`` is not zero. + +``lcov_filter_parallel`` = *0 | 1* +---------------------------------- + +This option specifies whether coverpoint filtering should be done serially or in parallel. If the number of files to process is very large, then parallelization may improve performance. + +This option has no effect unless the *\-\-parallel* option has been specified. + +The default is 1 (enabled). + +``lcov_gcov_dir`` = *path_to_kernel_coverage_data* +--------------------------------------------------- + +Specify the path to the directory where kernel coverage data can be found or leave undefined for auto-detection. + +Default is auto-detection. + +``lcov_tmp_dir`` = *temp* +-------------------------- + +Specify the location of a directory used for temporary files. + +Default is '/tmp'. + +``lcov_list_full_path`` = *0 | 1* +--------------------------------- + +If non-zero, print the full path to source code files during a list operation. + +This option corresponds to the \-\-list\-full\-path option of ``lcov``. + +Default is 0. + +``lcov_list_max_width`` = *width* +--------------------------------- + +Specify the maximum width for list output. This value is ignored when lcov_list_full_path is non-zero. + +Default is 80. + +``lcov_list_truncate_max`` = *percentage* +----------------------------------------- + +Specify the maximum percentage of file names which may be truncated when choosing a directory prefix in list output. This value is ignored when lcov_list_full_path is non-zero. + +Default is 20. + +``function_coverage`` = *0 | 1* +-------------------------------- + +Specify whether lcov/geninfo/genhtml should generate, process, and display function coverage data. + +Turning off function coverage by setting this option to 0 can sligly reduce memory and CPU time consumption when lcov is collecting and processing coverage data, as well as reduce the size of the resulting data files. + +This option can be overridden by the *\-\-function\-coverage* and *\-\-no\-function\-coverage* command line options. + +Default is 1. + +``branch_coverage`` = *0 | 1* +----------------------------- + +Specify whether lcov/geninfo should generate, process, and display branch coverage data. + +Turning off branch coverage by setting this option to 0 can reduce memory and CPU time consumption when lcov is collecting and processing coverage data, as well as reduce the size of the resulting data files. + +This option can be overridden by the *\-\-branch\-coverage* and *\-\-no\-branch\-coverage* command line options. + +Default is 0. + +``mcdc_coverage`` = *0 | 1* +---------------------------- + +Specify whether lcov/geninfo should generate, process, and display Modified Condition / Decision Coverage (MC/DC) coverage data. + +Turning off MC/DC coverage by setting this option to 0 can reduce memory and CPU time consumption when lcov is collecting and processing coverage data, as well as reduce the size of the resulting data files. + +This option can be overridden by the *\-\-mcdc\-coverage* command line option. + +Default is 0 (not enabled). + +See the MC/DC section of :manpage:`genhtml(1)` for more details + +``lcov_excl_line`` = *expression* +--------------------------------- + +Specify the regular expression of lines to exclude. Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped. + +There are at least 2 (moderately) common use cases for custom exclusion markers: + +- You are using multiple tools for coverage analysis, each of which has its own directives, and you don't want to complicate your source code with directives for each of them. + +- You want to exclude different regions/different types of code in different contexts - for example, to ignore or not ignore debug/trace code depending on your team. + +Default is 'LCOV_EXCL_LINE'. + +``lcov_excl_br_line`` = *expression* +------------------------------------ + +Specify the regular expression of lines to exclude from branch coverage. Branch coverpoints are associated with lines where this regexp is found are dropped. (Line and function coverpoints are not affected.) + +Default is 'LCOV_EXCL_BR_LINE'. + +``lcov_excl_exception_br_line`` = *expression* +------------------------------------------------ + +Specify the regular expression of lines to exclude from exception branch coverage. Exception-related Branch coverpoints associated with lines where this regexp is found are dropped. (Line, function coverpoints are not affected. Branch coverpoints which are not associated with exceptions are also not affected.) + +Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed. + +Note that this feature requires support from your compiler - and thus may not ignore all exception-related coverpoints. + +Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'. + +``lcov_excl_start`` = *expression* +---------------------------------- + +Specify the regexp mark the start of an exception region All coverpoints within exception regions are dropped. + +Default is 'LCOV_EXCL_START'. + +``lcov_excl_stop`` = *expression* +--------------------------------- + +Specify the regexp mark the end of an exception region + +Default is 'LCOV_EXCL_STOP'. + +``lcov_excl_br_start`` = *expression* +------------------------------------- + +Specify the regexp used to mark the start of a region where branch coverpoints are excluded. Line and function coverpoints within the region are not excluded. + +Default is 'LCOV_EXCL_BR_START'. + +``lcov_excl_br_stop`` = *expression* +------------------------------------ + +Specify the regexp used to mark the end of a region where branch coverpoints are excluded. + +Default is 'LCOV_EXCL_BR_STOP'. + +``lcov_excl_exception_br_start`` = *expression* +------------------------------------------------- + +Specify the regexp used to mark the start of a region where branch coverpoints associated with exceptions are excluded. Line, function, and non-exception branch coverpoints within the region are not excluded. + +Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed. + +Note that exception branch coverpoint identification requires support from your compiler - and thus may not ignore all exception-related coverpoints. + +Default is 'LCOV_EXCL_EXCEPTION_BR_START'. + +``lcov_excl_exception_br_stop`` = *expression* +------------------------------------------------ + +Specify the regexp used to mark the end of a region where exception-related branch coverpoints are excluded. + +Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'. + +``lcov_unreachable_line`` = *expression* +----------------------------------------- + +Specify the regular expression of unreachable line which should be excluded from reporting, but should generate an "inconsistent" error if hit. That is: we believe that the marked code is unreachable, so there is a bug in the code, the placement of the directive, or both if the "unreachable" code is executed. Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped. + +Default is 'LCOV_UNREACHABLE_LINE'. + +``lcov_unreachable_start`` = *expression* +------------------------------------------- + +Specify the regexp mark the start of an unreachable code block. All coverpoints within exception regions are dropped, but the tool will generate an "inconsistent" error if any code in the block is executed. + +Default is 'LCOV_UNREACHABLE_START'. + +``lcov_unreachable_stop`` = *expression* +----------------------------------------- + +Specify the regexp mark the end of the unreachable code block. + +Default is 'LCOV_UNREACHABLE_STOP'. + +``fail_under_branches`` = *percentage* +--------------------------------------- + +Specify branch coverage threshold: if the branch coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code. + +This option is equivalent to the \-\-fail\-under\-branches lcov/genhtml/geninfo command line argument. See :manpage:`lcov(1)` for more detailes. + +The default is 0 (no threshold). + +``retain_unreachable_coverpoints_if_executed`` = *[0 | 1]* +----------------------------------------------------------- + +Specify whether coverpoints in "unreachable" regions which are 'hit' are dropped (0) - because the region is excluded - or retained (1) - because the directive appears to be incorrect. See the "Exclusion markers" section in :manpage:`geninfo(1)` for more details. + +The default is 1 (retain the coverpoints). + +``fail_under_lines`` = *percentage* +----------------------------------- + +Specify line coverage threshold to lcov. If the line coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code. + +This option is equivalent to the \-\-fail\-under\-lines lcov/genhtml/geninfo command line argument. + +The default is 0 (no threshold). + +``profile`` = *filename* +------------------------- + +If set, tells genhtml, lcov, or geninfo to generate some execution time/profile data which can be used to motivate future optimizations. It is equivalent to the *\-\-profile* command line option. + +If *filename* is empty, then the profile is written to the default location chosen by the application. + +This option is used by genhtml, lcov, and geninfo. + +The default is unset: no data generated. + +``parallel`` = *integer* +------------------------- + +Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes to use. Zero means to use as many cores as are available on the machine. The default is 1 (one) - which means to process sequentially (no parallelism). + +This option is used by genhtml, lcov, and geninfo. + +``memory`` = *integer\_Mb* +--------------------------- + +Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing operations. Effectively, the process will not fork() if this limit would be exceeded. Zero means that there is no limit. The default is 0 (zero) - which that there is no explicit limit. + +This option is used by genhtml, lcov, and geninfo. + +``memory_percentage`` = *number* +-------------------------------- + +Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing operations. Maximum is computed as a percentage of the total memory available on the system; for example, '75' would use limit to 75% of total memory, whereas 150.5 would limit to 150.5% (*i.e.,* larger than the total available. Effectively, the process will not fork() if this limit would be exceeded. Note that this value is used only if the maximum memory value is not set explicitly - either by a the *\-\-memory* command line option or the *memory = integer* configuration file setting. + +The default is not not set. + +This option is used by genhtml, lcov, and geninfo. + +``max_fork_fails`` = *integer* +-------------------------------- + +Tells genhtml, lcov, or geninfo the number of consecutive fork() failures to ignore during *\-\-parallel* execution before giving up. Note that genhtml/lcov/geninfo fail and stop immediately unless the *fork* error message ignored - either via the *ignore\_errors* directive (above), the *\-\-ignore\-errors* command line option, or if *stop\_on\_error* is disabled or the *\-\-keep-going* command line option is used. + +The default fork failure maximum is 5. + +``fork_fail_timeout`` = *integer\_seconds* +------------------------------------------- + +Tells genhtml, lcov, or geninfo how long to wait after a fork() failure before retrying. + +The default is 10 (seconds). + +``max_tasks_per_core`` = *integer* +----------------------------------- + +This is the maximum number of files that genhtml will handle in a single child process during parallel execution. + +The default is 20. + +``genhtml_date_bins`` = *integer[,integer..]* +---------------------------------------------- + +This option is equivalent to the "genhtml \-\-date\-bins" option. See :manpage:`genhtml(1)` for details. + +This option can be used multiple times in the lcovrc file to set multiple cutpoints. + +``genhtml_datelabels`` = *string[,string..]* +-------------------------------------------- + +This option is equivalent to the "genhtml \-\-date\-labels" option. See :manpage:`genhtml(1)` for details. + +This option can be used multiple times in the lcovrc file to set multiple labels. The number of labels should equal one greater than number of cutpoints. + +``genhtml_annotate_script`` = *path_to_executable | parameter* +--------------------------------------------------------------- + +This option is equivalent to the "genhtml \-\-annotate\-script" option. + +This option can be used multiple times in the lcovrc file to specify both an annotation script and additional options which are passed to the script. + +See the genhtml man page for details. + +``genhtml_annotate_tooltip`` = *tooltip\_string* +------------------------------------------------- + +This option sets the 'tooltip' popup which appears if user hovers mouse over the associated source code. Note that the tooltop is generated only if the annotation-script callback is successful and returns a commit ID other than "NONE". Set *tooltip\_string* to "" (empty string) to force genhtml to not produce the tooltip. + +Substitutions are performed on *tooltip\_string:* + +- ``%C:`` commit ID (from annotate callback - see *\--anotate-script* entry in the ``genhtml`` man page) + +- ``%U:`` commit author abbreviated name (returned by annotate callback) + +- ``%F:`` commit author full name (returned by annotate callback) + +- ``%D:`` commit date (as returned by annotate callback) + +- ``%d:`` commit date with time of day removed (*i.e.*, date part only) + +- ``%A:`` commit age. + +- ``%l`` source line number. + +``context_script`` = *path_to_executable_or_module | parameter* +--------------------------------------------------------------- + +This option is equivalent to the *\-\-context\-script* option of genhtml/lcov/geninfo + +This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script. + +See the genhtml man page for details. + +``criteria_script`` = *path_to_executable_or_module | parameter* +---------------------------------------------------------------- + +This option is equivalent to the *\-\-criteria\-script* option of genhtml/lcov/geninfo + +This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script. + +See the genhtml man page for details. + +``criteria_callback_data`` = *comma_separated_list* +----------------------------------------------------- + +This option is used to tell genhtml whether you want date and/or owner summary data passed back to your criteria callback. Note that summary data is always passed. + +Note that lcov and geninfo do not record date or owner data - and so do not pass it to the callback. + +This option can be used multiple times in the lcovrc file to specify both date and owner data should be returned, or you can specify both in a comma-separated list. Date and/or owner data will be returned if and only if your genhtml command has enabled annotation. + +If this option is appears multiple times in the lcovrc file; the values are combined to form the list of binning types which are passed to your callback. + +See the genhtml man page for details. + +``criteria_callback_levels`` = *comma_separated_list* +------------------------------------------------------ + +This option is used to tell genhtml whether criteria callbacks should occur at the top, directory, or file level. + +If this option is appears multiple times in the lcovrc file, the values are combined to form the list of report levels when your callback will be executed. + +See the genhtml man page for details. + +``check_existence_before_callback`` = *0 | 1* +---------------------------------------------- + +This option configures the tool to check that the file exists before calling the *annotate-script* or *version-script* callback. If set and file does not exist, a ``source`` error is triggered. (Note that the error may be ignored - see the *\-\-ignore\-error* option.) + +You may want to NOT check for file existence if your callback looks up information in a non-local repository. + +The default is 1 (check for file existence). + +``compute_file_version`` = *0 | 1* +----------------------------------- + +This option is used to tell the tool to generate missing file version information when reading a .info (coverage data) file. Version information may be missing because the data was generated by a tool which did not support versioning, or because the data was generated without the required *\-\-version\-script* argument - or for some other reason. + +Note that this option has no effect without a version\-script callback - defined by either the *\-\-version\-script* command line option or the *version\_script* config file option. + +The default is 0: do not generate missing information. + +``version_script`` = *path_to_executable | parameter* +----------------------------------------------------- + +This option is equivalent to the geninfo/lcov/genhtml "\-\-version\-script" option. + +This option can be used multiple times in the lcovrc file to specify both a version script and additional options which are passed to the script. + +See the genhtml man page for details. + +``resolve_script`` = *path_to_executable | parameter* +----------------------------------------------------- + +This option is equivalent to the geninfo/lcov/genhtml "\-\-resolve\-script" option. + +This option can be used multiple times in the lcovrc file to specify both a resolve script and additional options which are passed to the script. + +The resolve script provides a mechanism to find a source or data file that cannot be found by simply modify paths via substitution patterns (see *"substitute = replace\_regexp"* above) and searching along the corresponding directory list: + +``geninfo``: + the *"'build\_directory = dirname'"* config file entry or *\-\-build\=directory* command line option, used to search for GCNO files, + +``geninfo/genhtml/lcov``: + the *"'source\_directory = dirname'"* config file entry or *\-\-source\=directory* command line option, used to search for source files. + +The resolve script is called as: + +``resolve_script`` [callback_args] *file_name* + +or + +*$resolve_callback* = ``resolve_module`` ->new([callback_args]) + +to initialize the callback, then + +*$resolve\_callback*->``resolve`` *(file_name)* + +to find the actual file location. + +If necessary, the callback can check the suffix of the filename to determine whether it should look for either a source or data file. + +The script should return either empty string (file not found/no such file) or the actual path name. The returned path may be either absolute or relative to CWD. + +``select_script`` = *path_to_executable | parameter* +----------------------------------------------------- + +This option is equivalent to the genhtml "\-\-select\-script" option. + +This option can be used multiple times in the lcovrc file to specify both a select script and additional options which are passed to the script. + +The select script provides a mechanism to decide whether a particular source line is interesting - whether it should be included in the generated coverage report - or not. + +Lines which are not selected but fall within *num\_context\_lines* of a selected line are also included in the report. See below. + +Note that selection is fundamentally intended to show regions of code with some surrounding context. It might not do what you expect if there is no code - *e.g.*, if the region of interest has been compiled out via compiler or exclusion directives. For example: when selecting based on SHA or changelist ID, an inserted comment will not be selected unless it is within *num\_context\_lines* of an inserted or changed line of code. + +The select script is called as: + +``select_script`` [callback_args] *lineDataJson annotateDataJson fileName lineNumber* + +or as: + +*$selectCallback* = ``select_module`` ->new([callback_args]) + +to initialize the callback object, then as + +*$selectCallback* ``select`` *(lineDataRef annotateDataRef fileName lineNumber)* + +to determine selection, where + +- *fileName* is the name of the source file and + +- *lineNumber* is the source file line number, indexed from zero, + +- *lineDataJson* is a json-encoded LineData structure (see the lcovutil.pm source code), and + +- *annotateDataJson* is the json-encoded data returned by your *annotate\-script* (see the *\-\-annotate\-script* parameter in :manpage:`genhtml(1)`.), or the empty string if there are no annotations for this file. + +The module callback is similar except that is passed objects rather than JSON encodings of the objects. + +The script should return "1" or "0". + +See example implementation ``$|TOOL_NAME|_HOME/share/lcov/support-scripts/select.pm``. + +``unreachable_script`` = *path_to_module | parameter* +----------------------------------------------------- + +This option is equivalent to the geninfo/lcov/genhtml "\-\-unreachable\-script" option. + +This option can be used multiple times in the lcovrc file to specify both a module script and additional options which are passed to the callback. + +See the genhtml man page for details. + +``num_context_lines`` = *integer* +---------------------------------- + +Set the number of lines around each selected line which is included in the report - see *select\_script = ...* above and the *\-\-select\-script* command line option in :manpage:`genhtml(1)`. + +``filter`` = *str[,str...]* +---------------------------- + +This option is equivalent to the \-\-filter option to geninfo, lcov, and genhtml. See the genhtml man page for details. + +This option can be used multiple times in the lcovrc file to enable multiple filters. The filters specified in the lcovrc file are appended to the list specified on the command line. + +This option is used by genhtml, lcov, and geninfo. + +``exclude`` = *glob_pattern* +---------------------------- + +This option is equivalent to the \-\-exclude option to geninfo, lcov, and genhtml. See the lcov man page for details.; + +This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. The patterns specified in the lcovrc file are appended to the list specified on the command line. + +This option is used by genhtml, lcov, and geninfo. + +``include`` = *glob_pattern* +----------------------------- + +This option is equivalent to the \-\-include option to geninfo, lcov, and genhtml. See the lcov man page for details.; + +This option can be used multiple times in the lcovrc file to specify multiple patterns to include. The patterns specified in the lcovrc file are appended to the list specified on the command line. + +This option is used by genhtml, lcov, and geninfo. + +``simplify_script`` = *path_to_executable | parameter* +------------------------------------------------------ + +This option is equivalent to the genhtml *\-\-simplify\-script* option. This option can be used multiple times in the lcovrc file to specify both a simplify script and additional options which are passed to the script. + +See :manpage:`genhtml(1)` for details. + +``substitute`` = *regexp* +-------------------------- + +This option is equivalent to the \-\-substitute option to geninfo, lcov, and genhtml. See the lcov man page for details.; + +This option can be used multiple times in the lcovrc file to specify multiple substitution patterns. If patterns are specified on both the command line and in the lcovrc file, then the command line patterns are used and the lcovrc patterns are dropped. + +This option is used by genhtml, lcov, and geninfo. + +``omit_lines`` = *regexp* +-------------------------- + +This option is equivalent to the \-\-omit\-lines option to geninfo, lcov, and genhtml. See the genhtml man page for details. + +This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. The patterns specified in the lcovrc file are appended to the list specified on the command line. + +This option is used by genhtml, lcov, and geninfo. + +``erase_functions`` = *regexp* +------------------------------- + +This option is equivalent to the \-\-erase\-functions option to geninfo, lcov, and genhtml. See the genhtml man page for details. + +This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. The patterns specified in the lcovrc file are appended to the list specified on the command line. + +This option is used by genhtml, lcov, and geninfo. + +``lcov_json_module`` = *module | auto* +--------------------------------------- + +Specify the JSON module to use, or choose best available from a set of alternatives if set to 'auto'. Note that some JSON modules are slower than others (notably JSON::PP can be very slow compared to JSON::XS). + +Default is 'auto'. + +``split_char`` = *char* +------------------------ + +Specify the character (or regexp) used to split list-like parameters which have been passed as a single string. This parameter is useful in the case that you need want to use a multi-option string but one or more of the options contains a comma character which would otherwise be seen as a delimiter. + +Default is ',' (comma - no quotes). + +``scope_regexp`` = *regexp* +---------------------------- + +Print debug messages for data in filenames which match *regexp.* Only certain categories of message are logged; the set changes from time to time - depending on debug need. + +``case_insensitive`` = *[0|1]* +-------------------------------- + +Specify whether string comparison is case insensitive when finding matching filenames, checking include/exclude directives, etc. + +Note that mixed-case or lower-case pathnames may be passed to your \-\-version\-script and \-\-annotate\-script callbacks when case-insensitive matching is used. Your callbacks must handle potential differences in case. + +Default is '0': case sensitive matching. + +``sort_input`` = *[0|1]* +-------------------------- + +Specify whether to sort file names before capture and/or aggregation. Sorting reduces certain types of processing order-dependent output differences - *e.g.,* due to ambiguities in branch data generated by gcc. + +Default is '0': no sorting - process files in the order they were specified on the command line and/or were found during traversal of the filesystem. + + +FILES +----- + +*$|TOOL_NAME|_HOME/etc/lcovrc* + The system-wide ``lcov`` configuration file. + +*\~/.lcovrc* + The individual per-user configuration file. + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)`, :manpage:`gcov(1)` diff --git a/docs/man/llvm2lcov.rst b/docs/man/llvm2lcov.rst new file mode 100644 index 00000000..5f62617b --- /dev/null +++ b/docs/man/llvm2lcov.rst @@ -0,0 +1,132 @@ +========================================================== +llvm2lcov - Translate ``llvm-cov`` profdata to LCOV format +========================================================== + +:Manual section: 1 +:Manual group: |ToolName| Tools + +NAME +---- + +llvm2lcov + Translate LLVM coverage data from ``llvm-cov`` profdata to LCOV format + + +SYNOPSIS +-------- + +:: + + llvm2lcov [--output filename] [--testname name] [options] json_file [json_file ...] + +DESCRIPTION +----------- + +``llvm2lcov`` traverses C/C++ coverage data in JSON format (generated by +``llvm-cov export -format=text ...``) and translates it into LCOV ``.info`` +format. + +Note that LLVM supports two coverage data collection paths: the one described in this page - based on profile data - and a *gcov path* - similar to that supported by ``gcc``. See the LLVM documentation for more details about the ``gcov`` support in LLVM. + +MC/DC Coverage +-------------- + +To generate MC/DC data: + +- Use LLVM 18 or newer (LLVM 21+ recommended for cleaner MC/DC data) +- Enable MC/DC instrumentation in compile/link steps with ``-fcoverage-mcdc`` +- Pass the ``--mcdc-coverage`` flag to ``llvm2lcov`` + +Note that LLVM does not support MC/DC metrics when using the ``gcov`` data +collection path. + +OPTIONS +------- + +In addition to common options supported by other tools in the |ToolName| suite +(*e.g.*, ``--comment``, ``--version-script``, ``--ignore-error``, ``--substitute``, +``--exclude``, *etc.*), the tool provides the following options: + +``--output`` *filename*, ``-o`` *filename* + The |ToolName| data will be written to the specified file. If this option is + not used, data is written to ``llvm2lcov.info`` in the current directory. + +``--testname`` *name*, ``-t`` *name* + Coverage info will be associated with the testcase name provided. + It is not necessary to provide a name. + +``--branch-coverage`` + Include branch coverage data in the output. + +``--mcdc-coverage`` + Include MC/DC data in the output. Requires LLVM 18 or higher with MC/DC + instrumentation enabled during compilation. + +See :manpage:`lcov(1)` and :manpage:`lcovrc(5)` for details of other options +and configuration settings. + +EXAMPLES +-------- + +Basic workflow: + +:: + + # Compile with coverage instrumentation (including MC/DC) + $ clang++ -o myExe -fprofile-inst-generate -fcoverage-mapping \ + -fcoverage-mcdc myCode.cpp + + # Run your testcases + $ ./myExe ... + + # Convert profile data + $ llvm-profdata merge -o myExe.profdata --sparse *.profraw + + # Export coverage data in JSON format + $ llvm-cov export -format=text -instr-profile=myExe.profdata \ + ./myExe > myExe.json + + # Convert to LCOV format + $ llvm2lcov --output myExe.info --test-name myTestcase \ + --mcdc-coverage --branch-coverage myExe.json ... + + # Generate HTML coverage report + $ genhtml -o html_report myExe.info ... + +(``...`` indicates other tool options that you might be using - *e.g.*, +for filtering and exclusion.) + +Executing the same example via ``gcov`` looks like: + +:: + + # Compile with gcov instrumentation + $ clang++ -o myExe --coverage myCode.cpp + + # Run your testcases + $ ./myExe ... + + # Convert to LCOV format + # Note that the '--gcov-tool' option appears *twice*: once to name + # the tool and once to pass a tool option. See the lcov man page + # for more information. + $ lcov --capture -d . --branch-coverage -o myExe.info --gcov-tool llvm-cov --gcov-tool gcov ... + + # Generate HTML coverage report + $ genhtml -o html_report myExe.info ... + + +AUTHOR +------ + +Henry Cox + + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)`, +:manpage:`lcovrc(5)`, + +- LLVM documentation: https://llvm.org/docs/CoverageMappingFormat.html +- ``llvm-cov`` documentation: https://llvm.org/docs/CommandGuide/llvm-cov.html diff --git a/docs/man/perl2lcov.rst b/docs/man/perl2lcov.rst new file mode 100644 index 00000000..87736007 --- /dev/null +++ b/docs/man/perl2lcov.rst @@ -0,0 +1,111 @@ +======================================================== +perl2lcov - Translate Perl coverage data to lcov format. +======================================================== + + +:Manual section: 1 +:Manual group: |ToolName| Tools + +NAME +---- + +perl2lcov + Translate Perl coverage data from ``Devel::Cover`` to lcov format + +SYNOPSIS +-------- + +:: + + perl2lcov [--output filename] [--testname name] [options] cover_db+ + +DESCRIPTION +----------- + +``perl2lcov`` traverses Perl coverage information in one or more coverage +data directories (generated by the Perl ``Devel::Cover`` module) and translates +it into LCOV ``.info`` format. + +OPTIONS +------- + +In addition to common options supported by other tools in the |ToolName| suite +(*e.g.*, ``--comment``, ``--version-script``, ``--ignore-error``, ``--substitute``, +``--exclude``, *etc.*), the tool options are: + +``--output`` *filename*, ``-o`` *filename* + The |ToolName| data will be written to the specified file. If this option is + not used, data is written to ``perlcov.info`` in the current directory. + +``--testname`` *name* + Coverage info will be associated with the testcase name provided. + It is not necessary to provide a name. + +See :manpage:`lcov(1)` and :manpage:`lcovrc(5)` for details of other supported +options and configuration settings. + +EXAMPLES +-------- + +Generate Perl coverage data and translate to LCOV format: + +:: + + # Write Perl line, branch, condition, and subroutine coverage data + # to 'myPerlDB' in the current directory + $ perl -MDevel::Cover=-db,./myPerlDB,-coverage,statement,branch,condition,subroutine,-silent,1 myScript.pl + + # OR: write all coverage types that Perl knows about to 'myPerlDB2' + # Note that perl2lcov will ignore types it does not understand + # (pod, time, and path) + $ perl -MDevel::Cover=-db,./myPerlDB2,-silent,1 myScript.pl + + # Run 'cover' from the Devel::Cover installation to extract runtime + # data into a usable form. This will also generate an HTML report + # in 'myCoverDB' + $ cover myCoverDB -silent 1 + + # Run perl2lcov translator to produce LCOV format data: + $ perl2lcov -o perldata.info [--testname myTestName] myCoverDB + + # Generate an HTML coverage report: + $ genhtml -o html_report perldata.info + +NOTES +----- + +The data generated by ``Devel::Cover`` is not always internally consistent. +For example: + +- Some functions which are never called do not appear in the coverage data. + +- Sometimes a line will appear to be executed (non-zero hit count) but + none of its contained branch expressions have been evaluated. (If the line + was executed, then at least one branch condition must have been evaluated.) + +This can cause the various tools in the |ToolName| package to generate errors of +type ``inconsistent``. + +In that case, you can: + +- Skip consistency checks entirely: see the ``skip_consistency_checks`` section + in :manpage:`lcovrc(5)`. + +- Ignore the error: see the ``--ignore-error`` section in :manpage:`genhtml(1)`. + +- Exclude the offending code: see the ``--exclude``, ``--filter``, and + ``--omit-lines`` sections in :manpage:`genhtml(1)`. + +AUTHOR +------ + +Henry Cox + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`lcovrc(5)` + +- ``Devel::Cover`` module documentation + +https://metacpan.org/pod/Devel::Cover diff --git a/docs/man/py2lcov.rst b/docs/man/py2lcov.rst new file mode 100644 index 00000000..c4890992 --- /dev/null +++ b/docs/man/py2lcov.rst @@ -0,0 +1,182 @@ +============================================================== +py2lcov - Translate Python ``Coverage.py`` data to lcov format +============================================================== + +:Manual section: 1 +:Manual group: |ToolName| Tools + +NAME +---- + +py2lcov + Translate Python ``Coverage.py`` data to lcov format + + + +SYNOPSIS +-------- + +:: + + py2lcov [--output mydata.info] [--test-name name] [options] coverage.dat+ + +DESCRIPTION +----------- + +``py2lcov`` traverses Python coverage data in one or more coverage data files +(generated by the ``Coverage.py`` module) and translates it into LCOV ``.info`` +format. + +Note that the ``--no-functions`` argument may result in subtly inconsistent +coverage data if a ``no-functions`` coverage DB is merged with one which +contains derived function data. This is because the ``def myFunc(...)`` line +will acquire a hit count of 1 (the Python interpreter considers the ``def`` +to have been executed when the line is interpreted, *i.e.*, when the function +is defined). This will generate an ``inconsistent`` error if the function is +not executed in your tests because the (derived) function will have a zero +hit count but the first line of the function has a non-zero count. + +**Best practice**: Either always specify ``--no-functions`` or never specify +``--no-functions``. + +``py2lcov`` uses ``Coverage.py`` to extract coverage data. The name of the +``Coverage.py`` executable may differ on your platform. By default, ``py2lcov`` +uses ``coverage`` (expected to be in your PATH). You can use a different +executable via the ``COVERAGE_COMMAND`` environment variable or the ``--cmd`` +command line option. + +``py2lcov`` does not implement the full suite of |ToolName| features (*e.g.*, filtering, +substitutions, etc.). Generate the translated LCOV format file and then read +the data back into ``lcov`` to use those features. + +**Branch Coverage Limitations** + +Note that the XML coverage data format does not contain enough information +to deduce exactly which branch expressions have been taken or not taken. +It reports the total number of branch expressions associated with a particular +line, and the number of those which have been taken. There is no way to know +(except, possibly by inspection of surrounding code and/or some understanding +of your implementation) exactly which ones. + +This is a problem in at least 2 ways: + +- It is not straightforward to use the result to improve your regression + suite because you don't really know what was exercised/not exercised. + +- Coverage data merge is problematic. For example: you have two testcase + XML files, each of which hit 4 of 8 branches on some line. Does that + mean you hit 4 of them (both tests exercised the same code), all 8 + (tests exercised disjoint subsets), or some number between? + +This implementation assumes that the first M branches are the ones which +are hit and the remaining N-M were not hit, in each testcase. Thus, the +combined result in the above example would claim 4 of 8 branches hit. +This definition turns out to be a lower bound. + +OPTIONS +------- + +``-i``, ``--input`` *file* + **DEPRECATED**: Specify the input XML file from ``coverage.py``. + +``-o``, ``--output`` *file* + Specify the output LCOV ``.info`` file. Default: ``py2lcov.info``. + +``-t``, ``--test-name``, ``--testname`` *name* + Specify the test name for the ``TN:`` entry in the LCOV ``.info`` file. + +``-e``, ``--exclude`` *patterns* + Specify exclude file patterns separated by commas. + +``-v``, ``--verbose`` + Print debug messages. + +``--version-script`` *script* + Version extract callback script. + +``--checksum`` + Compute line checksum. See :manpage:`lcov(1)`. + +``--no-functions`` + Do not derive function coverpoints. + +``--tabwidth`` *n* + Tab size when computing indent. Default: 8. + +``-k``, ``--keep-going`` + Ignore errors and continue processing. + +``--cmd`` *executable* + Executable used to extract Python coverage data (*e.g.*, ``python3-coverage``). + Default: ``coverage`` (or value from ``COVERAGE_COMMAND`` environment variable). + +Note that ``py2lcov`` is a stand-alone Python executable - and so does *not* +directly support the standard |ToolName| command line and RC options - *e.g.*, for filtering, file inclusion and +exclusion, *etc.* +To use these options, you will have to first use ``py2lcov`` to capture +your coverage DB, and then apply the options you want to use via +``lcov -a pycov.info ...``. See :manpage:`lcov(1)` for details. + +EXAMPLES +-------- + +Basic workflow: + +:: + + $ export PYCOV_DATA=path/to/pydata + + # For 'coverage' versions 6.6.1 and higher (support "--data-file"): + $ coverage run --data-file=${PYCOV_DATA} --append --branch \ + /path/to/myPythonScript.py args_to_my_python_script + + # For older versions without "--data-file" support: + $ COVERAGE_FILE=${PYCOV_DATA} coverage run --append --branch \ + /path/to/myPythonScript.py args_to_my_python_script + + # Translate to LCOV format: + $ py2lcov -o pydata.info ${PYCOV_DATA} + + # Apply filtering: + $ lcov -a pydata.info -o filtered.info --filter branch,blank + + # Generate HTML report: + $ genhtml -o html_report pydata.info + + # Generate filtered report: + $ genhtml -o html_filtered filtered.info + + # Use differential coverage to see what filtering did: + $ genhtml -o html_differential --baseline-file mydata.info filtered.info + +Deprecated XML input mode: + +:: + + # First translate from Python coverage data to XML: + $ coverage xml --data-file=${PYCOV_DATA} -o pydata.xml + + # Then translate XML to LCOV format: + $ py2lcov -i pydata.xml -o pydata.info --version-script myCovScript + +ENVIRONMENT +----------- + +``COVERAGE_COMMAND`` + Override the default ``coverage`` executable used to extract Python coverage + data. + +``COVERAGE_FILE`` + Default input file if no files are specified on the command line. + +AUTHOR +------ + +Henry Cox + +SEE ALSO +-------- + +:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)` + +- ``Coverage.py`` documentation: https://coverage.readthedocs.io diff --git a/docs/man/spreadsheet.rst b/docs/man/spreadsheet.rst new file mode 100644 index 00000000..2c46d69c --- /dev/null +++ b/docs/man/spreadsheet.rst @@ -0,0 +1,140 @@ +====================================================================== +spreadsheet.py - Convert |ToolName| profile data to Excel spreadsheet +====================================================================== + +:Manual section: 1 +:Manual group: |ToolName| Utilities + +NAME +---- + +spreadsheet.py + Convert |ToolName| profile data to Excel spreadsheet for performance analysis and comparison + + +SYNOPSIS +-------- + +:: + + spreadsheet.py [-o output.xlsx] [options] data.json [data2.json ...] + +DESCRIPTION +----------- + +``spreadsheet.py`` is a utility script that converts JSON profile data from +``genhtml``, ``geninfo``, and ``lcov`` into an Excel spreadsheet for easier +analysis. The script processes performance timing data and presents it in a +tabular format with statistical analysis and conditional formatting. + +The spreadsheet includes: + +- **Summary sheets** for comparing multiple runs +- **Per-file timing data** for detailed analysis +- **Statistical summaries** (total, average, standard deviation) +- **Conditional formatting** to highlight outliers + +Color Coding +------------ + +The spreadsheet uses conditional formatting to highlight timing anomalies: + +- **Yellow**: Values between 1.5 and 2.0 standard deviations larger than average + (and more than 15% above average) +- **Red**: Values more than 2.0 standard deviations larger than average + (and more than 15% above average) +- **Green**: Values more than 2.0 standard deviations smaller than average + (significantly better performance) + +Supported Tools +--------------- + +The script processes profile data from: + +- **geninfo**: Chunk timing, file processing, filter operations +- **genhtml**: Source parsing, HTML generation, annotation, categorization +- **lcov**: Tracefile merging, parsing, segment processing + +OPTIONS +------- + +``-o`` *file*, ``--out`` *file* + Save Excel output to specified file. Default: ``stats.xlsx``. + +``--threshold`` *percent* + Minimum percentage difference from average to trigger colorization. + Differences smaller than this threshold are not highlighted. + Default: 15.0%. + +``--low`` *multiplier* + Standard deviation multiplier for yellow highlighting. Values between + ``--low`` and ``--high`` standard deviations above average are colored + yellow. Default: 1.5. + +``--high`` *multiplier* + Standard deviation multiplier for red highlighting. Values more than + ``--high`` standard deviations above average are colored red. + Default: 2.0. + +``-v``, ``--verbose`` + Increase verbosity of the report. Includes additional timing data + such as read and translate operations. + +``--show-filter`` + Include filter operation timing data in the spreadsheet. Filter data + shows time spent in filter chunk processing, queue operations, and + merging. + +*files* + One or more JSON profile data files to process. Files should be generated + using the ``--profile`` option of ``geninfo``, ``genhtml``, or ``lcov``. + +EXAMPLES +-------- + +Basic usage with a single profile file: + +:: + + $ spreadsheet.py -o report.xlsx geninfo_profile.json + +Compare multiple profile runs: + +:: + + $ spreadsheet.py -o comparison.xlsx run1.json run2.json run3.json + +Include filter timing data with verbose output: + +:: + + $ spreadsheet.py --show-filter -v -o detailed.xlsx profile.json + +Adjust sensitivity for outlier detection: + +:: + + $ spreadsheet.py --threshold 10 --low 1.0 --high 1.5 -o sensitive.xlsx data.json + +Generating Profile Data +----------------------- + +To generate profile data for analysis, use the ``--profile`` option: + +:: + + $ geninfo --profile geninfo_profile.json -o coverage.info ./build + $ genhtml --profile genhtml_profile.json -o html coverage.info + $ lcov --profile lcov_profile.json -a a.info -a b.info -o merged.info + +AUTHOR +------ + +Henry Cox + +SEE ALSO +-------- + +:manpage:`genhtml(1)`, :manpage:`geninfo(1)`, :manpage:`lcov(1)` + +- xlsxwriter documentation: https://xlsxwriter.readthedocs.io diff --git a/docs/scripts.rst b/docs/scripts.rst new file mode 100644 index 00000000..0aa54ade --- /dev/null +++ b/docs/scripts.rst @@ -0,0 +1,632 @@ +.. _scripts: + +============================ +|TOOL_NAME| Callback Scripts +============================ + +This section documents the callback scripts provided with |TOOL_NAME| for integration +with version control systems, coverage criteria checking, and report customization. + +Note that these are intended as examples of possible callback implementations - +but the intent is that users may want or need to write their own in order +to support specific requirements and/or development environments. + +.. contents:: Section Contents + :local: + :depth: 1 + :backlinks: none + + +Annotate Scripts: ``--annotate-script`` option +============================================== + +These scripts extract file annotation data (author, date, version) for age/ownership +tracking in differential coverage reports. + +.. _gitblame: + +gitblame.pm +----------- + +Run ``git blame`` for a file and format the result to match the diffcov(1) +annotation specification. + +:: + + use gitblame; + my $callback = gitblame->new([options]); + $callback->annotate(filename); + +**Options:** + +``--p4`` + Assume the GIT repo is cloned from Perforce - look for the changelist ID + in the commit log message. + +``--prefix`` *path* + Prepend *path* to pathname before processing. + +``--abbrev`` *regexp* + Specify regexp patterns to compute user name abbreviations. + +``--cache`` *dir* + Cache directory for storing previous results to improve performance. + +``--verify`` + Do additional consistency checking when merging local edits. + +``--log`` *logfile* + File for annotation-related log messages (useful for debugging). + +``--domain`` *name* + Strip domain from author addresses; treat users outside matching domain + as "External". + +Note that ``gitblame`` is a stand-alone executable which does the same thing +as ``gitblame.pm`` - except that it is called as an executable rather than +as a module. + + +.. _p4annotate: + +p4annotate.pm +------------- + +Run ``p4 annotate`` for a file and format the result to match the diffcov(1) +annotation specification. + +:: + + use p4annotate; + my $callback = p4annotate->new([options]); + $callback->annotate(filename); + +**Options:** + +``--cache`` *dir* + Cache directory for storing previous results. + +``--verify`` + Do additional consistency checking when merging local edits. + +``--log`` *logfile* + File for annotation-related log messages. + +Note that ``p4annotate`` is a stand-alone executable which does the same thing +as ``p4annotate.pm`` - except that it is called as an executable rather than +as a module. + + +Version Scripts: ``--version-script`` option +============================================ + +These scripts extract file version information for verifying that merged +coverage data comes from the same source version. + +Version checking is useful as it is easy to inadvertently mix data +from different branches or different products and then create misleading or +inconsistent reports which can be difficult to debug. + +.. _gitversion: + +gitversion.pm +------------- + +Use git commands to determine the version of a file. + +:: + + use gitversion; + my $callback = gitversion->new([options]); + $version = $callback->version($filepath); + $callback->compare_version($v1, $v2, $filepath); + +**Options:** + +``--p4`` + Assume the GIT repo is cloned from Perforce. + +``--md5`` + Return MD5 signature for files not in git. + +``--local-change`` + Check for local uncommitted changes. + +``--prefix`` *path* + Prepend *path* to pathname before processing. + + +Note that ``gitversion`` is a stand-alone executable which does the same thing +as ``gitversion.pm`` - except that it is called as an executable rather than +as a module. + + +.. _batchGitVersion: + +batchGitVersion.pm +------------------ + +Optimized version extraction that creates an initial database of version +stamps for all files, then queries during execution. + +:: + + use batchGitVersion; + my $callback = batchGitVersion->new([options]); + $version = $callback->extract_version(pathname); + +**Options:** + +``--md5`` + Use MD5 for files not in repo. + +``--allow-missing`` + Don't error if file is not in git. + +``--repo`` *repo* + Repository directory. + +``--prepend`` *path* + Prepend path to filenames. + +``--prefix`` *dir* + Prefix directory. + +``--token`` *string* + Token prefix for version strings. + +.. _P4version: + +P4version.pm +------------ + +Use Perforce commands to determine file versions. + +:: + + use P4version; + my $callback = P4version->new([options]); + $version = $callback->extract_version($filepath); + +**Options:** + +``--md5`` + Return MD5 for files not in depot. + +``--allow-missing`` + Don't error if file is not in depot. + +``--local-edit`` + Check for local edits. + +``--prefix`` *path* + Prepend *path* to pathname. + +Note that ``getp4version`` is a stand-alone executable which does the same thing +as ``P4version.pm`` - except that it is called as an executable rather than +as a module. + + +Diff Scripts: ``--diff-file`` option +==================================== + +These scripts extract unified diffs between versions for differential coverage. + +.. _p4udiff: + +p4udiff +------- + +Extract unified-diff between two Perforce changelists. + +:: + + p4udiff [options] old_cl new_cl + +**Options:** + +``--depot`` *path* + Depot path prefix. + +``--sandbox`` *path* + Local sandbox path. + +``--exclude`` *pattern* + Exclude files matching pattern. + +``--include`` *pattern* + Include only files matching pattern. + +``--verbose`` + Print debug messages. + +.. _gitdiff: + +gitdiff +------- + +Extract unified-diff between two git SHAs. + +:: + + gitdiff [options] base_SHA current_SHA + +**Options:** + +``--repo`` *directory* + Git repository directory. Default: current directory. + +``--prefix`` *path* + Leading path to strip from file pathnames. + +``--exclude`` *regexp* + Exclude files matching pattern. + +``--include`` *regexp* + Include only files matching pattern. + +``--no-unchanged`` + Remove unchanged file references from diff. + +``-b``, ``--blank`` + Ignore whitespace changes. + +``--verbose`` + Print debug messages. + +Criteria Scripts: ``--criteria-script`` option +============================================== + +These scripts implement coverage criteria callbacks for pass/fail decisions. + +.. _criteria: + +criteria.pm +----------- + +Sample criteria script that checks "UNC + LBC + UIC == 0". + +:: + + genhtml --criteria-script 'criteria.pm [--signoff] [--function] [--branch] [--mcdc]' + +**Options:** + +``--signoff``, ``--suppress`` + Exit with status 0 even if criteria not met. + +``--function`` + Check function coverage. + +``--branch`` + Check branch coverage. + +``--mcdc`` + Check MC/DC coverage. + +Note that ``criteria`` is a stand-alone executable which does the same thing +as ``criteria.pm`` - except that it is called as an executable rather than +as a module. + + +.. _threshold: + +threshold.pm +------------ + +Check that coverage exceeds specified thresholds. + +:: + + genhtml --criteria-script 'threshold.pm,--line,85,--branch,70,--function,100' + +**Options:** + +``--line`` *percent* + Minimum line coverage percentage. + +``--branch`` *percent* + Minimum branch coverage percentage. + +``--function`` *percent* + Minimum function coverage percentage. + +``--signoff`` + Exit 0 even if thresholds not met. + +Subset Selection/Code Review: ``--select-script`` option +======================================================== + +.. _select: + +select.pm +--------- + +Select a subset of source code to include in the HTML report. + +This is useful for code review - say, between releases or of a particular +commit or range of commits - or when you are interested in code authored or +owned by your team and do not want to look at the entire project. + +:: + + genhtml --select-script 'select.pm,--tla,LBC;UNC,--range,5:10' + +**Options:** + +``--tla`` *categories* + Comma-separated differential categories to retain (UNC, LBC, UIC, etc.). + +``--sha`` *id* + Git SHAs to retain (comma-separated). + +``--cl`` *id* + Perforce changelists to retain (comma-separated). + +``--range`` *min:max* + Age range in days to retain. + +``--owner`` *regexp* + Regular expression to match owner names. + +``--separator`` *char* + Character to separate list arguments. + + +Find source files - in nontrivial build environment: ``--resolve-script`` option +================================================================================= + +.. _resolve: + +In a complicated build environment - for example, to build the LLVM toolchain - +it can be difficult to tell |TOOL_NAME| how to find your your source +code using only ``--build-directory``, ``--source-directory``, and +``--substitute`` options. +The ``--resolve-script`` callback can be and easier to understand. + + + +Modify appearance of displayed code: ``--simplify-script`` option +================================================================== + +.. _simplify: + +simplify.pm +----------- + +Simplify function names in the function detail tables - say, to use +regexps to shorten very long C++ template names. + +:: + + genhtml --simplify-script 'simplify.pm,--re,regexp' + +**Options:** + +``--file`` *pattern_file* + File containing Perl regexps (one per line). + +``--re`` *regexp* + Perl regexp or separator-separated list of regexps. + +``--separator`` *char* + Separator character for regexp lists. + +.. _unreach: + + +Tag unreachable coverpoints: ``--unreach-script`` option +========================================================= + +unreach.pm +---------- + +Identify unreachable branches and MC/DC conditions so that they do +not appear in coverage reports. + +:: + + genhtml --unreachable-script 'unreach.pm,--branch,--mcdc' + +**Options:** + +``--branch`` + Support branch filtering. + +``--mcdc`` + Support MC/DC filtering. + +**Comment Format:** + +- Branch: ``// LCOV_UNREACHABLE_BRANCH (expressionId[,blockId])+`` +- MC/DC: ``// LCOV_UNREACHABLE_MCDC (conditionId)+`` + + +Load balancing: ``--history-script`` option +============================================ + +.. _history: + +history.pm +---------- + +Reuse profile history from prior tool execution for better load balancing +during parallel execution + +:: + + genhtml --history-script history.pm --profile previous_profile.json + + +Environment/context: ``--context-script`` option +================================================= + +.. _context: + + +context.pm +---------- + +Collect and store context data for infrastructure debugging/tracking. + +:: + + genhtml --context-script context.pm + + + +Performance monitoring and optimization +======================================= + +spreadsheet.py +-------------- + +Generate Excel spreadsheets from |TOOL_NAME| profile data for performance analysis. + +:: + + spreadsheet.py [--verbose] profile.json output.xlsx + +Creates sheets for: + +- Capture summary +- Processing times +- Chunk analysis +- Filtering statistics + + +Other Scripts +============= + +These are additional utility scripts provided for specific workflows. + +.. _analyzeInfoFiles: + +analyzeInfoFiles +---------------- + +Check for consistency across a set of .info files for the same code base. + +:: + + analyzeInfoFiles [options] infoFile infoFile ... + +**Arguments:** + +*infoFile* + .info file (ending in ".info") or data file containing names of .info files. + Data file comment character is '#'. + +**Options:** + +``--include`` *glob* + glob pattern to match source filenames to check. + +``--exclude`` *glob* + glob pattern to match source filenames to skip. + +``--substitute`` *regexp* + Munge source file path when reading .info files. + +``--keep-going`` + Do not stop after mismatch found. + +``--all`` + Print all regions (not just regions with conflicting votes). + +``--drop`` + Ignore .info file if it does not contain some source file - continue to + check consistency in the .info files which do contain the file. + +``--compact`` + Compact printing of source code region. + +``--sort`` + Sort by region size. + +``--verbose``, ``-v`` + Be chatty. + +``--help``, ``-h`` + Print usage message. + +**Checks:** + +- Is every source file present in every .info file? +- For every source file that is not dropped: + - Is the version ID the same in all the .info files? + - Do all the .info files agree about the status of every line? + +.. _getp4version: + +getp4version +------------ + +Use Perforce commands to determine the version of a file. +This is the same as the ``P4version.pm`` module described above - except +that it is called as an executable rather than a module. + +:: + + getp4version [--md5] [--allow-missing] filename + + getp4version --compare old_version new_version filename + +**Options:** + +``--md5`` + Append MD5 checksum to the P4 version string. + +``--allow-missing`` + Do not error if file is not in depot. + +``--compare`` + Compare two version strings. + +``--help`` + Print usage message. + +**Output:** + +Returns version information (revision number or \"@head\") for files in the depot, +or modification time for files not in depot. If ``--md5`` is specified, includes +MD5 checksum. + +.. _get_signature: + +get_signature +------------- + +Compute MD5 signature for a file. + +:: + + get_signature [--allow-missing] filename + + get_signature --compare old_version new_version filename + +**Options:** + +``--allow-missing`` + Do not error if file does not exist. + +``--compare`` + Compare two signature strings. + +``--help`` + Print usage message. + +**Output:** + +Returns MD5 checksum of the specified file. + + +AUTHOR +====== + +Henry Cox + +SEE ALSO +======== + +:manpage:`genhtml(1)`, :manpage:`lcov(1)`, :manpage:`geninfo(1)`, :manpage:`llvm2lcov(1)`, :manpage:`perl2lcov(1)` diff --git a/example/Makefile b/example/Makefile index 4f66cabb..6c0077c9 100644 --- a/example/Makefile +++ b/example/Makefile @@ -46,6 +46,8 @@ GENDESC := $(EXEC_COVER) $(BINDIR)/gendesc GENPNG := $(EXEC_COVER) $(BINDIR)/genpng SCRIPTDIR = $(shell if [ -d ../scripts ] ; then echo $(SCRIPTS) ; else echo $(LCOV_HOME)/share/lcov/support-scripts ; fi) +GITDIFF := $(EXEC_COVER) $(SCRIPTDIR)/gitdiff + # Depending on the presence of the GD.pm perl module, we can use the # special option '--frames' for genhtml USE_GENPNG := $(shell $(GENPNG) --help >/dev/null 2>/dev/null; echo $$?) @@ -206,7 +208,7 @@ test_differential: --history $(SCRIPTDIR)/history.pm,baseline.info.json ) @echo "Compute source diffs" (cd $(REPO) ; \ - $(SCRIPTDIR)/gitdiff -b . `git rev-list -n 1 baseline` \ + $(GITDIFF) -b . `git rev-list -n 1 baseline` \ `git rev-list -n 1 current` > udiff.txt ) @echo "Step 6: Generate differential coverage report" diff --git a/example/README b/example/README deleted file mode 100644 index d0cf08cb..00000000 --- a/example/README +++ /dev/null @@ -1,81 +0,0 @@ -To see some examples of LCOV generated HTML coverage reports, run - - $ make - -in the .../examples directory, review the 'make' log and the generated -data, and then point a web browser into the resulting reports. - -The example builds with GCC by default. -You will need to make a few changes if you want to use LLVM instead. - - -Default view: - - - Point your browser to - output/index.html - -Hierarchical view: - - - Point your browser to - hierarchical/index.html - - - Note that that the coverage data is the same - only the report - format is different: - - - Follows directory structure, similar to MS file viewer - ('--hierarchical' flag) - - - Additional navigation links also enabled - ('--show-navigation' flag) - -Differential coverage: - - - Point your browser to - exampleRepo/differential/index.html - - - This example is slightly complicated because it emulates a moderately - realistic project in that it pretends to see project changes: - - - updates to two project source files example.c and iterate.c - - - change to the test suite: only one test of updated - code rather than 3 of the original code - - - The Makefile simulates this by checking code into a git repo, - building an executable and then updating a few source files, rebuildling, - and running some tests. - -Code review: - - - point your browser to - exampleRepo/review/index.html - - - This example builds on the "Differential coverage" example, above - to emulate a possible code review methodology in which adds code - coverage to the review criteria. - The intent is to generate a reduced report which shows only the - code changes which negatively affect code coverage - while removing - other details which only distract from the review. - - - Use the 'genhtml --select-script ...' feature to show only new - source code which was negatively affected by the change under - review (uncovered and/or lost code). - You might want to modify the select criteria to include positive - change (e.g., GNC, GBC, and GIC categories). - - - Real use cases are likely to use more sophisticated select-script - callbacks (e.g., to select from a range of changelists). - - - The example uses caching and profile history to improve runtime - performance - see the man pages for a more detailed description - of the features. There is no effect with a tiny example - but - a real project may see benefit. - The 'spreadsheet.py' application script can be used to convert - JSON profile files into more readable excel spreadsheets. This - can be useful to see the effect (if any) of the caching and/or - history features, and can show where time is spent for your example. - This can be helpful, to suggest opportunities to optimize the LCOV - implementation. - -Feel free to edit the Makefile or to run the lcov utilities directly, -to see the effect of other options that you find in the lcov man pages. diff --git a/example/README.rst b/example/README.rst new file mode 100644 index 00000000..e6f64bbe --- /dev/null +++ b/example/README.rst @@ -0,0 +1,79 @@ +To see some examples of |TOOL_NAME| generated HTML coverage reports:: + + $ cp -r $|TOOL_NAME|_HOME/share/lcov/example . + $ cd example + $ make + +Review the 'make' log and the generated +data, and then point a web browser into the resulting reports. + +The example builds with GCC by default. +You will need to make a few changes if you want to use LLVM instead. + + +- Default view: + + - Point your browser to ``output/index.html`` + +- Hierarchical view: + + - Point your browser to ``hierarchical/index.html`` + + - Note that that the coverage data is the same - only the report + format is different: + + - Follows directory structure, similar to MS file viewer + (``--hierarchical`` flag) + + - Additional navigation links also enabled + (``--show-navigation`` flag) + +- Differential coverage: + + - Point your browser to ``exampleRepo/differential/index.html`` + + - This example is slightly complicated because it emulates a moderately + realistic project in that it pretends to see project changes: + + - updates to two project source files ``example.c`` and ``iterate.c`` + + - change to the test suite: only one test of updated + code rather than 3 of the original code + + The Makefile simulates this by checking code into a git repo, + building an executable and then updating a few source files, rebuilding, + and running some tests. + +- Code review: + + - point your browser to ``exampleRepo/review/index.html`` + + - This example builds on the **Differential coverage** example, above + to emulate a possible code review methodology in which adds code + coverage to the review criteria. + The intent is to generate a reduced report which shows only the + code changes which negatively affect code coverage - while removing + other details which only distract from the review. + + - Use the ``genhtml --select-script ...`` feature to show only new + source code which was negatively affected by the change under + review (uncovered and/or lost code). + You might want to modify the select criteria to include positive + change (*e.g.*, GNC, GBC, and GIC categories). + + - Real use cases are likely to use more sophisticated select-script + callbacks (*e.g.*, to select from a range of changelists). + + - The example uses caching and profile history to improve runtime + performance - see the man pages for a more detailed description + of the features. There is no effect with a tiny example - but + a real project may see benefit. + The ``spreadsheet.py`` application script can be used to convert + JSON profile files into more readable excel spreadsheets. This + can be useful to see the effect (if any) of the caching and/or + history features, and can show where time is spent for your example. + This can be helpful, to suggest opportunities to optimize the |ToolName| + implementation. + +Feel free to edit the Makefile or to run the lcov utilities directly, +to see the effect of other options that you find in the lcov man pages. diff --git a/lcovrc b/lcovrc index 7d319cf7..081eb0d6 100644 --- a/lcovrc +++ b/lcovrc @@ -230,7 +230,7 @@ genhtml_desc_html=0 # Set threshold for hit count which tool should deem likely to indicate # a toolchain bug (corrupt coverage data) -# excessive_count_theshold = number +# excessive_count_threshold = number # Demangle C++ symbols # Call multiple times to specify command and command line arguments @@ -336,7 +336,7 @@ mcdc_coverage = 0 # set to empty to elide tooltip # Substitutions: # %d: line number -# %C: commit ID (from annotate callback - see --anotate-script entry in +# %C: commit ID (from annotate callback - see --annotate-script entry in # genhtml documentation) # %U: commit author abbreviated name # %F: commit author full name diff --git a/lib/lcovutil.pm b/lib/lcovutil.pm index 65700eaa..8cc4848c 100644 --- a/lib/lcovutil.pm +++ b/lib/lcovutil.pm @@ -115,7 +115,7 @@ our $tool_name = basename($0); # import from lcovutil module our $VERSION = `"$tool_dir"/get_version.sh --full`; chomp($VERSION); our $lcov_version = 'LCOV version ' . $VERSION; -our $lcov_url = "https://github.com//linux-test-project/lcov"; +our $lcov_url = "https://github.com/linux-test-project/lcov"; our @temp_dirs; our $tmp_dir = '/tmp'; # where to put temporary/intermediate files our $preserve_intermediates; # this is useful only for debugging @@ -287,7 +287,7 @@ our $FILTER_BRANCH_NO_COND; # don't report line coverage for closing brace of a function # or basic block, if the immediate predecessor line has the same count. our $FILTER_LINE_CLOSE_BRACE; -# merge functions which appear on same file/line - guess that that +# merge functions which appear on same file/line - guess that # they are all the same our $FILTER_FUNCTION_ALIAS; # region between LCOV EXCL_START/STOP @@ -2468,7 +2468,7 @@ sub report_exit_status MessageContext::context(); if ($signal) { $explain = - "$prefix died died due to signal $signal (SIG" . + "$prefix died due to signal $signal (SIG" . (split(' ', $Config{sig_name}))[$signal] . ')' . MessageContext::context() . ': possibly killed by OS due to out-of-memory'; @@ -3346,10 +3346,10 @@ sub context $line =~ s/\r//g; # remove CR from line-end # first word on line is the key.. my ($key, $value) = split(/ +/, $line, 2); - if (exists($context{key})) { - $context{key} .= "\n" . $value; + if (exists($context{$key})) { + $context{$key} .= "\n" . $value; } else { - $context{key} = $value; + $context{$key} = $value; } } my $status = $iter->close(1); # check error return @@ -3517,7 +3517,7 @@ sub load_json_module($) } if (!defined($did_init)) { - die("No Perl JSON module found on your system. Please install of of the following supported modules: " + die("No Perl JSON module found on your system. Please install one of the following supported modules: " . join(" ", @alternatives) . " - for example (as root):\n \$ perl -MCPAN -e 'install " . $alternatives[0] @@ -4625,7 +4625,7 @@ sub insertExpr } else { if ($idx != scalar(@$group)) { lcovutil::ignorable_error($lcovutil::ERROR_FORMAT, - "\"$filename\":" . '":' . $self->line() . + "\"$filename\":" . $self->line() . ": MC/DC group $groupSize: non-contiguous expression '$idx' found - should be '" . scalar(@$group) . "'."); @@ -5032,7 +5032,7 @@ sub merge $self->name() . " has different location than " . $that->name() . " during merge") - if ($self->line() != $self->line()); + if ($self->line() != $that->line()); while (my ($name, $count) = each(%{$that->[ALIASES]})) { $self->addAlias($name, $count); } @@ -5679,7 +5679,7 @@ sub difference $changedHere = 1; # ignore all the leading common blocks... for (my $idx = $yourCount; $idx <= $#$myList; ++$idx) { - my $mine = $myList->[$idx++]; + my $mine = $myList->[$idx]; my $catBlock = Storable::dclone($mine); $replace->insertBlock($catBlock); } @@ -5788,7 +5788,7 @@ sub union $changed += $myBranch->merge($yourBranch, $filename); } else { lcovutil::ignorable_error($lcovutil::ERROR_INCONSISTENT_DATA, - "cannot merge iconsistent MC/DC record"); + "cannot merge inconsistent MC/DC record"); # possibly remove this record? } } @@ -5813,7 +5813,7 @@ sub intersect $changed += $myBranch->merge($yourBranch, $filename); } else { lcovutil::ignorable_error($lcovutil::ERROR_INCONSISTENT_DATA, - "cannot merge iconsistent MC/DC record"); + "cannot merge inconsistent MC/DC record"); # possibly remove this record? } } else { @@ -6531,16 +6531,16 @@ sub parseLines if (defined($lcovutil::cov_filter[$lcovutil::FILTER_EXCLUDE_BRANCH])) { push(@excludes, - [$excl_ex_start, $excl_ex_stop, - \$exclude_exception_region, e_EXCEPTION | EXCLUDE_BRANCH_REGION, - $lcovutil::EXCL_BR_START, $lcovutil::EXCL_BR_STOP, - ], - [$excl_br_start, - $excl_br_stop, - \$exclude_br_region, - e_BRANCH | EXCLUDE_BRANCH_REGION, + [$excl_ex_start, + $excl_ex_stop, + \$exclude_exception_region, + e_EXCEPTION | EXCLUDE_BRANCH_REGION, $lcovutil::EXCL_EXCEPTION_BR_START, $lcovutil::EXCL_EXCEPTION_BR_STOP, + ], + [$excl_br_start, $excl_br_stop, + \$exclude_br_region, e_BRANCH | EXCLUDE_BRANCH_REGION, + $lcovutil::EXCL_BR_START, $lcovutil::EXCL_BR_STOP, ]); } else { $excl_br_line = undef; @@ -6780,7 +6780,7 @@ sub isExcluded # - non-zero if the line is excluded (in an excluded or unreachable # region), or if '$flags" is set and the exclusion reason includes # at least one of the flags. - # - The latter condition is used to check for branch-only or execption- + # - The latter condition is used to check for branch-only or exception- # only exclusions, as well as to check whether this line is # unreachable (as opposed to excluded). my ($self, $lineNo, $flags, $skipRangeCheck) = @_; @@ -6790,7 +6790,7 @@ sub isExcluded # version N of the file, then generating HTML with version M # "--version-script callback" option can be used to detect this - # if we are just checking whether this line in in an unreachable region, + # if we are just checking whether this line is in an unreachable region, # then don't check for out-of-range (that check happens later) return 0 if $skipRangeCheck; @@ -7972,7 +7972,7 @@ sub _filterFile $fileVersion, 'filter') ) { lcovutil::info(1, - '$source_file: skip filtering due to version mismatch\n'); + "$source_file: skip filtering due to version mismatch\n"); return ($traceInfo, 0); } @@ -9177,7 +9177,7 @@ sub _read_info # (for the same file) $functionMap->define_function($fnName, $lineNo, $end_line ? $end_line : undef, - , "\"$tracefile\":$."); + "\"$tracefile\":$."); last; }; @@ -9490,7 +9490,7 @@ sub write_info($$$) foreach my $filename (sort($self->files())) { my $entry = $self->data($filename); my $source_file = $entry->filename(); - die("expected to have have filtered $source_file out") + die("expected to have filtered $source_file out") if lcovutil::is_external($source_file); die("expected TraceInfo, got '" . ref($entry) . "'") unless ('TraceInfo' eq ref($entry)); diff --git a/man/gendesc.1 b/man/gendesc.1 deleted file mode 100644 index 984b5b25..00000000 --- a/man/gendesc.1 +++ /dev/null @@ -1,85 +0,0 @@ -\" Define project URL -.ds lcovurl https://github.com/linux\-test\-project/lcov - -.TH gendesc 1 "LCOV 2.0" 2023\-05\-12 "User Manuals" -.SH NAME -gendesc \- Generate a test case description file -.SH SYNOPSIS -.B gendesc -.RB [ \-h | \-\-help ] -.RB [ \-v | \-\-version ] -.RS 8 -.br -.RB [ \-o | \-\-output\-filename -.IR filename ] -.br -.I inputfile -.SH DESCRIPTION -Convert plain text test case descriptions into a format as understood by -.BR genhtml . -.I inputfile -needs to observe the following format: - -For each test case: -.IP " \-" -one line containing the test case name beginning at the start of the line -.RE -.IP " \-" -one or more lines containing the test case description indented with at -least one whitespace character (tab or space) -.RE - -.B Example input file: - -test01 -.RS -An example test case description. -.br -Description continued -.RE - -test42 -.RS -Supposedly the answer to most of your questions -.RE - -Note: valid test names can consist of letters, decimal digits and the -underscore character ('_'). -.SH OPTIONS -.B \-h -.br -.B \-\-help -.RS -Print a short help text, then exit. -.RE - -.B \-v -.br -.B \-\-version -.RS -Print version number, then exit. -.RE - - -.BI "\-o " filename -.br -.BI "\-\-output\-filename " filename -.RS -Write description data to -.IR filename . - -By default, output is written to STDOUT. -.RE -.SH AUTHOR -Peter Oberparleiter - -.SH SEE ALSO -.BR lcov (1), -.BR genhtml (1), -.BR geninfo (1), -.BR genpng (1), -.BR gcov (1) -.br - -.I \*[lcovurl] -.br diff --git a/man/genhtml.1 b/man/genhtml.1 deleted file mode 100644 index 31f3593a..00000000 --- a/man/genhtml.1 +++ /dev/null @@ -1,3890 +0,0 @@ -\" Define path to scripts -.ds scriptdir scripts - -\" Define project URL -.ds lcovurl https://github.com/linux\-test\-project/lcov - -.TH genhtml 1 "LCOV 2.0" 2023\-05\-17 "User Manuals" -.SH NAME -genhtml \- Generate HTML view from LCOV coverage data files -.SH SYNOPSIS -.B genhtml -.RB [ \-h | \-\-help ] -.RB [ \-\-version ] -.RS 8 -.br -.RB [ \-q | \-\-quiet ] -.RB [ \-v | \-\-verbose ] -.br -.RB [ \-\-debug ] [ \-\-validate ] -.br -.RB [ \-s | \-\-show\-details ] -.br -.RB [ \-f | \-\-frames ] -.br -.RB [ \-b | \-\-baseline\-file -.IR baseline\-file\-pattern ] -.br -.RB [ \-o | \-\-output\-directory -.IR output\-directory ] -.br -.RB [ \-\-header-title -.IR banner ] -.br -.RB [ \-\-footer -.IR string ] -.br -.RB [ \-t | \-\-title -.IR title ] -.br -.RB [ \-d | \-\-description\-file -.IR description\-file ] -.br -.RB [ \-k | \-\-keep\-descriptions ] -.RB [ \-c | \-\-css\-file -.IR css\-file ] -.br -.RB [ \-p | \-\-prefix -.IR prefix ] -.RB [ \-\-no\-prefix ] -.br -.RB [ \-\-build\-directory -.IR directory ] -.br -.RB [ \-\-source\-directory -.IR dirname ] -.br -.RB [ \-\-no\-source ] -.RB [ \-\-no\-html ] -.br -.RB [ \-\-num\-spaces -.IR num ] -.RB [ \-\-highlight ] -.br -.RB [ \-\-legend ] -.RB [ \-\-html\-prolog -.IR prolog\-file ] -.br -.RB [ \-\-html\-epilog -.IR epilog\-file ] -.RB [ \-\-html\-extension -.IR extension ] -.br -.RB [ \-\-html\-gzip ] -.RB [ \-\-sort\-tables ] -.RB [ \-\-no\-sort ] -.br -.RB [ \-\-function\-coverage ] -.RB [ \-\-no\-function\-coverage ] -.br -.RB [ \-\-branch\-coverage ] -.RB [ \-\-no\-branch\-coverage ] -.br -.RB [ \-\-mcdc\-coverage ] -.br -.RB [ \-\-demangle\-cpp -.IR [ param ] ] -.br -.RB [ \-\-msg\-log -.IR [ log_file_name ] ] -.br -.RB [ \-\-ignore\-errors -.IR errors ] -.br -.RB [\-\-expect\-message\-count -.IR message_type=expr[,message_type=expr..]] -.br -.RB [ \-\-keep\-going ] -.RB [ \-\-config\-file -.IR config\-file ] -.br -.RB [ \-\-profile -.IR [profile\-file ]] -.br -.RB [ \-\-history-script -.IR callback ] -.br -.RB [ \-\-rc -.IR keyword = value ] -.br -.RB [ \-\-precision -.IR num ] -.RB [ \-\-missed ] -.br -.RB [ \-\-merge\-aliases ] -.br -.RB [ \-\-suppress\-aliases ] -.br -.RB [ \-\-forget\-test\-names ] -.br -.RB [ \-\-dark\-mode ] -.br -.RB [ \-\-baseline\-title -.IR title ] -.br -.RB [ \-\-baseline\-date -.IR date ] -.br -.RB [ \-\-current\-date -.IR date ] -.br -.RB [ \-\-diff\-file -.IR diff\-file ] -.br -.RB [ \-\-annotate\-script -.IR script ] -.br -.RB [ \-\-context\-script -.IR script ] -.br -.RB [ \-\-criteria\-script -.IR script ] -.br -.RB [ \-\-version\-script -.IR script ] -.br -.RB [ \-\-resolve\-script -.IR script ] -.br -.RB [ \-\-select\-script -.IR script ] -.br -.RB [ \-\-simplify\-script -.IR script ] -.br -.RB [ \-\-unreachable\-script -.IR module ] -.br -.RB [ \-\-checksum ] -.br -.RB [ \-\-fail\-under\-branches -.IR percentage ] -.br -.RB [ \-\-fail\-under\-lines -.IR percentage ] -.br -.RB [ \-\-new\-file\-as\-baseline ] -.br -.RB [ \-\-elide\-path\-mismatch ] -.br -.RB [ \-\-synthesize\-missing ] -.br -.RB [ \-\-date\-bins -.IR day[,day,...]] -.br -.RB [ \-\-date\-labels -.IR string[,string,...]] -.br -.RB [ \-\-show\-owners -.IR [ all ] ] -.br -.RB [ \-\-show\-noncode ] -.br -.RB [ \-\-show\-zero\-columns ] -.br -.RB [ \-\-show\-navigation ] -.br -.RB [ \-\-show\-proportions ] -.br -.RB [ \-\-simplified-colors ] -.br -.RB [ \-\-hierarchical ] -.RB [ \-\-flat ] -.br -.RB [ \-\-filter -.IR filters ] -.br -.RB [ \-\-include -.IR glob_pattern ] -.br -.RB [ \-\-exclude -.IR glob_pattern ] -.br -.RB [ \-\-erase\-functions -.IR regexp_pattern ] -.br -.RB [ \-\-substitute -.IR regexp_pattern ] -.br -.RB [ \-\-omit\-lines -.IR regexp_pattern ] -.br -.RB [ \-\-parallel | -j -.IR [integer] ] -.br -.RB [ \-\-memory -.IR integer_num_Mb ] -.br -.RB [ \-\-tempdir -.IR dirname ] -.br -.RB [ \-\-preserve ] -.br -.RB [ \-\-save ] -.br -.RB [ \-\-sort\-input ] -.br -.RB [ \-\-serialize -.IR serialize_output_file ] -.br -.IR tracefile_pattern(s) -.RE -.SH DESCRIPTION - -.B genhtml -creates an HTML view of coverage data found in tracefiles -.B geninfo -and -.B lcov -tools which are found from glob-match pattern(s) -.I tracefile_pattern. -See man -.B geninfo(1) for a description of the tracefile format. - - Features include: - -.IP \(bu 3 -Differential coverage comparison against baseline coverage data -.PP -.IP \(bu 3 -Annotation of reports with date and owner information ("binning") -.PP - -The basic concepts of differential coverage and date/owner binning are described in the paper found at -.I https://arxiv.org/abs/2008.07947 - -.SS Differential coverage - -Differential coverage compares two versions of source code - the baseline and the current versions - and the coverage results for each to segment the code into categories. -.br - -To create a differential coverage report, -.B genhtml -requires - -.IP 1. 3 -one or more -.I baseline\-files -specified via -.BR \-\-baseline\-file , -and -.PP -.IP 2. 3 -a patch file in unified format specified using -.BR \-\-diff\-file . -.PP -.br - -Both -.I tracefile_pattern -and -.I baseline\-file -are treated as glob patterns which match one or more files. -.br - -The difference in coverage between the set of -.I tracefiles -and -.I baseline\-files -is classified line-by-line into categories based on changes in 2 aspects: - -.IP 1. 3 -.BR "Test coverage results" : -a line of code can be tested (1), untested (0), -or unused (#). An unused line is a source code line that has no associated -coverage data, for example due to a disabled #ifdef statement. -.br -.PP - -.IP 2. 3 -.BR "Source code changes" : -a line can be unchanged, added (+\ =>), or removed (=>\ \-). -Note that the diff-file format used by -.B genhtml -reports changes in lines as removal of old line and addition of new line. -.br -.PP - -Below are the resulting 12 categories, sorted by priority (assuming that untested code is more interesting than tested code, and new code is more interesting than old code): -.br - -.RE -.B UNC -.RS -Uncovered New Code (+ => 0): newly added code is not tested. -.br -.RE - -.B LBC -.RS -Lost Baseline Coverage (1 => 0): unchanged code is no longer tested. -.br -.RE - -.B UIC -.RS -Uncovered Included Code (# => 0): previously unused code is untested. -.br -.RE - -.B UBC -.RS -Uncovered Baseline Code (0 => 0): unchanged code was untested before, is untested now. -.br -.RE - -.B GBC -.RS -Gained Baseline Coverage (0 => 1): unchanged code is tested now. -.br -.RE - -.B GIC -.RS -Gained Included Coverage (# => 1): previously unused code is tested now. -.br -.RE - -.B GNC -.RS -Gained New Coverage (+ => 1): newly added code is tested. -.br -.RE - -.B CBC -.RS -Covered Baseline Code (1 => 1): unchanged code was tested before and is still tested. -.br -.RE - -.B EUB -.RS -Excluded Uncovered Baseline (0 => #): previously untested code is unused now. -.br -.RE - -.B ECB -.RS -Excluded Covered Baseline (1 => #): previously tested code is unused now. -.br -.RE - -.B DUB -.RS -Deleted Uncovered Baseline (0 => \-): previously untested code has been deleted. -.br - -Note: Because these lines are not represented in the current source version, -they are only represented in the classification summary table. -.RE - -.B DCB -.RS -Deleted Covered Baseline (1 => \-): previously tested code has been deleted. -.br - -Note: Because these lines are not represented in the current source version, -they are only represented in the classification summary table. -.br -.RE - -The differential coverage report colorizes categorized regions in the source code view using unique colors for each. You can use the -.B \-\-simplified\-colors -option to instead use one color for 'covered' code and another for 'uncovered'. - -.SS Date and owner binning - -.B "Date binning" -annotates coverage reports with age-of-last-change information to distinguish -recently added or modified code which has not been tested from older, presumed -stable code which is also not tested. -.B "Owner binning" -adds annotation identifying the author of changes. -.br - -Both age and ownership reporting can be used to enhance team efforts to maintain -good coverage discipline by spotlighting coverage shortfalls in recently -modified code, even in the absence of baseline coverage data. -.br - -To enable date and owner binning, the -.B \-\-annotate\-script -option must be used to specify a script that provides source code line age and -ownership information. -.br - -For each source line, age is the interval since the most recent modification date -and the owner is the user identity responsible for the most recent change to that line. -.br - -Line coverage overall totals and counts for each of the 12 classification categories are -collected for each of the specified age ranges (see the -.B \-\-date\-bins -option, below). - -.SS Script conventions - -Some -.B genhtml -options expect the name of an external script or tool as argument. These -scripts are then run as part of the associated function. This includes the -following options: - -.RS -.B \-\-annotate\-script -.br -.B \-\-context\-script -.br -.B \-\-criteria\-script -.br -.B \-\-history\-script -.br -.B \-\-resolve\-script -.br -.B \-\-select\-script -.br -.B \-\-simplify\-script -.br -.B \-\-unreachable\-script -.br -.B \-\-version\-script -.br -.RE - -While each script performs a separate function there are some common aspects -in the way these options are handled: - -.IP 1. 3 -If the callback script name ends in -.B \.pm -then the script is assumed to be a Perl module. -.br -A perl module may offer performance advantages over an external script, as it is compiled once and loaded into the interpreter and because it can load and maintain internal state. -.br -The module is expected to export a method 'new', which is -called with the script name and the script parameters (if any) as arguments. It is expected to return an object which implements several standard methods: -.br -.I $callback_obj = packagename\-\>new(perl_module_file, args); -.RS 3 -.IP version\-script 3 -.I $version = $callback_obj->extract_version($source_file_ename); -.br -.I $match = $callback_obj->check_version($old_version, $new_version, $source_file_name); -.br -.RS -.IP $match 3 - is expected to be 1 (true) if the version keys refer to the came file and 0 (false) otherwise. -.PP - -.IP $version 3 - is a string representing a unique identifier of the particular version of the file -.PP -.RE - -See example implementations -.I $LCOV_HOME/share/lcov/support-scripts/gitversion.pm -and -.I $LCOV_HOME/share/lcov/support-scripts/getp4version.pm. -.PP -.IP annotate\-script 3 -.I ($status, $array) = $callback_obj->annotate($source_file_name); -.br -.br -.br - -where -.RS -.IP $status 3 - is 0 if the command succeeded and nonzero otherwise. -.I $status -is interpreted in same way as the return code from 'system(..)' -.PP -.IP $array 3 -is a list of line data of the form: -.br -.I [$text, $abbrev, $full_name, $when, $changelist]. -.PP -.br - -and - -.IP $text 3 -is the source text from the corresponding line (without newline termination) -.PP -.IP $abbrev 3 -is the "abbreviated author name" responsible for this line of code. This is the name that will be used in the various HTML tables. For example, for brevity/readability, you may want to strip the domain from developers who are inside your organization. If there is no associated author, then the value should be -.I \"NONE\". -.PP -.IP $full_name 3 -is the "full author name" which is used in annotation tooltips. See the -.I genhtml_annotate_tooltip -entry in man -.B lcovrc(5). -.I $fullname -may be -.I undef -if the full name and abbreviated names are the same. -.PP -.IP $when 3 -is the timestamp associated with the most recent edit of the corresponding -line and may be -.I \"NONE\" -if there is no associated time. -.PP -.IP $changelist 3 -is the commit identifier associated with the most recent change to this line, or -.I \"NONE\" -if there isn't one. -.PP - - -See example implementations -.I $LCOV_HOME/share/lcov/support-scripts/gitblame.pm -and -.I $LCOV_HOME/share/lcov/support-scripts/p4annotate.pm. -.RE - -.IP context\-script -.I $hash = $callback_obj->context(); -.br -.br - -where -.I $hash -is a reference to a hash of key/value pairs which are meaningful to you. -This data is stored in the -.I profile -database. See the 'profile' section in man -.B lcovrc(5) -for more information. - -If your callback is not a perl module - for example, is a shellscript - then it should return a string such that the first word on each line is the key and the remainder is the associated data. If a key is repeated, then the corresponding data strings are concatenated, separated by newline. - -If you want to record only system information, then a shell callback is likely sufficient. If you want to record any tool-specific/internal information, then you will need to implement a perl module so that your callback will be able to access the information. -Note that the constructor of your -.I context-script -callback (or of any callback) can perform any additional actions which -are required - for example, to write additional files, to query or set -tool-specific information, -.I etc. -For example, the example implementation, below, has an option to append -comments to the generated .info file. - - -See the example implementation -.I $LCOV_HOME/share/lcov/support-scripts/context.pm. -.RE - - - -.IP criteria\-script -.I ($status, $array) = $callback_obj->check_criteria($obj_name, $type, $json); -.br -.br - -where -.RS -.IP $obj_name 3 -is the source file or directory name, or \"top\" of the object whose coverage criteria is being checked. -.PP -.IP $type 3 -is the object type - either -.I \"file\", \"directory\", or \"top\". -.PP -.IP $json 3 -is the coverage data associated with this object, in JSON format - see below. -.PP -.IP $status 3 -is the return status of the operation, interpreted the same way as the -.I annotate -callback status, described above. -.PP -.IP $array 3 -is a reference to a possibly empty list of strings which will be reported by genhtml. The strings are are expected to explain why the coverage criteria failed. -.PP - -See example implementations -.I $LCOV_HOME/share/lcov/support-scripts/criteria.pm. -.RE - -.IP history\-script -$cpu_seconds = $callback_obj->history($element_name) -.br -.br - -where -.I $cpu_seconds -is the predicted time taken to process -.I $element_name -or -.I undef -if there is no prediction/the element is unknown. - -.br -See the sample implementation -.RS -\*[scriptdir]/history.pm, -which uses the -.I "\-\-profile" -data generated by a previous -.B genhtml -execution to predict the time required this time. -.br -The prediction may improve load balancing - and thus improve overall -runtime performance ( -.I i.e., -because we won't be waiting for some "long pole" task to complete while -all other threads are idle. - -.PP - -.IP resolve\-script -$newpath = $callback_obj->resolve($source_file_name) -.br -.br - -where -.I $newpath -is the correct path to the indicated source file or -.I undef -if the source file is not found by the callback. -.PP - -.IP simplify\-script -$new_func_name = $callback_obj->simplify($orig_func_name) -.br -.br - -where -.I $new_func_name -is the function name which will appear in the function detail table and -.I $orig_func_name -is the (possibly demangled) function name found in the coverage DB. - -.br -Note that the modified name is only used in the "function detail" table -and does not modify information in the coveage DB. - -.PP - -.IP unreachable\-script -$data_changed = $callback_obj->exclude($type, $source, $summary, $testdata); -.br -.br - -where -.I $data_changed -is non-zero if coverage data was changed in the callback, -.I $type -is either \"branch\" or \"mcdc\", -.I $source -is a "ReadCurrentSource" object, -.I $summary -is the coverage summary across all testcases, and -.I $testdata -is the per-tescase coverage data. - -See the sample implementation -.RS -\*[scriptdir]/unreach.pm -.RE -for a simple example callback which uses source code annotations to -indicate branch expressions and/or MC/DC conditions which are excluded. -See the comment at the top of the file for script usage directions. - -More sophisticated unreachability analysis is easy to visualize. -For example, one could use reachability data from the compiler or another tool, rather than relying on user annotation. - -.br -Note that the -.I "\-\-unreachable\-script" -callback must be a Perl module. Unlike the other callbacks, generic scripts -are not supported. - - -.PP - -.RE - -.IP 2. 3 -The option may be specified as a single -.I split_char -separated string which is divided into words (see -.B man lcovrc(5) -), or as a list of arguments. -The resulting command line is passed -to a shell interpreter to be executed. -The command line includes the script path followed by optional additional parameters -separated by spaces. Care must be taken to provide proper quoting if script -path or any parameter contains spaces or shell special characters. -.br -Note that module callbacks must be called via the 'list' method: they cannot be called as an executable with a space-separated set of arguments. -.br -For convenience: your callback module may need to implement its own -'split_char' so that you can pass multiple parameters to your callback -without interacting with genhtml's split mechanism. -.PP - -.IP 3. 3 -If an option is specified multiple times, then the parameters are -.I not -split, but are simply concatenated to form the command line - see the examples, below. -.br -For simplicity and ease of understanding: your command line should -pass all arguments individually, or all as a comma-separated list - not a mix of the two. -.PP - -.IP 4. 3 -.B genhtml -passes any additional parameters specified via option arguments -between the script path and the parameters required by the script's function. -.br -.PP - -Example: -.br - -.RS -genhtml --annotate-script /bin/script.sh -.br - --annotate-script arg0 ... -.br - -results in the same callback as - -.br -genhtml --annotate-script "/bin/script.sh arg0" ... -.br - -or - -.br -genhtml --annotate-script /bin/script.sh,arg0 ... -.br - -Note that the first form is preferred. - -.RE - -The resulting -.B genhtml -callback executes the command line: -.br - -.RS -/bin/script.sh arg0 -.I source_file_name -.RE -.br - -Similarly -.br -.RS -genhtml --annotate-script -.I /bin/myMoodule.pm -.br - --annotate-script arg0 --annotate-script arg1 ... -.br - -or -.br -genhtml --annotate-script -.I /bin/myMoodule.pm,arg0,arg1 -.br - -.br -.RE - -result in -.B genhtml -executing -.br - -.RS -$annotateCallback = myModule->new(arg0, arg1); -.RE - -to initialize the class object - -.I arg0 -and -.I arg1 -passed as strings - and then to execute - -.RS -($status, $arrayRef) = $annotateCallback( -.I source_file_name -); -.RE - -to retrieve the annotation information. - -In contrast, the command -.br -.RS -genhtml --annotate-script -.I /bin/myMoodule.pm -.br - --annotate-script arg0,arg1 ... -.RE -would result in -.B genhtml -initializing the callback object via -.br - -.RS -$annotateCallback = myModule->new("arg0,arg1"); -.RE -where "arg0,arg1" is passed as single comma-separated string. - -Similarly, the command -.br -.RS -genhtml --annotate-script -.I /bin/myMoodule.pm,arg0 -.br - --annotate-script arg1 ... -.RE -would very likely result in an error when genhtml tries to find -a script called "/bin/mymodule.pm,arg0". - - -Note that multiple instances of each script may execute simultaneously if the -.B \-\-parallel -option was specified. Therefore each script must either be reentrant or should arrange for its own synchronization, if necessary. -.br -In particular, if your callback is implemented via a perl module: -.IP \- 3 -the class object associated with the module will initialized once (in the parent process) -.PP -.IP \- 3 -The callback will occur in the child process (possibly simultaneously with other child processes). -.PP -As a result: if your callback needs to pass data back to the parent, you will need to arrange a communication mechanism to do so. -.br - -.SS Callbacks and parallel execution - -Because callbacks may need to record data - -.I e.g., -for error reporting or action summaries in the presence of parallel execution - -.B genhtml (and -.B lcov and -.B geninfo -) can call certain optional callback methods: - -.IP \- 3 -.I $callback->start() -.br -is called when the child process begins execution. This method can be -used to capture initial state - -.I e.g., -to set the count of events in this child to zero. -This method is optional. -.PP - -.IP \- 3 -.I my $data = $callback->save() -.br -is called when processing is complete, just before the child process exits. -The scalar -.I $data -returned by your -.I $callback->save() -method -.I $callback->restore() -method when the child process is reaped. -.PP - -.IP \- 3 -.I $callback->restore($data) -.br -is called in the parent process when the child is reaped. -.I $data -is the data that was returned when your -.I $callback->save() -method was called in the child. (Serialization/deserialization has happened under the covers.) -.PP - -.IP \- 3 -.I $callback->finalize() -.br -is called in the parent process when all calculalations are complete -and the parent setting up to report final results. -This method is optional. -.br -Note that, unlike the other callback methods described in this section, -.I finalize() -is called in both parallel and serial execution contexts. -.PP - -Note that your callback must implement -.I $callback->restore() -if it implements -.I $callback->save(). -.I $callback->start() -and -.I $callback->finalize() -are optional: if they are implemented, then they will be called. - -These methods are available only for callbacks implemented a perl modules. -If you callback is implemented as an executable script (say) - then you -are free to implement parent/child data passing however you prefer. - - -.SS Additional considerations - -If the -.B \-\-criteria\-script -option is used, genhtml will use the referenced script to determine whether your coverage criteria have been met - and will return a non\-zero status and print a message if the criteria are not met. -.br - -The -.B \-\-version\-script -option is used to verify that the same/compatible source code versions are displayed as were used to capture coverage data, as well as to verify that the same source code was used to capture coverage information which is going to be merged and to verify that the source version used for filtering operations is compatible with the version used to generate the data. - -HTML output files are created in the current working directory unless the -.B \-\-output\-directory -option is used. If -.I tracefile -or -.I baseline\-file -ends with ".gz", it is assumed to be GZIP\-compressed and the gunzip tool -will be used to decompress it transparently. - -Note that all source code files have to be present and readable at the -exact file system location they were compiled, and all path references in the input data ".info" and "diff" files must match exactly (i.e., exact string match). -.br - -Further, the -.BR \-\-version\-script ", " \-\-annotate\-script ", and " \-\-criteria\-script " scripts " -use the same path strings. However, see the -.B \-\-substitute -and -.B \-\-resolve\-script -options for a mechanism to adjust extracted paths so they match your source and/or revision control layout. - -.br -You can use the -.BR check_exisitence_before_callback -configuration option to tell the tool to check that the file exists before -calling the -.BR \-\-version\-script -or -.BR \-\-annotate\-script -callback. See man -.B lcovrc(5) -for details. -.br - -.SS Additional options - -Use option -.B \-\-diff\-file -to supply a unified diff file that represents the changes to the source -code files between the version used to compile and capture the baseline -trace files, and the version used to compile and capture the current -trace files. - -Use option -.B \-\-css\-file -to modify layout and colors of the generated HTML output. Files are -marked in different colors depending on the associated coverage rate. -.br - -By default, the coverage limits for low, medium and high coverage are set to -0\-75%, 75\-90% and 90\-100% percent respectively. To change these -values, use configuration file options. -.br - -.RS -.IR genhtml_hi_limit " and " genhtml_med_limit -.RE -.br - -or type-specific limits: -.br - -.RS -.IR genhtml_line_hi_limit " and " genhtml_line_med_limit -.br -.IR genhtml_branch_hi_limit " and " genhtml_branch_med_limit -.br -.IR genhtml_function_hi_limit " and " genhtml_function_med_limit -.br -.RE - -See man -.B lcovrc(5) -for details. - -Also note that when displaying percentages, 0% and 100% are only printed when -the values are exactly 0% and 100% respectively. Other values which would -conventionally be rounded to 0% or 100% are instead printed as nearest -non\-boundary value. This behavior is in accordance with that of the -.BR gcov (1) -tool. - -By default, -.B genhtml -reports will include both line and function coverage data. -Neither branch or MC/DC data is displayed by default; you can use the -.B \-\-branch\-coverage -and -.B \-\-mcdc\-coverage -options to enable branch or MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate -settings to your personal, group, or site lcov configuration file. See the -.B branch_coverage -and -.B mcdc_coverage -sections of man -.B lcovrc(5) -for details. - - -.SH OPTIONS - -In general, (almost) all -.B genhtml -options can also be specified in your personal, group, project, or site -configuration file - see man -.B lcovrc(5) -for details. - - -.B \-h -.br -.B \-\-help -.RS -Print a short help text, then exit. - -.RE -.B \-\-version -.RS -Print version number, then exit. - -.RE -.B \-v -.br -.B \-\-verbose -.RS -Increment informational message verbosity. This is mainly used for script and/or flow debugging - e.g., to figure out which data files are found, where. -Also see the \-\-quiet flag. - -.RE -.B \-q -.br -.B \-\-quiet -.RS -Decrement informational message verbosity. - -Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. - -.RE -.B \-\-debug -.RS -Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. - -.RE -.B \-\-validate -.RS -Check the generated HTML to verify that there are no dead hyperlinks and no unused files in the output directory. -The checks can also be enabled by setting environment variable -.B LCOV_VALIDATE = 1. -This option is primarily intended for use by developers who modify the HTML report. - -.RE -.B \-\-flat -.br -.B \-\-hierarchical -.RS -Use the specified HTML report hierarchy layout. -.br - -The default HTML report is 3 levels: - -.RS 2 -.IP 1. 3 -.B top\-level: -table of all directories, -.PP - -.IP 2. 3 -.B directory: -table of source files in a directory, and -.PP - -.IP 3. 3 -.B source file detail: -annotated source code. -.PP -.RE - -Option -.B \-\-hierarchical -produces a multilevel report which follows the directory structure of the -source code (similar to the file tool in Microsoft Windows). - -Option -.B \-\-flat -produces a two-level HTML report: - -.RS 2 -.IP 1. 3 -.B top\-level: -table of all project source files, and -.PP - -.IP 2. 3 -.B source file detail: -annotated source code. -.PP -.RE - -The 'flat' view can reduce the number of clicks required to navigate around -the coverage report - but is unwieldy except for rather small projects consisting of only a few source files. It can be useful in 'code review' mode, even for very large projects (see the -.I \-\-select\-script -option). -.br -Most large projects follow a rational directory structure - which favors the 'hierarchical' report format. Teams responsible for a particular module can focus on a specific subdirectory or set of subdirectories. - -Only one of options -.B \-\-flat -or -.B \-\-hierarchical -can be specified at the same time. - -These options can also be persistently set via the lcovrc configuration file -using either: -.br - -.RS -.I genhtml_hierarchical -= 1 -.br -.RE - -or -.br - -.RS -.I genhtml_flat_view -= 1 -.br -.RE - -See man -.B lcovrc(5) -for details. - -.RE -.B \-f -.br -.B \-\-frames -.RS -Use HTML frames for source code view. - -If enabled, a frameset is created for each source code file, providing -an overview of the source code as a "clickable" image. Note that this -option will slow down output creation noticeably because each source -code character has to be inspected once. Note also that the GD.pm Perl -module has to be installed for this option to work (it may be obtained -from http://www.cpan.org). - -This option can also be controlled from the -.I genhtml_frames -entry of the -.B lcovrc -file. - -Please note that there is a bug in firefox and in chrome, such that -enabling frames will disable hyperlinks from the 'directory' level summary -table entry to the first line in the corresponding file in the particular -category - e.g., to the first 'MIS' line (vanilla coverage report - see the -.i \-\-show\-navigation -option, below), to -the first 'UNC' branch (differential coverage report), etc. -Hyperlinks from the summary table at the top of the 'source detail' page are not affected. - -.RE -.B \-s -.br -.B \-\-show\-details -.RS -Generate detailed directory view. - -When this option is enabled, -.B genhtml -generates two versions of each source file file entry in the corresponding summary table: -.IP -one containing the standard information plus a link to a -"detailed" version, and -.PP -.IP -a second which contains the number of coverpoints in the hit by each -testcase. -.br -Note that missed coverpoints are not shown in the per-testcase table entry data. -.PP - -The corresponding summary table is found on the 'directory' page of the default 3-level genthm report, or on the top-level page of the 'flat' report (see -.I genhtml \-\-flat ... -), or on the parent directory page of the 'hierarchical' report (see -.I genhtml \-\-hierarchical ... -). - -Note that this option may significantly increase memory consumption. - -.RE -.BI "\-b " baseline\-file\-pattern -.br -.BI "\-\-baseline\-file " baseline\-file\-pattern -.RS -Use data in the files found from glob pattern -.I baseline\-file\-pattern -as coverage baseline. - -.B \-\-baseline\-file -may be specified multiple times - for example, if you have multiple trace data files for each of several test suites and you do not want to go through the additional step of merging all of them into a single aggregated data file. - -The coverage data files specified by -.I baseline\-file\-pattern -is read and used as the baseline for classifying the change in coverage represented by the coverage counts in -.IR tracefile\-patterns . -If -.I baseline\-file\-pattern -is a directory, then genhtml will search the directory for all files ending in '.info'. -See the -.I info_file_extension -section in -.B man(5) lcovrc -for how to change this pattern. - -In general, you should specify a diff file in unified diff format via -.B \-\-diff\-file -when you specify a -.IR \-\-baseline\-file\-pattern . -Without a diff file, genhtml will assume that there are no source differences -between 'baseline' and 'current'. -For example: this might be used to find -incremental changes caused by the addition of more testcases, or to compare -coverage results between gcc versions, or between gcc and llvm. - -.RE -.BI "\-\-baseline\-title " title -.RS -Use -.I title -as the descriptive label text for the source of coverage baseline data. - -.RE -.BI "\-\-baseline\-date " date -.RS -Use -.I date -as the collection date in text format for the coverage baseline data. -If this argument is not specified, the default is to use the creation time of the first file matched by -.I baseline\-file\-pattern -as the baseline date. If there are multiple baseline files, then the creation date of the first file is used. - -.RE -.BI "\-\-current\-date " date -.RS -Use -.I date -as the collection date in text format for the coverage baseline data. -If this argument is not specified, the default is to use the creation time of the current -.IR tracefile . - -.RE -.BI "\-\-diff\-file " diff\-file -.RS -Use the -.I diff\-file -as the definition for source file changes between the sample points for -.I baseline\-file\-pattern -and -.IR tracefile(s) . -.br - - -Note: - -.IP - 3 -if filters are applied during the creation of a differential coverage report, -(see the -,I \-\-filter -section, below), then those filters will be applied to the -.I baseline coverage data -(see the -.I \-\-baseline\-file -section, above) as well as to the -.I current coverage data. -It is important that the -.I diff-file -accurately reflect all source code changes so that the baseline coverage data can be correctly filtered. -.PP - -.IP - 3 -Best practice is to use a -.I \-\-version\-script -callback to verify that source versions match before source-based filtering is applied. -.PP - -It is almost always a better idea to filter at capture or aggregate time - not at report generation. - -A suitable -.I \"universal diff\" -input file for the -.I \-\-diff\-file -option -can be generated using either the "p4udiff" or "gitdiff" sample scripts that are provided as part of this package, or by using revision control commands directly. - -The "p4udiff" or "gitdiff" sample scripts are found in: - -.RS -\*[scriptdir]/p4udiff -.br -.RE - -and - -.RS -\*[scriptdir]/gitdiff -.br -.RE - - -These scripts simply post\-process the 'p4' or 'git' output to (optionally) remove files that are not of interest and to explicitly note files which have not changed. - -.B p4udiff -accepts either a changelist ID or the literal string "sandbox"; "sandbox" indicates that there are modified files which have not been checked in. -See " -.I gitdiff \-\- help -" and " -.I p4udiff \-\- help -" for more information. - -It is useful to note unchanged files denoted by lines of the form: -.br - -.RS -diff [optional header strings] -.br -=== file_path -.RE -.br - -in the p4diff/gitdiff output as this knowledge will help to suppress spurious 'path mismatch' warnings. See the -.B \-\-elide\-path\-mismatch -and -.B \-\-build\-directory -entries, below. - -In general, you will specify -.B \-\-baseline\-file -when you specify -.BR \-\-diff\-file . -The -.I baseline_files -are used to compute coverage differences ( -.I e.g. -gains and losses) between the baseline and current, where the -.I diff_file -is used to compute code changes: source text is -identical between 'baseline' and 'current'. -If you specify -.I baseline_files -but no -.I diff_file, -the tool will assume that there are no code changes between baseline and current. -If you specify a -.I diff_file -but no -.I baseline_files, -the tool will assume that there is no baseline coverage data (no baseline code was covered); as result unchanged code ( -.I i.e., -which does not appear in the -.I diff_file -will be categorized as eiher GIC (covered) or UIC (not covered) while new or changed code will be categorized as either GNC or UNC. - -.RE -.BI "\-\-annotate\-script " script -.RS -Use -.I script -to get source code annotation data. - -Use this option to specify an external tool or command line that -.B genhtml -can use to obtain source code annotation data such as age and author of the last -change for each source code line. -.br - -This option also instructs -.B genhtml -to add a summary table to the HTML report header that shows counts in the various coverage categories, associated with each date bin. In addition, each source code line will show age and owner information. -Annotation data is also used to populate a 'tooltip' which appears when the mouse -hovers over the associated source code. See the -.I genhtml_annotate_tooltip -entry in man -.B lcovrc(5) -for details. -.br - -The specified -.I script -is expected to obtain age and ownership information -for each source code line from the revision management system and to output -this information in the format described below. -.br - -If the annotate script fails and annotation errors are ignored via -.BR --ignore-errors , -then -.B genhtml -will try to load the source file normally. If the file is not present or not readable, and the -.B \-\-synthesize\-missing -flag is specified, then -.B genhtml -will synthesize fake data for the file. -.br - -.B genhtml -will emit an error if you have specified an annotation script but no files are -successfully annotated (see below). -This can happen, for example, if your P4USER, P4CLIENT, -or P4PORT environment variables are not set correctly - -.I e.g. if the -Jenkins user who generates coverage reports is not the same and the user -who checked out the code and owns the sandbox. -.br - -Sample annotation scripts for Perforce ("p4annotate") and git ("gitblame") -are provided as part of this package in the following locations: -.br - -.RS -\*[scriptdir]/p4annotate -.br -.RE - -and -.br - -.RS -\*[scriptdir]/gitblame -.br -.RE - -Note that these scripts generate annotations from the file version checked in to the repository - not the locally modified file in the build directory. If you need annotations for locally modified files, you can shelve your changes in P4, or check them in to a local branch in git. - -.B "Creating your own script" -.br - -When creating your own script, please first see -.B "Script considerations" -above for general calling conventions and script requirements. -.br - -.I script -is called by genhtml with the following command line: - -.RS -.B script -.I "[additional_parameters] " source_file_name -.RE -.br - -where - -.RS -.B script -.br -.RS -is the script executable -.br -.RE - -.B additional_parameters -.br -.RS -includes any optional parameters specified (see -.B "Script conventions" -above) -.br -.RE - -.B source_file_name -.br -.RS -is the source code file name -.br -.RE -.RE - -The -.I script -executable should output a line to the standard output stream in the following format for each line in file -.IR source_file_name : -.br - -.RS -.IR commit_id | author_data | date | source_code -.br -.RE - -where - -.RS -.B commit_id -.br -.RS -is an ID identifying the last change to the line or NONE if this file is not -checked in to your revision control system. -.br -.B genhtml -counts the file as not 'successfully annotated' if -.B commit_id -is -.I NONE -and as 'successfully annotated' otherwise. -.br -.RE -.br - -.B author_data -.br -.RS -identifies the author of the last change. -.br -For backward compatibility with existing annotate-script implementations, -two -.I author_data -formats are supported: -.IP - 3 -.I string -: the string used as both the 'abbreviated name' (used as 'owner' name in -HTML output and callbacks) and as 'full name' (used in tooltip callbacks) -.PP -.IP - 3 -.I abbrev_string;full_name -: the -.I author_data -string contains both an 'abbreviated name' and a 'full name' - separated by a semicolon character (';'). -.br -This is useful when generating coverage reports for opensource software -components where there are many 'External' contributors who you do not want -to distinguish in 'owner' summary tables but you still want to know who the -actual author was. (See the -.B gitblame -callback script for an example.) -.PP -.br -.RE -.br - -.B date -.br -.RS -is the data of last change in W3CDTF format (--
T::) -.br -.RE -.br - -.B source_code -.br -.RS -is the line's source code -.br -.RE -.br -.RE - -The script should return 0 (zero) if processing was successful and non\-zero if it encountered an error. -.br - -.RE -.BI "\-\-criteria\-script " script -.RS -Use -.I script -to test for coverage acceptance criteria. -.br - -Use this option to specify an external tool or command line that -.B genhtml -can use to determine if coverage results meet custom acceptance criteria. -Criteria checking results are shown in the standard output log of -.BR genhtml . -If at least one check fails, -.B genhtml -will exit with a non-zero exit code after completing its processing. -.br - -A sample coverage criteria script is provided as part of this package in the -following location: - -.RS -\*[scriptdir]/criteria -.br -.RE - -The sample script checks that top\-level line coverage meets the criteria "UNC + LBC + UIC == 0" (added code and newly activated code must be tested, and existing tested code must not become untested). -.br - -As another example, it is possible to create scripts that mimic the -.B "lcov \-\-fail\-under\-lines" -feature by checking that the ratio of exercised lines to total lines ("(GNC + GIC + CBC) / (GNC + GIC + CBC + UNC + UIC + UBC)") is greater than the threshold - either only at the top level, in every directory, or wherever desired. Similarly, criteria may include branch and function coverage metrics. -.br - -By default the criteria script is called for all source code hierarchy levels, i.e.: top-level, directory, and file-level. The -.I criteria_callback_levels -configuration file option can be used to limit the hierarchy levels to any combination of 'top', 'directory', or 'file' levels. -.br - -Example: -.br - -.RS -genhtml --rc criteria_callback_levels=directory,top ... -.br -.RE - -You can increase the amount of data passed to the criteria script using -configuration file option -.IR criteria_callback_data . -By default, only total counts are included. Specifying "date" adds per -date-bin counts, "owner" adds per owner-bin counts. -.br - -Example: -.br - -.RS -genhtml --rc criteria_callback_data=date,owner ... -.br -.RE - -See man -.B lcovrc(5) -for more details. - -.B "Creating your own script" -.br - -When creating your own script, please first see -.B "Script considerations" -above for general calling conventions and script requirements. -.br - -.I script -is run with the following command line for each source code file, -leaf\-directory, and top-level coverage results: - -.RS -.B script -.I "[additional_parameters] " "name " " type" -.I "coverage_data" -.br -.RE - -where - -.RS -.B script -.br -.RS -is the script executable -.br -.RE - -.B additional_parameters -.br -.RS -includes any optional parameters specified (see -.B "Script conventions" -above) -.br -.RE - -.B name -.br -.RS -is the name of the object for which coverage criteria should be checked, -that is either the source code file name, directory name, or "top" if the -script is called for top-level data -.br -.RE - -.B type -.br -.RS -is the type of source code object for which coverage criteria should be -checked, that is one of "file", "directory", or "top" -.br -.RE - -.B coverage_data -.br -.RS -is either a coverage data hash or a JSON representation of coverage data hash of the corresponding source code -object. -If the callback is a Perl module, then the it is passes a hash object - other wise, it is passed a JSON representation of that data. -.br -.RE -.RE - -The JSON data format is defined as follows: -.br - -{ -.br - "": { -.br - "found": , -.br - "hit": , -.br - "": , -.br - ... -.br - }, -.br - "": { -.br - "" : { -.br - "found": , -.br - "hit": , -.br - "": , -.br - ... -.br - }, -.br - ... -.br - }, -.br - ... -.br -} -.br - -where - -.RS -.B type -.br -.RS -specifies the type of coverage as one of "line", "function", or "branch" -.br -.RE - -.B bin_type -.br -.RS -specifies the type of per-bin coverage as one of "line_age", "function_age", or "branch_age" for date-bin data, and "line_owners" or "branch_owners" for owner-bin data -.br -.RE - -.B bin_id -.br -.RS -specifies the date-bin index for date-bin data, and owner ID for owner-bin data. -.br -.RE - -.B found -.br -.RS -defines the number of found lines, functions, or branches -.br -.RE - -.B hit -.br -.RS -defines the number of hit lines, functions, or branches -.br -.RE - -.B category -.br -.RS -defines the number of lines, functions, or branches that fall in the specified -category (see -.B "Differential coverage" -above) -.br -.RE - -.RE - -Note that data is only reported for non-empty coverage types and bins. -.br - -The script should return 0 (zero) if the criteria are met and non\-zero otherwise. -.br - -If desired, it may print a single line output string which will be appended to the error log if the return status is non\-zero. Additionally, non\-empty lines are appended to the genhtml standard output log. -.br - -.RE - -.B \-\-version\-script -.I script -.br -.RS -Use -.I script -to get source code file version data. - -Use this option to specify an external tool or command line that -.B genhtml -can use to obtain a source code file's version ID when generating HTML or -applying source filters (see -.B \-\-filter -option). -.br - -A version ID can be a file hash or commit ID from revision control. It is used to check the version of the source file which is loaded against the version which was used to generate coverage data (i.e., the file version seen by lcov/geninfo). It is important that source code versions match - otherwise inconsistent or confusing results may be produced. -.br - -Version mismatches typically happen when the tasks of capture, aggregation, and report generation are split between multiple jobs - e.g., when the same source code is used in multiple projects, a unified/global coverage report is required, and the projects accidentally use different revisions. -.br - -If your .info (coverage data) file does not contain version information - for example, because it was generated by a tool which did not support versioning - then you can use the -.I compute_file_version " = 1" -config file option to generate the data afterward. A convenient way to do this might be to use -.B lcov -.I \-\-add\-tracefile -to read the original file, insert version information, and write out the result. -See man -.B lcovrc(5) -for more details. - - -Sample scripts for Perforce ("getp4version"), git ("gitversion") and using an md5 hash ("get_signature") are provided as part of this package in the following locations: -.br - -.RS -.I \*[scriptdir]/getp4version -.RE -.br - -.RS -.I \*[scriptdir]/gitversion -.RE -.br - -and -.br - -.RS -.I \*[scriptdir]/get_signature -.RE -.br - -Note that you must use the same script/same mechanism to determine the file version when you extract, merge, and display coverage data - otherwise, you may see spurious mismatch reports. -.br - -.B "Creating your own script" -.br - -When creating your own script, please first see -.B "Script considerations" -above for general calling conventions and script requirements. -.br - -.I "script " -is used both to generate and to compare the version ID to enable retaining history between calls or to do more complex processing to determine equivalence. -It will be called by -.B genhtml -with either of the following command lines: -.br - -1. Determine source file version ID -.br - -.RS -.BI script " source_file_name" -.RE -.br - -It should write the version ID of -.I " source_file_name " -to stdout and return a 0 exit status. -If the file is not versioned, it should write an empty string and return a 0 exit status. -.br - -2. Compare source file version IDs - -.RS -.B script \-\-compare -.I " source_file_name source_file_id" -.br -.I " info_file_id" -.br - -.RE -where -.RS -.br - -.B "source_file_name" -.RS -is the source code file name -.RE -.br - -.B "source_file_id " -.RS -is the version ID returned by calling "script source_file_name" -.RE -.br - -.B "info_file_id " -.RS -is the version ID found in the corresponding .info file -.RE -.RE -.br - -It should return non\-zero if the IDs do not match. -.br - -.RE - -.B \-\-resolve\-script -.I script -.br -.RS -Use -.I script -to find the file path for some source file which which appears in -an input data file if the file is not found after applying -.I \-\-substitute -patterns and searching the -.I \-\-source\-directory -list. This option is equivalent to the -.B resolve_script -config file option. See man -.B lcovrc(5) -for details. -.RE - -.B \-\-select\-script -.I callback -.br -.RS -Use -.I callback -to decide whether a particular source line is interesting and should be -included in the output data/generated report or not. - -This option is equivalent to the -.B select_script -config file option. See man -.B lcovrc(5) -for details. -.RE - -.B \-\-simplify\-script -.I callback -.br -.RS -Use -.I callback -to shorten/simplify long demangled C++ function and template names to make the function detail table more compact and readable - for example, to -remove nested namespace names. - -Note that the simplifications affect only the display and not the actual names -stored in the coverage DB. In particular, the DB name (not the simplified name) -is the one used to match -.I \-\-erase\-function -patterns. - -This option is equivalent to the -.B simplify_script -config file option. See man -.B lcovrc(5) -for details -.RE - -.B \-\-unreachable\-script -.I module -.br -.RS -Use -.I module -to decide whether particular branch expressions and/or MC/DC conditions -should be removed from the coverage report. -This option is equivalent to the -.B unreachable_script -config file option. See man -.B lcovrc(5) -for details. - -Note that -.I \"module\" -is required to be a Perl module. - -See the -.I "unreachable\-script" -discussion in the -.I \"Script conventions\" -section, above, and the -.I \"Exclusion markers\" -section in man -.B geninfo(1). - - -.RE - -.BI "\-\-checksum " -.RS -Specify whether to compare stored tracefile checksum to checksum computed from the source code. - -Checksum verification is -.B disabled -by default. - -When checksum verification is enabled, a checksum will be computed for each source -code line and compared to the checksum found in the 'current' tracefile. -This will help to prevent attempts to display source code which is not identical -to the code used to generate the coverage data. - -Note that this option is somewhat subsumed by the -.B \-\-version\-script -option - which does something similar, but at the 'whole file' level. - -.RE -.B \-\-fail\-under\-branches -.I percentage -.br -.RS -Use this option to tell genhtml to exit with a status of 1 if the total -branch coverage is less than -.I percentage. -See -.B man lcov(1) -for more details. - -.RE -.B \-\-fail\-under\-lines -.I percentage -.br -.RS -Use this option to tell genhtml to exit with a status of 1 if the total -line coverage is less than -.I percentage. -See -.B man lcov(1) -for more details. - - -.RE -.B \-\-new\-file\-as\-baseline -.RS -By default, when code is identified on source lines in the 'current' data which were not identified as code in the 'baseline' data, but the source text has not changed, their coverpoints are categorized as "included code": -.I GIC -or -.I UIC. -.br - -However, if the configuration of the coverage job has been recently changed to instrument additional files, then all un\-exercised coverpoints in those files will fall into the -.I GIC -category - which may cause certain coverage criteria checks to fail. -.br - -When this option is specified, genhtml pretends that the baseline data for the file is the same as the current data - so coverpoints are categorized as -.I CBC -or -.I UBC -which do not trigger the coverage criteria check. - -Please note that coverpoints in the file are re\-categorized only if: - -.RS -.IP \(bu 3 -There is no 'baseline' data for any coverpoint in this file, AND -.PP -.IP \(bu 3 -The file pre\-dates the baseline: the oldest line in the file is older than the 'baseline' data file (or the value specified by the -.B \-\-baseline\-date -option). -.PP -.RE - -.RE -.BI "\-\-elide\-path\-mismatch" -.RS -Differential categorization uses file pathnames to match coverage entries from the ".info" file with file difference entries in the unified\-diff\-file. If the entries are not identical, then categorization may be incorrect or strange. - -When paths do not match, genhtml will produce "path" error messages to tell you about the mismatches. - -If mismatches occur, the best solution is to fix the incorrect entries in the .info and/or unified\-diff\-file files. However, fixing these entries is not possible, then you can use this option to attempt to automatically work around them. -.br - -When this option is specified, genhtml will pretend that the unified\-diff\-file entry matches the .info file entries if: - -.RS -.IP \(bu 3 -the same path is found in both the 'baseline' and 'current' .info files, and -.PP -.IP \(bu 3 -the basename of the path in the .info file and the path in the unified\-diff\-file are the same, and -.PP -.IP \(bu 3 -there is only one unmatched unified\-diff\-file entry with that basename. -.PP -.RE - -See the -.B \-\-diff\-file -and -.B \-\-build\-directory -entries for a discussion of how to avoid spurious warnings and/or incorrect matches. - -.RE -.BI "\-\-synthesize\-missing" -.RS -Generate (fake) file content if source file does not exist. -This option can be used to work around otherwise fatal annotation errors. - -When generating annotated file content, -.B genhtml -assumes that the source was written 'now' (so age is zero), the author is -.I no.body -and the commit ID is -.I synthesized. -These names and ages will appear in your HTML reports. - -.br -This option is equivalent config file -.I genhtml_synthesize_missing -parameter; see man -.B lcovrc(5) -for details. - - -.RE -.BI "\-\-date\-bins " day[,day,...] -.RS -The -.B \-\-date\-bins -option is used to specify age boundaries (cutpoints) for date\-binning classification. Each -.I age -element is expected to be an integer number of days prior to today (or prior to your SOURCE_DATE_EPOCH environment variable, if set). If -.I \-\-date\-bins is not specified, the default is to use 4 age ranges: less than 7 days, 7 to 30 days, 30 to 180 days, and more than 180 days. -This option is equivalent to the -.I genhtml_date_bins -config file option. See man -.B lcovrc(5). - -This argument has no effect if there is no -.I source\-annotation\-script . - -.RE -.BI "\-\-date\-labels " string[,string,...] -.RS -The -.B \-\-date\-labels -option is used to specify labels used for the 'date\-bin' table entries in the HTML report. -.br -The number of labels should be one greater than the number of cutpoints. -.br -If not specified, the default is to use label strings which specify the -.I [from ..to) -range of ages held by the corresponding bin. - -One possible use of this option is to use release names in the tables - -.I i.e., -to indicate the release in which each particular line first appeared. - -This option is equivalent to the -.I genhtml_date_labels -config file option. See man -.B lcovrc(5). - -This argument has no effect if there is no -.I source\-annotation\-script . - -.RE -.BI "\-\-show\-owners " [all] -.RS -If the -.B \-\-show\-owners -option is used, each coverage report header report contain a summary table, showing counts in the various coverage categories for everyone who appears in the revision control annotation as the most recent editor of the corresponding line. If the optional argument 'all' is not specified, the table will show only users who are responsible for un\-exercised code lines. If the optional argument is specified, then users responsible for any code lines will appear. In both cases, users who are responsible for non\-code lines (e.g, comments) are not shown. -This option does nothing if -.B \-\-annotate\-script -is not used; it needs revision control information provided by calling the script. - -Please note: if the -.I all -option is not specified, the summary table will contain "Total" rows for all date/owner bins which are not empty - but there will be no secondary "File/Directory" entries for elements which have no "missed" coverpoints. - -.br -This option is equivalent config file -.I genhtml_show_owner_table -parameter; see man -.B lcovrc(5) -for details. - -The lcovrc controls -.I owner_table_entries -and -.I truncate_owner_table -can be used to improve readability by limiting the number of authors who are displayed in the table -when the author number is large. -For example, if your configuration is: -.RS -.PP -.I owner_table_entries = 5 -.IP -.PP -.I truncate_owner_table = top,directory -.PP -.RE -then the owner table displayed at the top- and directory-levels will be truncated while the table shown at the 'file' level will display the full list. - -See man -.B lcovrc(5) -for details. - - -.RE -.BI "\-\-show\-noncode " -.RS -By default, the source code detail view does not show owner or date annotations in the far-left column for non\-code lines (e.g., comments). If the -.B \-\-show\-noncode -option is used, then the source code view will show annotations for both code and non\-code lines. -This argument has no effect if there is no -.I source\-annotation\-script . - -.br -This option is equivalent config file -.I genhtml_show_noncode_owners -parameter; see man -.B lcovrc(5) -for details. - - -.RE -.BI "\-\-show\-zero\-columns " -.RS -By default, columns whose entries are all zero are removed (not shown) in the summary table at the top of each HTML page. -If the -.B \-\-show\-zero\-columns -option is used, then those columns will be shown. - -When columns are retained, then all the tables have the same width/contain the same number of columns - which may be a benefit in some situations. - -When columns are removed, then the tables are more compact and easier to read. -This is especially true in relatively mature development environments, when there are very few un-exercised coverpoints in the project. - -.RE -.BI "\-\-show\-navigation " -.RS -By default, the summary table in the source code detail view does not contain hyperlinks from the number to the first line in the corresponding category ('Hit' or 'Missed') and from the current location to the next location in the current category, in non-differential coverage reports. (This is the lcov 'legacy' view non-differential reports.) - -If the -.B \-\-show\-navigation -option is used, then the source code summary table will be generated with navigation links. -Hyperlinks are always generated for differential coverage reports. - -This feature enables developers to find and understand coverage issues more quickly than they might otherwise, if they had to rely on scrolling. - -See the -.I \-\-frames -description above for a description of a browser bug which disables -these hyperlinks in certain conditions. - -Navigation hyperlinks are always enabled in differential coveage report. - -.RE -.BI "\-\-show\-proportions " -.RS -In the 'function coverage detail' table, also show the percentage of lines and branches within the function which are exercised. - -This feature enables developers to focus attention on functions which have the largest effect on overall code coverage. - -This feature is disabled by default. -Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the -.BI derive_function_end_line -discussion in man -.B lcovrc(5). - - -.RE -.BI "\-\-simplified\-colors " -.RS -By default, each differential category is colorized uniquely in the source code detail view. With this option, only two colors are used: one for covered code and another for uncovered code. Note that ECB and EUB code is neither covered nor uncovered - and so may be difficult to distinguish in the source code view, as they will be presented in normal background color. - -.RE -.BI "\-\-exclude " -.I pattern -.RS -pattern is a glob\-match pattern of filenames to exclude from the report. -Files which do NOT match will be included. -See the lcov man page for details. - -.RE -.BI "\-\-include " -.I pattern -.RS -pattern is a glob\-match pattern of filenames to include in processing. -Files which do not match will be excluded from the report. -See the lcov man page for details. -.RE - -.B \-\-erase\-functions -.I regexp -.br -.RS -Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the -.B \-\-demangle\-cpp -option is used or not. - -Note that this option requires that you use a compiler version which is new enough to support function begin/end line reports or that you configure the tool to derive the required data - see the -.BI derive_function_end_line -discussion in man -.B lcovrc(5). -.RE - -.B \-\-substitute -.I regexp_pattern -.br -.RS -Apply Perl regexp -.IR regexp_pattern -to source file names found during processing. This is useful when some file paths in the baseline or current .info file do not match your source layout and so the source code is not found. -See the lcov man page for more details. - -Note that the substitution patterns are applied to the -.IR \-\-diff\-file -entries as well as the baseline and current .info files. -.RE - -.B \-\-omit\-lines -.I regexp_pattern -.br -.RS -Exclude coverage data from lines whose content matches -.IR regexp . - -Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (e.g., some complicated macro). -See the lcov man page for details. - -.RE -.BI "\-\-parallel " -.I [ integer ] -.br -.BI "\-j " -.I [ integer ] -.RS -Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). -.br -Also see the -.I memory, memory_percentage, max_fork_fails -and -.I fork_fail_timeout -entries in man -.B lcovrc(5). -.br -A previously generated execution profile may help to enable better utilization -and faster parallel execution. See the -.I "\-\-profile" -and -.I "\-\-history\-script" -sections of this man page. - - -.RE -.BI "\-\-memory " -.I integer -.RS -Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. - -This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does not know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. - -The configuration file -.I memory_percentage -option provided another way to set the maximum memory consumption. -See man -.B lcovrc (5) -for details. - - -.RE -.BI \-\-filter " filters" -.RS -Specify a list of coverpoint filters to apply to input data. - -Note that certain filters apply only to C/C++ source files. -.B genhtml -associates the file extension ('.c', '.vhd', -.I etc. -) with its source language. See the -.I c_file_extentions -and -.I rtl_file_extensions -sections of man -.B lcovrc(5) -for a description of the default associations and how they can be changed. - -Note that filters are applied to both 'branch' and 'MC/DC' coverpoints, -where appropriate: if a particular filter would remove some branch, -then it will also remove corresponding MC/DC coverpoints - for example, -.I "\-\-filter branch" -will remove MC/DC coverpoints if there is no conditional expression on the -corresponding line, and -.I "\-\-filter branch_region" -will remove both branch and MC/DC coverpoints in the marked region. - -Most filters need the source code; filters are not applied if the source file is not available. Similarly, for each source file, if the version recorded in the coverage data (the '.info' file) -does not match the version found on the filesystem, then a -.I version -error is reported. If the -.I version -error is ignored, then filtering is not applied to the mismatched file. -See the -.I \-\-version\-script -for more information. - -.I filters -can be a comma\-separated list of the following keywords: - -.IP branch: 3 -ignore branch counts for C/C++ source code lines which do not appear to contain conditionals. These may be generated automatically by the compiler (e.g., from C++ exception handling) - and are not interesting to users. -This option has no effect unless -.B \-\-branch\-coverage -is used. - -See also man -.B lcovrc(5) -- which describes several variables which affect branch filtering: -.I filter_lookahead -and -.I filter_bitwise_conditional. - -The most common use for branch filtering is to remove compiler-generated branches related to C++ exception handlers. See the no_exception_branch' option in man -.B lcovrc(5) -for a way to remove all identified exception branches. -.PP - -.IP brace: 3 -ignore line coverage counts on the closing brace of C/C++ code block, if the line contains only a closing brace and the preceding line has the same count or if the close brace has a zero count and either the preceding line has a non\-zero count, or the close brace is not the body of a conditional. - -These lines seem to appear and disappear in gcov output - and cause differential coverage to report bogus LBC and/or GIC and/or UIC counts. Bogus LBC or UIC counts are a problem because an automated regression which uses pass criteria "LBC + UIC + UNC == 0" will fail. -.PP - -.IP blank: 3 -ignore lines which contain only whitespace (or whitespace + comments) whose 'hit' count is zero. These appear to be a 'gcov' artifact related to compiler-generated code - such as exception handlers and destructor calls at the end of scope - and can confuse differential coverage criteria. -.br -If lcovrc option -.I filter_blank_aggressive = 1 -is enabled, then blank lines will be ignored whether their 'hit' count is zero or not. Aggressive filtering may be useful in LLVM-generated coverage data, which tends to include large numbers of such lines. -.PP - -.IP directive: 3 -ignore lines which look like C compiler directives: #ifdef, #include, #define, -.I etc. -These lines are sometimes included by -.I llvm\-cov -when LLVM profile data is translated to LCOV format. -.PP - -.IP exception: 3 -Exclude branches related to C++ exception handling from branch coverage. -Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data. -See the -.I no_exception_branch -section of -.B man lcovrc(5). - -.IP initializer: 3 -Exclude lines which appear to be part of a C++ std::initializer_list. -.PP - -.IP line: 3 -alias for "\-\-filter brace,blank". -.PP - -.IP mcdc: 3 -Remove MC/DC coverpoint which contains single expression, if 'branch' coverpoint -is present on the same line. -Singe-element MC/DC coverpoints are identical to the corresponding branch - except -in the case of compile-time expression evaluation, for example, in a template -function. - -.IP orphan: 3 -Remove branches which appear by themselves - -.I i.e., -the branch has only one destination and so cannot be a conditional. -.br -These occur most frequently as a result of exception branch filtering. - -.IP range: 3 -Ignore line and branch coverpoints on lines which are out-of range/whose line number is beyond the end of the source file. These appear to be gcov artifacts caused by a macro instantiation on the last line of the file. -.PP - -.IP region: 3 -apply LCOV_EXCL_START/LCOV_EXCL_STOP/LCOV_EXCL_LINE and LCOV_UNREACHABLE_START/LCOV_UNREACHABLE_STOP/LCOV_UNREACHABLE_LINE directives found in source text to the coverpoints found in the current and baseline .info files. -This option may be useful in cases that the source code was not found during 'lcov \-\-capture ...' but is accessible now. -.PP - -.IP branch_region: 3 -apply LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP/LCOV_EXCL_BR_LINE directives found in source text to the coverpoints found in the current and baseline .info files. -This is similar to the 'region option, above - but applies to branch coverpoints only. -.PP - -.IP function: 3 -combine data for every "unique" function which is defined at the same file/line. -.I geninfo/gcov -seem to have a bug such that they create multiple entries for the same function. -This feature also merges all instances of the same template function/template method. -.PP - -.IP trivial: 3 -remove trivial functions and associated coverpoints. 'Trivial' functions are -whose body is empty/do not contain any statements. Commonly, these include compiler-generated methods (e.g., default constructors and assignment operators) as well as static initialization wrappers, etc. - -Note that the -.I trivial -filter requires function end line information - and so requires that you use a compiler version which is new enough to support begin/end line reports -( -.I e.g., -gcc/9 or newer) or that you enable lcov/genhtml/geninfo to derive the information: - -In man -.B lcovrc(5), -see the -.I derive_function_end_line -setting as well as the -.I trivial_function_threshold -setting. The former is used to turn end line calculation on or off, -and the latter to change the lookahead used to determine whether the -function body is empty. -Also see the -.I lcov_filter_parallel -and -.I lcov_filter_chunk_size -settings, which may improve CPU performance if the number of files to process is very large. -.PP - -.RE -.BI "\-o " output\-directory -.br -.BI "\-\-output\-directory " output\-directory -.RS -Create files in -.I output\-directory. - -Use this option to tell -.B genhtml -to write the resulting files to a directory other than -the current one. If -.I output\-directory -does not exist, it will be created. - -It is advisable to use this option since depending on the -project size, a lot of files and subdirectories may be created. - -.RE -.BI "\-t " title -.br -.BI "\-\-title " title -.RS -Display -.I title -in header table of all pages. - -.I title -is written to the "Test:"-field in the header table at the top of each -generated HTML page to identify the context in which a particular output -was created. By default, this is the name of the 'current; tracefile. - -A common use is to specify a test run name, or a version control system -identifier (perforce changelist or git SHA, for example) that indicates -the code level that was tested. - -.RE -.BI "\-\-header\-title " BANNER -.RS -Display -.I BANNER -in header of all pages. - -.I BANNER -is written to the header portion of each generated HTML page. -By default, this -simply identifies this as an LCOV (differential) coverage report. - -A common use is to specify the name of the project or project branch and the -Jenkins build ID. - -.RE -.BI "\-\-footer " FOOTER -.RS -Display -.I FOOTER -in footer of all pages. - -.I FOOTER -is written to the footer portion of each generated HTML page. -The default simply identifies the LCOV tool version used to generate the report. - -.RE -.BI "\-d " description\-file -.br -.BI "\-\-description\-file " description\-file -.RS -Read test case descriptions from -.IR description\-file . - -All test case descriptions found in -.I description\-file -and referenced in the input data file are read and written to an extra page -which is then incorporated into the HTML output. - -The file format of -.IR "description\-file " is: - -for each test case: -.RS -TN: -.br -TD: - -.RE - -Valid test case names can consist of letters, numbers and the underscore -character ('_'). -.RE -.br - -.B \-k -.br -.B \-\-keep\-descriptions -.RS -Do not remove unused test descriptions. - -Keep descriptions found in the description file even if the coverage data -indicates that the associated test case did not cover any lines of code. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_keep_descriptions . - -.RE -.BI "\-c " css\-file -.br -.BI "\-\-css\-file " css\-file -.RS -Use external style sheet file -.IR css\-file . - -Using this option, an extra .css file may be specified which will replace -the default one. This may be helpful if the default colors make your eyes want -to jump out of their sockets :) - -This option can also be configured permanently using the configuration file -option -.IR genhtml_css_file . - -.RE -.BI "\-\-build\-directory " dirname -.RS -To support 'linked build directory' structures, add 'dirname' to the list of -places to search for soft links to source files - -.I e.g., -to handle the case that the links point to source files which are held in your -revision control system, and appear in the -.I \-\-diff\-file -data. In this use case, paths in the coverage data very likely refer to the -structure seen by the compiler during the build - so resolving them back to -the corresponding revsion-controlled source structure is likely to be successful. -.br - -Look in -.I dirname -for file paths which appear in -.IR tracefile -\- possibly after substitutions have been applied \- -which are soft links. -Both the original file path and the path to the linked file will resolve to the same -.I \-\-diff\-file entry. - -This option can be specified multiple times, to add more directories to the search path. - - -.RE -.BI "\-\-source\-directory " dirname -.RS -Add 'dirname' to the list of places to look for source files. -.br - -For relative source file paths -.I e.g. -paths found in -.IR tracefile, -or in -.IR diff-file -\- possibly after substitutions have been applied - -.B genhtml -will first look for the path from 'cwd' (where genhtml was -invoked) and -then from each alternate directory name in the order specified. -The first location matching location is used. - -This option can be specified multiple times, to add more directories to the source search path. - - -.RE -.BI "\-p " prefix -.br -.BI "\-\-prefix " prefix -.RS -Remove -.I prefix -from all directory names. - -Because lists containing long filenames are difficult to read, there is a -mechanism implemented that will automatically try to shorten all directory -names on the overview page beginning with a common prefix. By default, -this is done using an algorithm that tries to find the prefix which, when -applied, will minimize the resulting sum of characters of all directory -names. - -Use this option to specify the prefix to be removed by yourself. - -.RE -.B \-\-no\-prefix -.RS -Do not remove prefix from directory names. - -This switch will completely disable the prefix mechanism described in the -previous section. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_no_prefix . - -.RE -.B \-\-no\-source -.RS -Do not create source code view. - -Use this switch if you don't want to get a source code view for each file. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_no_source . - -.RE -.B \-\-no\-html -.RS -Do not create HTML report. - -Use this switch if you want some artifact of coverage report generation - -.I e.g., -the coverage criteria check or the serialized coverage DB, -.B etc. -- but do not need the coverage report HTML itself. - - -.RE -.BI "\-\-num\-spaces " spaces -.RS -Change appearance of tabs in source view according to -.IR spaces . - -When set to 0, tabs and their behaviour will be the browser's default. -.br -Negative values will set the rendered width in the source view to -.I spaces -spaces. -.br -Positive values will replace tabs with -.I spaces -spaces. - -Default value is 8. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_num_spaces . - -.RE -.B \-\-highlight -.RS -Highlight lines with converted\-only coverage data. - -Use this option in conjunction with the -.B \-\-diff -option of -.B lcov -to highlight those lines which were only covered in data sets which were -converted from previous source code versions. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_highlight . - -.RE -.B \-\-legend -.RS -Include color legend in HTML output. - -Use this option to include a legend explaining the meaning of color coding -in the resulting HTML output. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_legend . - -.RE -.BI "\-\-html\-prolog " prolog\-file -.RS -Read customized HTML prolog from -.IR prolog\-file . - -Use this option to replace the default HTML prolog (the initial part of the -HTML source code leading up to and including the tag) with the contents -of -.IR prolog\-file . -Within the prolog text, the following words will be replaced when a page is generated: - -.B "@pagetitle@" -.br -The title of the page. - -.B "@basedir@" -.br -A relative path leading to the base directory (e.g., for locating css\-files). - -This option can also be configured permanently using the configuration file -option -.IR genhtml_html_prolog . - -.RE -.BI "\-\-html\-epilog " epilog\-file -.RS -Read customized HTML epilog from -.IR epilog\-file . - -Use this option to replace the default HTML epilog (the final part of the HTML -source including ) with the contents of -.IR epilog\-file . - -Within the epilog text, the following words will be replaced when a page is generated: - -.B "@basedir@" -.br -A relative path leading to the base directory (e.g., for locating css\-files). - -This option can also be configured permanently using the configuration file -option -.IR genhtml_html_epilog . - -.RE -.BI "\-\-html\-extension " extension -.RS -Use customized filename extension for generated HTML pages. - -This option is useful in situations where different filename extensions -are required to render the resulting pages correctly (e.g., php). Note that -a '.' will be inserted between the filename and the extension specified by -this option. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_html_extension . -.RE - -.B \-\-html\-gzip -.RS -Compress all generated html files with gzip and add a .htaccess file specifying -gzip\-encoding in the root output directory. - -Use this option if you want to save space on your webserver. Requires a -webserver with .htaccess support and a browser with support for gzip -compressed html. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_html_gzip . - -.RE -.B \-\-sort-tables -.br -.B \-\-no\-sort -.RS -Specify whether to include sorted views of file and directory overviews. - -Use -.B \-\-sort-tables -to include sorted views or -.B \-\-no\-sort -to not include them. -Sorted views are -.B enabled -by default. - -When sorted views are enabled, each overview page will contain links to -views of that page sorted by coverage rate. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_sort . - -.RE -.B \-\-function\-coverage -.br -.B \-\-no\-function\-coverage -.RS -Specify whether to display function coverage summaries in HTML output. - -Use \-\-function\-coverage to enable function coverage summaries or -\-\-no\-function\-coverage to disable it. Function coverage summaries are -.B enabled -by default. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_function_coverage . - -When function coverage summaries are enabled, each overview page will contain -the number of functions found and hit per file or directory, together with -the resulting coverage rate. In addition, each source code view will contain -a link to a page which lists all functions found in that file plus the -respective call count for those functions. -The function coverage page groups the data for every alias of each function, sorted by name or execution count. The representative name of the group of functions is the shorted (i.e., containing the fewest characters). - -If using differential coverage and a sufficiently recent compiler version which report both begin and end line of functions ( -.I e.g., -gcc/9 and newer), functions are considered 'new' if any of their source lines have changed. -With older compiler versions, functions are considered 'new' if the function signature has changed or if the entire function is new. - -.RE -.B \-\-branch\-coverage -.br -.B \-\-no\-branch\-coverage -.RS -Specify whether to display branch coverage data in HTML output. - -Use -.B \-\-branch\-coverage -to enable branch coverage display or -.B \-\-no\-branch\-coverage -to disable it. Branch coverage data display is -.B disabled -by default. - -When branch coverage display is enabled, each overview page will contain -the number of branches found and hit per file or directory, together with -the resulting coverage rate. In addition, each source code view will contain -an extra column which lists all branches of a line with indications of -whether the branch was taken or not. Branches are shown in the following format: - - ' + ': Branch was taken at least once -.br - ' - ': Branch was not taken -.br - ' # ': The basic block containing the branch was never executed -.br - -Note that it might not always be possible to relate branches to the -corresponding source code statements: during compilation, GCC might shuffle -branches around or eliminate some of them to generate better code. - -This option can also be configured permanently using the configuration file -option -.IR branch_coverage . - -.RE - -.B \-\-mcdc\-coverage -.RS -Specify whether to display Modifie Condition / Decision Coverage (MC/DC) -data in HTML output. - -MC/DC data display is -.B disabled -by default. - -MC/DC coverage is supported for GCC versions 14.2 and higher, or -LLVM 18.1 and higher. -.br -See -.I llvm2lcov \-\-help -for details on MC/DC data capture in LLVM. - -When MC/DC display is enabled, each overview page will contain -the number of MC/DC expressions found and hit per file or directory - two senses per expression - together with -the resulting coverage rate. In addition, each source code view will contain -an extra column which lists all expressions and condition senses of a line with indications of -whether the condition was sensitized or not. Conditions are shown in the following format: - -.RS 3 -.IP T: 3 -True sense of subexpression was sensitized: if this subexpression's value had been false, then the condition result would have been different. -.IP t: 3 -True sense of subexpression was -.B not -sensitized: the condition result would not change if the subexpression value was different. -.IP F: -False sense of subexpression was sensitized: if this subexpression's value had been true, then the condition result would have been different. -.IP f: -False sense of subexpression was -.B not -sensitized: the condition result would not change if the subexpression value was different. -.RE - -Note that branch and MC/DC coverage are identical if the condition is -a simple expression - -.I e.g., -.RS 3 - if (enable) ... -.RE - -Note that, where appropriate, filters are applied to both 'branch' and 'MC/DC' coverpoints: if a particular filter would remove some branch, -then it will also remove corresponding MC/DC coverpoints. See the -.I \-\-filter -section, above. - -This option can also be configured permanently using the configuration file -option -.IR mcdc_coverage . -See man -.B lcovrc(5) . - -Note that MC/DC coverpoints are defined differently by GCC and LLVM. -.IP GCC: 3 -evaluates the sensitivity of the condition to the 'true' and 'false' sense of each constituent (leaf) expression independently. -.br -That is: it evaluates the question: does the result of the condition change if -.I this -constituent expression changed from true to false (termed the 'true' sense, above) or from false to true (termed the 'false' sens, above). -.br -For example, the expression -.I A || B -is sensitive to -.I A==true -when -.I B==false, -but is is not sensitive to -.I A==true -when -.I B==true. - -.IP LLVM: 3 -records the subexpression as covered if and only if there is a pair of evaluations -of the condition such that the condition was -sensitized for both 'true' and 'false' values of the subexpression. -This is defined as an -.I independence pair -in the LLVM documentation. -.PP - -That is: the testcase must sensitize both values in order to be marked covered by -LLVM, whereas GCC will independently mark each. -Consequently: in LLVM-generated -.B lcov -reports, either both 'true' and 'false' sensitizations will be covered, or neither will be. -.br -See the examples in tesctcase -.I .../tests/lcov/mcdc. - - - -.RE -.BI "\-\-demangle\-cpp " [param] -.RS -Specify whether to demangle C++ function names. - -Use this option if you want to convert C++ internal function names to -human readable format for display on the HTML function overview page. - -If called with no parameters, genhtml will use -.I c++filt -for demangling. This requires that the c++filt tool is installed (see -.BR c++filt (1)). - -If -.I param -is specified, it is treated as th tool to call to demangle source code. -The -.I \-\-demangle\-cpp -option can be used multiple times to specify the demangling tool and a set of -command line options that are passed to the tool - similar to how the gcc -.I -Xlinker -parameter works. In that case, you callback will be executed as: -.I | demangle_param0 demangle_param1 ... -Note that the demangle tool is called as a pipe and is expected to read from stdin and write to stdout. - -.RE -.B \-\-msg\-log -.I [ log_file_name ] -.br -.RS -Specify location to store error and warning messages (in addition to writing to STDERR). -If -.I log_file_name -is not specified, then default location is used. -.RE - -.RE -.B \-\-ignore\-errors -.I errors -.br -.RS -Specify a list of errors after which to continue processing. - -Use this option to specify a list of error classes after which -.B genhtml -should continue processing with a warning message instead of aborting. -To suppress the warning message, specify the error class twice. -.br - -.I errors -can be a comma\-separated list of the following keywords: - -.IP annotate: 3 -.B \-\-annotate\-script -returned non\-zero exit status - likely a file path or related error. HTML source code display will not be correct and ownership/date information may be missing. -.PP - -.IP branch: 3 -Branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. -.PP - -.IP callback: 3 -Annotate, version, or criteria script error. -.PP - -.IP category: 3 -Line number categorizations are incorrect in the .info file, so branch coverage line number turns out to not be an executable source line. -.PP - -.IP child: 3 -child process returned non-zero exit code during -.I \-\-parallel -execution. This typically indicates that the child encountered an error: see the log file immediately above this message. -In contrast: the -.B parallel -error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. -.PP - -.IP count: 3 -An excessive number of messages of some class has been reported - subsequent messages of that type will be suppressed. -The limit can be controlled by the 'max_message_count' variable. See man -.B lcovrc(5). -.PP - -.IP corrupt: 3 -Corrupt/unreadable coverage data file found. -.PP - -.IP deprecated: 3 -You are using a deprecated option. -This option will be removed in an upcoming release - so you should change your -scripts now. -.PP - -.IP empty: 3 -The patch file specified by the -.B \-\-diff\-file -argument does not contain any differences. This may be OK if there were no source code changes between 'baseline' and 'current' (e.g., the only change was to modify a Makefile) - or may indicate an unsupported file format. -.PP - -.IP excessive: 3 -your coverage data contains a suspiciously large 'hit' count which is unlikely -to be correct - possibly indicating a bug in your toolchain. -See the -.I excessive_count_threshold -section in man -.B lcorc(5) -for details. -.PP - -.IP fork: 3 -Unable to create child process during -.I \-\-parallel -execution. -.br -If the message is ignored ( -.I \-\-ignore\-errors fork -), then genhtml -will wait a brief period and then retry the failed execution. -.br -If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. - -.PP - -.IP format: 3 -Unexpected syntax or value found in .info file - for example, negative number or -zero line number encountered. - -.PP - -.IP inconsistent: 3 -This error indicates that your coverage data is internally inconsistent: it makes two or more mutually exclusive claims. For example: -.RS -.IP \- 3 -Files have been moved or repository history presented by -.B \-\-diff\-file -data is not consistent with coverage data; for example, an 'inserted' line has baseline coverage data. These issues are likely to be caused by inconsistent handling in the 'diff' data compared to the 'baseline' and 'current' coverage data (e.g., using different source versions to collect the data but incorrectly annotating those differences), or by inconsistent treatment in the 'annotate' script. -Consider using a -.B \-\-version\-script -to guard against version mismatches. -.PP -.IP \- 3 -Two or more -.B gcov -data files or -.B lcov -".info" files report different end lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch. -.br -In this context, if the -.I "inconsistent" -error is ignored, then the tool will record the largest number as the function end line. -.PP -.IP \- 3 -Two or more -.B gcov -data files or -.B lcov -".info" files report different start lines for the same function. This is likely due either to a gcc/gcov bug or to a source version mismatch. -.br -In this context, if the -.I "inconsistent" -error is ignored, then the tool will retain only the first function definition that it saw. -.PP -.IP \- 3 -Mismatched function declaration/alias records encountered: -.RS 3 -.IP "(backward compatible LCOV format)" 3 -function execution count record ( -.I FNDA -) without matching function declaration record ( -.I FN -). -.PP -.IP "(enhanced LCOV format)" 3 -function alias record ( -.I FNA -) without matching function declaration record ( -.I FLN -). -.PP -.RE -.PP -.IP \- 3 -branch expression (3rd field in the .info file 'BRDA' entry) of merge data does not match - -.br -If the error is ignored, the offending record is skipped. -.RE -.PP - -.IP internal: 3 -internal tool issue detected. Please report this bug along with a testcase. -.PP - -.IP mismatch: 3 -Incorrect or inconsistent information found in coverage data and/or source code - for example, -the source code contains overlapping exclusion directives. - -.PP - -.IP missing: 3 -remove all coverpoints associated with source files which are not found or are not readable. -This is equivalent to adding a -.I \-\-exclude -pattern for each file which is not found. -.br -If a -.I \-\-resolve\-script -callback is specified, then the file is considered missing if it is not -locally visible and the callback -returns "" (empty string) or 'undef' - otherwise not missing. -.br - -.IP negative: 3 -negative 'hit' count found. - -Note that negative counts may be caused by a known GCC bug - see - - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 - -and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. -.PP - - -.IP package: 3 -A required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. -.PP - -.IP parallel: 3 -various types of errors related to parallelism - -.I i.e., -a child process died due to an error. The corresponding error message appears in the log file immediately before the -.I parallel -error. -If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the \-\-parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. -.PP - -.IP path: 3 -File name found in -.B \-\-diff\-file -file but does not appear in either baseline or current trace data. These may be mapping issues - different pathname in the tracefile vs. the diff file. -.PP - -.IP range: 3 -Coverage data refers to a line number which is larger than the number of -lines in the source file. This can be caused by a version mismatch or -by an issue in the -.I gcov -data. -.PP - -.IP source: 3 -The source code file for a data set could not be found. -.PP - -.IP unmapped: 3 -Coverage data for a particular line cannot be found, possibly because the source code was not found, or because the line number mapping in the \.info file is wrong. - -This can happen if the source file used in HTML generation is not the same as the file used to generate the coverage data - for example, lines have been added or removed. -.PP - -.IP unreachable: 3 -a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. -If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the -.I retain_unreachable_coverpoints_if_executed -configuration parameter. -See man -.B lcovrc(5) -and the -.I "Exclusion markers" -section of man -.B geninfo(1) -for more information. -.PP - -.IP unsupported: 3 -The requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. -.PP - -.IP unused: 3 -The include/exclude/erase/substitute/omit pattern did not match any file pathnames. -.PP - -.IP usage: 3 -unsupported usage detected - e.g. an unsupported option combination. -.PP - -.IP utility: 3 -a tool called during processing returned an error code (e.g., 'find' encountered an unreadable directory). -.PP - -.IP version: 3 -\-\-version\-script comparison returned non\-zero mismatch indication. It likely that the version of the file which was used in coverage data extraction is different than the source version which was found. File annotations may be incorrect. -.PP - -Note that certain error messages are caused by issues that you probably cannot -fix by yourself - for example, bugs in your tool chain which result in -.I inconsistent -coverage DB data (see above). -In those cases, after reviewing the messages you may want to exclude the offending code or the entire offending -file, or you may simply ignore the messages - either by converting to warning or suppressing entirely. -Another alternative is to tell -.B genhtml -about the number of messages you expect - so that it can warn you if something changes -such that the count differs, such that you know to review the messages again. -See the -.I "\-\-expect\-message\-count" -flag, below. - -Also see 'man -.B lcovrc(5) -' for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. -.br - -.RE -.BI "\-\-expect\-message\-count message_type:expr[,message_type:expr]" -.RS -Give -.B genhtml -a constraint on the number of messages of one or more types which are expected to -be produced during execution. Note that the total includes _all_ messages -of the given type - including those which have been suppressed. -If the constraint is not true, an -error of type -.I "count" -(see above) is generated. -.I message_type -is one of the message mnemonics described above, and -.I expr -may be either -.IP \- 3 -an integer - interpreted to mean that there should be exactly that number -of messages of the corresponding type, or -.IP \- 3 -a Perl expression containing the substring -.B %C -; %C is replaced with the total number of messages of the corresponding type and -then evaluated. The constraint is met if the result is non-zero and is not met -otherwise. - -For example: -.IP -\-\-expect\-message\-count inconsistent:5 -.br -says that we expect exactly 5 messages of type 'inconsistent'. -.PP -.IP -\-\-expect\-message\-count inconsistent:%C==5 -.br -also says that we expect exactly 5 messages of this type, but specified -using expression syntax. -.PP -.IP -\-\-expect\-message\-count 'inconsistent : %C > 6 && %C <= 10' -.br -says that we expect the number of messages to be in the range (6:10]. -(Note that quoting may be necessary, to protect whitespace from interpretation by -your shell, if you want to improve expression readability by adding spaces to your expression.) -.PP - -Multiple constraints can be specified using a comma-separated list or -by using the option multiple times. - -This flag is equivalent to the -.I "expect_message_count" -configuration option. See man -.B lcovrc(5) -for more details on the expression syntax and how expressions are interpreted. -The number of messages of the particular type is substituted into the -expression before it is evaluated. - -.RE - -.BI "\-\-keep\-going " -.RS -Do not stop if error occurs: attempt to generate a result, however flawed. - -This command line option corresponds to the -.I stop_on_error -lcovrc option. See man -.B lcovrc(5) -for more details. - -.RE - -.B \-\-config\-file -.I config\-file -.br -.RS -Specify a configuration file to use. -See man -.B lcovrc(5) -for details of the file format and options. Also see the -.I config_file -entry in the same man page for details on how to include one config file into -another. - -When this option is specified, neither the system\-wide configuration 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 -.B genhtml -with different configuration file options in parallel. - -Note that this option must be specified in full - abbreviations are not supported. - -.RE - -.B \-\-profile -.I [ profile\-data\-file ] -.br -.RS -Tell the tool to keep track of performance and other configuration data. -If the optional -.I profile\-data\-file -is not specified, then the profile data is written to a file named -.I "genhtml.json" -in the output directory. -.br -Profile data is useful if you are trying to optimize the -.B lcov -implementation (see -.B $LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py -), and can also enable faster 'genhtml --parallel' execution (see the -"\-\-history\-script" section of this man page). - - -.RE - -.BI "\-\-history\-script" script -.br -.RS -Tell the tool to use performance data from a prior job to predict resource usage by the current job. -This may allow better segmentation to enable more balanced workloads between parallel threads - thus improving wall clock execution time. - -A common source for the -.I "previous\-profile\-data\-file" -is the profile data generated by a prior regression suite execution. -See -.B $LCOV_ROOT/share/lcov/example -and -.B $LCOV_ROOT/share/lcov/support-scripts/history.pm -in the installed release (or -.B .../example -in the source repository). -.RE - - -.B \-\-rc -.IR keyword = value -.br -.RS -Override a configuration directive. - -Use this option to specify a -.IR keyword = value -statement which overrides the corresponding configuration statement in -the lcovrc configuration file. You can specify this option more than once -to override multiple configuration statements. -See man -.BR lcovrc (5) -for a list of available keywords and their meaning. -.RE - -.BI "\-\-precision " num -.RS -Show coverage rates with -.I num -number of digits after the decimal point. - -Default value is 1. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_precision . -.RE - -.B \-\-merge\-aliases -.RS -Functions whose file/line is the same are considered to be aliases; -.B genthml -uses the shortest name in the list of aliases (fewest characters) as the leader. -.br -This option counts each alias group as a single object - so the 'function' -count will be the number of distinct function groups rather than the total number -of aliases of all functions - and displays them as groups in the 'function detail -table. -.br -Note that this option has an effect only if -.B "\-\-filter function" -has been applied to the coverage DB. -.br - -This parameter an be configured via the configuration file -.IR merge_function_aliases -option. See -.B man(5) lcovrc. - - -.B \-\-suppress\-aliases -.RS -Suppress list of aliases in function detail table. -.br - -Functions whose file/line is the same are considered to be aliases; -.B genthml -uses the shortest name in the list of aliases (fewest characters) as the leader. -.br - -The number of aliases can be large, for example due to instantiated templates - which can make function coverage results difficult to read. This option removes the list of aliases, making it easier to focus on the overall function coverage number, which is likely more interesting. - -Note that this option has an effect only if -.B "\-\-filter function" -has been applied to the coverage DB. - -This parameter an be configured via the configuration file -.IR merge_function_aliases -option. See -.B man(5) lcovrc. - - -.B \-\-forget\-test\-names -.br -.RS -If non\-zero, ignore testcase names in .info file - -.I i.e., -treat all coverage data as if it came from the same testcase. -This may improve performance and reduce memory consumption if user does -not need per-testcase coverage summary in coverage reports. - -This option can also be configured permanently using the configuration file -option -.IR forget_testcase_names . -.RE - -.B \-\-missed -.RS -Show counts of missed lines, functions, branches, and MC/DC expressions. - -Use this option to change overview pages to show the count of lines, functions, -branches, or MC/DC expressions that were not hit. These counts are represented by negative numbers. - -When specified together with \-\-sort\-tables, file and directory views will be sorted -by missed counts. - -This option can also be configured permanently using the configuration file -option -.IR genhtml_missed . -.RE - -.B \-\-dark\-mode -.RS -Use a light\-display\-on\-dark\-background color scheme rather than the default dark\-display\-on\-light\-background. - -The idea is to reduce eye strain due to viewing dark text on a bright screen - particularly at night. -.RE - -.B \-\-tempdir -.I dirname -.br -.RS -Write temporary and intermediate data to indicated directory. Default is "/tmp". -.RE - -.BI "\-\-preserve " -.RS -Preserve intermediate data files generated by various steps in the tool - e.g., for debugging. By default, these files are deleted. - -.RE - -.BI "\-\-save " -.RS -Copy -.I unified\-diff\-file, baseline_trace_files, -and -.I tracefile(s) -to -output\-directory. - -Keeping copies of the input data files may help to debug any issues or to regenerate report files later. - -.RE - -.B \-\-sort\-input -.br -.RS -Specify whether to sort file names before capture and/or aggregation. -Sorting reduces certain types of processing order-dependent output differences. -See the -.BI sort_input -section in -man -.B lcovrc(5). - -.RE - -.BI "\-\-serialize " file_name -.RS -Save coverage database to -.I file_name. - -The file is in Perl "Storable" format. - -Note that this option may significantly increase -.I genhtml -memory requirements, as a great deal of data must be retained. - -.RE - -.SH FILES - -.I /etc/lcovrc -.RS -The system\-wide configuration file. -.RE - -.I ~/.lcovrc -.RS -The per\-user configuration file. -.RE - -Sample -.I \-\-diff\-file -data creation scripts: -.RS - -.I \*[scriptdir]/p4udiff -.RS -Sample script for use with -.B --diff-file -that creates a unified diff file via -.B Perforce. -.br -.RE - -.I \*[scriptdir]/gitdiff -.RS -Sample script for use with -.B --diff-file -that creates a unified diff file via -.B git. -.br -.RE -.RE - -Sample -.I \-\-annotate\-script -callback Perl modules: - -.RS -.I \*[scriptdir]/p4annotate.pm -.RS -Sample script written as Perl module for use with -.B --annotate-script -that provides annotation data via -.B Perforce. -.br -.RE - -.I \*[scriptdir]/gitblame.pm -.RS -Sample script written as Perl module for use with -.B --annotate-script -that provides annotation data via git. -.br -.RE -.RE - -Sample -.I \-\-criteria\-script -callback Perl modules: -.RS - -.I \*[scriptdir]/criteria.pm -.RS -Sample script written as Perl module for use with -.B --criteria-script -that implements a check for "UNC + LBC + UIC == 0". -.br -.RE - -.I \*[scriptdir]/threshold.pm -.RS -Sample script written as Perl module to check for minimum acceptable -line and/or branch and/or and/or MC/DC function coverage. -For example, the -.RS -.I "genhtml --fail_under_lines 75 ..." -.RE -feature can instead be realized by -.RS -.I "genhtml --criteria-script \*[scriptdir]/threshold.pm,--line,75 ..." -.RE -.br -.RE -.RE - -Sample -.I \-\-simplify\-script -callback Perl module: -.RS - -.I \*[scriptdir]/simplify.pm -.RS -Sample script written as Perl module for use with -.B \-\-simplify\-script -that implements regular expression substitutions for function name simplification. -.br -.RE - -.RE -.RE - -Sample -.I \-\-version\-script -callback Perl modules and scripts: -.RS - -.I \*[scriptdir]/getp4version -.RS -Sample script for use with -.B \-\-version\-script -that obtains version IDs via -.B Perforce. -.br -.RE - -.I \*[scriptdir]/P4version.pm -.RS -A perl module with similar functionality to -.B getp4version -but higher performance. -.br -.RE - -.I \*[scriptdir]/get_signature -.RS -Sample script for use with -.B --version-script -that uses md5hash as version IDs. -.br -.RE - -.I \*[scriptdir]/gitversion.pm -.RS -A perl module with for use with -.B \-\-version\-script -which retrieves version IDs from -.B git. -.br -.RE - -.I \*[scriptdir]/batchGitVersion.pm -.RS -A perl module with similar functionality to -.B gitversion.pm -but higher performance. -.br -.RE -.RE - - -.SH AUTHORS -Peter Oberparleiter -.br - -Henry Cox -.RS -Differential coverage and date/owner binning, filtering, error management, -parallel execution sections, -.RE -.br - -.SH SEE ALSO -.BR lcov (1), -.BR lcovrc (5), -.BR geninfo (1), -.BR genpng (1), -.BR gendesc (1), -.BR gcov (1) -.br - -.I \*[lcovurl] -.br diff --git a/man/geninfo.1 b/man/geninfo.1 deleted file mode 100644 index bac7022d..00000000 --- a/man/geninfo.1 +++ /dev/null @@ -1,2082 +0,0 @@ -\" Define path to scripts -.ds scriptdir bin - -\" Define project URL -.ds lcovurl https://github.com/linux\-test\-project/lcov - -.TH geninfo 1 "LCOV 2.0" 2023\-05\-17 "User Manuals" -.SH NAME -geninfo \- Generate tracefiles from GCOV coverage data files -.SH SYNOPSIS -.B geninfo -.RB [ \-h | \-\-help ] -.RB [ \-\-version ] -.RB [ \-q | \-\-quiet ] -.RB [ \-v | \-\-verbose ] -.RB [ \-\-debug ] -.br -.RS 8 -.RB [ \-\-comment -.IR comment-string ] -.br -.RB [ \-i | \-\-initial ] -.RB [ \-\-all ] -.br -.RB [ \-t | \-\-test\-name -.IR test\-name ] -.br -.RB [ \-o | \-\-output\-filename -.IR filename ] -.RB [ \-f | \-\-follow ] -.br -.RB [ \-b | \-\-base\-directory -.IR directory ] -.br -.RB [ \-\-build\-directory -.IR directory ] -.br -.RB [ \-\-branch\-coverage ] -.br -.RB [ \-\-mcdc\-coverage ] -.br -.RB [ \-\-checksum ] -.RB [ \-\-no\-checksum ] -.br -.RB [ \-\-compat\-libtool ] -.RB [ \-\-no\-compat\-libtool ] -.br -.RB [ \-\-gcov\-tool -.IR tool ] -.br -.RB [ \-\-parallel | -j -.IR [integer] ] -.br -.br [ \-\-large\-file -.IR regexp ] -.br -.RB [ \-\-memory -.IR integer_num_Mb ] -.br -.RB [ \-\-msg\-log -.IR [ log_file_name ] ] -.br -.RB [ \-\-ignore\-errors -.IR errors ] -.br -.RB [\-\-expect\-message\-count -.IR message_type=expr[,message_type=expr..]] -.br -.RB [ \-\-keep\-going ] -.br -.RB [ \-\-preserve ] -.br -.RB [ \-\-filter -.IR type ] -.br -.RB [ \-\-demangle\-cpp [param]] -.br -.RB [ \-\-no\-recursion ] -.RB [ \-\-external ] -.RB [ \-\-no\-external ] -.br -.RB [ \-\-sort\-input ] -.br -.RB [ \-\-config\-file -.IR config\-file ] -.RB [ \-\-no\-markers ] -.br -.RB [ \-\-profile -.IR [ profile\-file ] ] -.br -.RB [ \-\-history\-script -.IR callback ] -.br -.RB [ \-\-compat -.IR mode =on|off|auto] -.br -.RB [ \-\-rc -.IR keyword = value ] -.br -.RB [ \-\-include -.IR glob_pattern ] -.br -.RB [ \-\-exclude -.IR glob_pattern ] -.br -.RB [ \-\-erase\-functions -.IR regexp_pattern ] -.br -.RB [ \-\-substitute -.IR regexp_pattern ] -.br -.RB [ \-\-omit\-lines -.IR regexp_pattern ] -.br -.RB [ \-\-fail\-under\-branches -.IR percentage ] -.br -.RB [ \-\-fail\-under\-lines -.IR percentage ] -.br -.RB [ \-\-forget\-test\-names ] -.br -.RB [ \-\-context\-script -.IR script_file ] -.br -.RB [ \-\-criteria\-script -.IR script_file ] -.br -.RB [ \-\-resolve\-script -.IR script_file ] -.br -.RB [ \-\-version\-script -.IR script_file ] -.br -.RB [ \-\-unreachable\-script -.IR module_file ] -.br -.RB [ \-\-tempdir -.IR dirname ] -.br -.IR directory -.RE - -.SH DESCRIPTION - -Use -.B geninfo -to create LCOV tracefiles from GCC and LLVM/Clang coverage data files (see -.B --gcov-tool -for considerations when working with LLVM). You can use -.B genhtml -to create an HTML report from a tracefile. -.br - -Note that -.B geninfo -is called by -.BR "lcov --capture" , -so there is typically no need to call it directly. -.br - -Unless the -.B --output-filename -option is specified -.B geninfo -writes its output to one file with .info filename extension per input file. -.br - -Note also that the current user needs write access to both -.I 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. -.br - -By default, -.B geninfo -collects line and function coverage data. -Neither branch nor MC/DC data is not collected by default; you can use the -.B \-\-branch\-coverage -and -.B \-\-mcdc\-coverage -command line options to enable them, or you can permanently enable them by adding -.B branch_coverage = 1 -and/or -.B mcdc_coverage = 1 -to your personal, group, or site lcov configuration file. See man -.B lcovrc(5) -for details. - - -.SS "File types" - -A -.B tracefile -is a coverage data file in the format used by all LCOV tools such as -.BR geninfo ", " lcov ", and " genhtml . -By convention, tracefiles have a .info filename extension. See "Tracefile format" below for a description of the file format. -.br - -A -.B .gcda file -is a compiler-specific file containing run-time coverage data. It is created and updated when a program compiled with GCC/LLVM's -.B --coverage -option is run to completion. -.B geninfo -reads .gcda files in its default mode of operation. Note: earlier compiler versions used the .da filename extension for this file type. -.br - -A -.B .gcno file -is a compiler-specific file containing static, compile-time coverage data. It is created when source code is compiled with GCC/LLVM's -.B --coverage -option. -.B geninfo -reads .gcno files when option -.B --initial -is specified. Note: earlier compiler versions used .bb and .bbg filename extensions for this file type. -.br - -A -.B .gcov file -is a textual or JSON representation of the data found in .gcda and .gcno files. It is created by the -.BR gcov -tools that is part of GCC (see -.B --gcov-tool -for LLVM considerations). -There are multiple gcov file format versions, including textual, intermediate, and JSON format. -.B geninfo -internally uses -.B gcov -to extract coverage data from .gcda and .gcno files using the best supported gcov file format. -.br - -See the -.B gcov -man page for more information on .gcda, .gcno and .gcov output formats. -.br - -.SS "Exclusion markers" - -To exclude specific lines of code from a tracefile, you can add exclusion -markers to the source code. Similarly, you can mark specific regions of code -as "unreachable". An "unreachable" error message is generated if any -coverpoints in unreachable regions are executed ( -.I i.e., -have non-zero hit counts. -See the -.I retain_unreachable_coverpoints_if_executed -section in man -.B lcovrc(1) -for a description of the actions taken in this case. - -Additionally you can exclude specific branches or MC/DC expressions -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 man -.BR lcovrc (5) -how to override the exclusion keywords ( -.I e.g., -to reuse markers inserted for other tools or to generate reports with different -sets of excluded regions). - -The following markers are recognized by geninfo: - -.B LCOV_EXCL_LINE -.br -.RS -Lines containing this marker will be excluded. -.br -.RE - -.B LCOV_EXCL_START -.br -.RS -Marks the beginning of an excluded section. The current line is part of this -section. -.br -.RE - -.B LCOV_EXCL_STOP -.br -.RS -Marks the end of an excluded section. The current line not part of this -section. -.br -.RE - -.B LCOV_UNREACHABLE_LINE -.br -.RS -If the marked line is 'hit', then generate an error: we believe the marked code -is unreachable and so there is a bug in the code, the plaement of the directive, or both. -Lines containing this marker will be excluded from reporting. -.br -Apart from error reporting, this directive is equivalent to -.I LCOV_EXCL_LINE. -.RE - -.B LCOV_UNREACHABLE_START -.br -.RS -Marks the beginning of an unreachable section of code. The current line in part of this region. -.br -As described in the -.I LCOV_UNREACHABLE_LINE -section, above: an error is generated if any code in the region is hit, but the code is excluded from reporting. -.RE - -.B LCOV_UNREACHABLE_STOP -.br -.RS -Marks the end of the region of unreachable code. The current line not part of this -section. -.RE - -.B LCOV_EXCL_BR_LINE -.br -.RS -Lines containing this marker will be excluded from branch coverage. -.br -.RE - -.B LCOV_EXCL_BR_START -.br -.RS -Marks the beginning of a section which is excluded from branch coverage. The -current line is part of this section. -.br -.RE - -.B LCOV_EXCL_BR_STOP -.br -.RS -Marks the end of a section which is excluded from branch coverage. The current -line not part of this section. -.br -.RE - -.B LCOV_EXCL_EXCEPTION_BR_LINE -.br -.RS -Lines containing this marker will be excluded from exception branch coverage: -Exception branches will be ignored, but non-exception branches will not be -affected. -.br -.RE - -.B LCOV_EXCL_EXCEPTION_BR_START -.br -.RS -Marks the beginning of a section which is excluded from exception branch -coverage. The current line is part of this section. -.br -.RE - -.B LCOV_EXCL_EXCEPTION_BR_STOP -.br -.RS -Marks the end of a section which is excluded from exception branch coverage. -The current line not part of this section -.br -.RE - -In addition, -.B geninfo -also supports the -.I \"\-\-unreachable\-script\" -option. This provides a mechanism to exclude particular branch expressions and/or MC/DC conditions from coverage reports. -A simple sample callback can be found in -.RS -.B \*[scriptdir]/unreach.pm. -.RE - -This sample callback adds support for branch-specific and condition-specific -exclusion, specified by end-of-line annotations in the source code: - -.RS -.IP "LCOV_EXCLUDE_BRANCH (expressionId[,blockId])\+" -One or more space-separated branch exclusions may specified. -.RS -.IP expressionId: -.br -decimal integer which specifies which branch to exclude. -An error is generated if an the index is invalid -.IP blockId -.br -decimal integer which specified the block index which contains the excluded expression. -.br -An error is generated if the block index is invalid -If there is only one branch block at this location, -then the block ID does not need to be specified -.PP -.PP -.RE - -.IP "LCOV_UNREACHABLE_COND ([groupSize,]conditionId(t|f))\+" -One or more space-separated MC/DC exclusions may specified. -.RS -.IP groupSize -decimal integer which specified the group which contains -the excluded condition. -.br -An error is generated if the groupSize is invalid -.br -If there is only one MC/DC group at this location, -then the groupSize does not need to be specified. -.IP conditionId -.br -decimal integer which specifies which condition to exclude -.br -An error is generated if an the index is invalid - -.IP sense -t' or 'f': the value of the condition which is unreachable - -.RE - -.RE - -For example, the line -.RS -code // LCOV_EXCLUDE_BRANCH 0,1 3 LCOV_EXCLUDE_CONDITION 0f -.RE -will exclude branch expressions 1 and 3 from block 0 (or generate an error if there is more than one branch block on this line), and the 'false' sense of condition 0 (or generate an error if there is more than one MC/DC group on this line). - -One way to determine the branch and/or condition ID in order to -exclude them is to generate an HTML report without exclusions then hover the -mouse over the colorized branch/condition region and read the IDs from the -tooltip popup. -Another way is to simply read the BRDA/MCDC entries in coverage data file. - -See the comment at the top of the sample script for more details. - -.SH OPTIONS - -In general, (almost) all -.B geninfo -options can also be specified in your personal, group, project, or site -configuration file - see the -.I \-\-config\-file -section, below, and man -.B lcovrc(5) -for details. - - -.B \-b -.I directory -.br -.B \-\-base\-directory -.I directory -.br -.RS -.RI "Use " directory -as base directory for relative paths. - -Use this option to specify the base directory of a build\-environment -when geninfo produces error messages like: - -.RS -ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c -.RE - -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 directory 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 multiple base -directories are used. In that case use configuration file setting -.B geninfo_auto_base=1 -(see man -.BR lcovrc (5)). -.RE - -.B \-\-build\-directory -.I build_dir -.br -.RS -Search for .gcno data files from -.I build_dir -rather finding them only adjacent to the corresponding .o and/or .gcda file. - -By default, geninfo expects to find the .gcno and .gcda files (compile- -and run-time data, respectively) in the same directory. -.br - -When this option is used: -.br - -.RS -geninfo path1 \-\-build\-directory path2 ... -.RE -.br - -then geninfo will look for .gcno file -.br - -.RS -path2/relative/path/to/da_base.gcno -.RE -.br - -when it finds .gcda file -.br - -.RS -path1/relative/path/to/da_base.gcda. -.RE - -Use this option when you have used the -.I GCOV_PREFIX -environment variable to direct the gcc or llvm runtime environment to write -coverage data files to somewhere other than the directory where the code -was originally compiled. -See -.BR gcc (1) -and/or search for -.I GCOV_PREFIX -and -.I GCOV_PREFIX_STRIP. - -This option can be used several times to specify multiple alternate directories to look for .gcno files. This may be useful if your application uses code which is compiled in many separate locations - for example, common libraries that are shared between teams. - -.RE -.BI "\-\-source\-directory " dirname -.RS -Add 'dirname' to the list of places to look for source files. -.br - -For relative source file paths found in the gcov data \- possibly after substitutions have been applied, -.B geninfo -will first look for the path from 'cwd' (where genhtml was -invoked) and -then from each alternate directory name in the order specified. -The first location matching location is used. - -This option can be specified multiple times, to add more directories to the source search path. -.RE - -.B \-\-branch\-coverage -.br -.RS -Collect retain branch coverage data. - -This is equivalent to using the option "\-\-rc branch_coverage=1"; the option was added to better match the genhml interface. - -.RE - -.B \-\-mcdc\-coverage -.br -.RS -Collect retain MC/DC data. - -This is equivalent to using the option "\-\-rc mcdc_coverage=1". -MC/DC coverage capture is supported for GCC versions 14.2 and higher, -or LLVM versions 18.1 and higher. -.br -See -.I llvm2lcov \-\-help -for details on MC/DC data capture in LLVM. - -.br -See the MC/DC section of man -.B genhtml(1) -for more details -.RE - -.B \-\-checksum -.br -.B \-\-no\-checksum -.br -.RS -Specify whether to generate checksum data when writing tracefiles. - -Use -.B \-\-checksum -to enable checksum generation or -.B \-\-no\-checksum -to disable it. Checksum generation is -.B disabled -by default. - -When checksum generation is enabled, a checksum will be generated for each -source code line and stored along with the coverage data. This checksum will -be used to prevent attempts to combine 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. - -Note that this options is somewhat subsumed by the -.B \-\-version\-script -option - which does something similar, but at the 'whole file' level. - -.RE - -.B \-\-compat -.IR mode = value [, mode = value ,...] -.br -.RS -Set compatibility mode. - -Use -.B \-\-compat -to specify that geninfo should enable one or more compatibility -modes when capturing coverage data. You can provide a comma-separated list -of mode=value pairs to specify the values for multiple modes. - -Valid -.I values -are: - -.B on -.RS -Enable compatibility mode. -.RE -.B off -.RS -Disable compatibility mode. -.RE -.B auto -.RS -Apply auto-detection to determine if compatibility mode is required. Note that -auto-detection is not available for all compatibility modes. -.RE - -If no value is specified, 'on' is assumed as default value. - -Valid -.I modes -are: - -.B libtool -.RS -Enable this mode if you are capturing coverage data for a project that -was built using the libtool mechanism. See also -.BR \-\-compat\-libtool . - -The default value for this setting is 'on'. - -.RE -.B hammer -.RS -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 versions. 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'. - -.RE -.B split_crc -.RS -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' -.RE - -.RE - -.B \-\-compat\-libtool -.br -.B \-\-no\-compat\-libtool -.br -.RS -Specify whether to enable libtool compatibility mode. - -Use -.B \-\-compat\-libtool -to enable libtool compatibility mode or -.B \-\-no\-compat\-libtool -to disable it. The libtool compatibility mode is -.B enabled -by default. - -When libtool compatibility mode is enabled, geninfo will assume that the source -code relating to a .gcda file located in a directory 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. -.RE - -.B \-\-config\-file -.I config\-file -.br -.RS -Specify a configuration file to use. -See man -.B lcovrc(5) -for details of the file format and options. -Also see the -.I config_file -entry in the same man page for details on how to include one config file into -another. - -When this option is specified, neither the system\-wide configuration 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 -.B geninfo -with different configuration file options in parallel. - -Note that this option must be specified in full - abbreviations are not supported. - -.RE - -.B \-\-profile -.I [ profile\-data\-file ] -.br -.RS -Tell the tool to keep track of performance and other configuration data. -If the optional -.I profile\-data\-file -is not specified, then the profile data is written to a file named with the same -basename as the -.I \-\-output\-filename, with suffix -.I ".json" -appended. -.br -Profile data is useful if you are trying to optimize the -.B geninfo -implementation (see -.B $LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py -), and can also enable faster 'geninfo --parallel' execution (see the -"\-\-history\-script" section of this man page). - -.RE - - -.B \-\-history\-script -.I callback -.br -.RS -Tell the tool to use performance data from a prior job to predict resource usage by the current job. -This may allow better segmentation to enable more balanced workloads between parallel threads - thus improving wall clock execution time. - -A common source for the performance history is the -.I "previous\-profile\-data\-file" -generated by the -.I "\-\-profile" -argument. - -See a sample callback implementation in -.B $LCOV_ROOT/share/lcov/support\-scripts/history.pm -and its use in -.B $LCOV_ROOT/share/lcov/example -in the installed release (or -.B .../example -and -.B .../scripts/history.pm -in the source repository). -.RE - -See man -.B genhtml(1) -for more details. - - -.B \-\-external -.br -.B \-\-no\-external -.br -.RS -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 -.I \-\-directory -or -.I \-\-base\-directory. -Use -.I \-\-external -to include -coverpoints in external source files while capturing coverage data or -.I \-\-no\-external -to exclude them. -If your -.I \-\-directory -or -.I \-\-base\-directory -path contains a soft link, then actual target directory is not considered to be -"internal" unless the -.I \-\-follow -option is used. - -The -.I \-\-no\-external -option is somewhat of a blunt instrument; the -.I \-\-exclude -and -.I \-\-include -options provide finer grained control over which coverage data is and is not -included if your project structure is complex and/or -.I \-\-no\-external -does not do what you want. - -Data for external source files is -.B included -by default. -.RE - -.B \-f -.br -.B \-\-follow -.RS -Follow links when searching .gcda files, as well as to decide whether a -particular (symbolically linked) source directory is "internal" to the project or not - see the -.I \-\-no\-external -option, above, for more information. -The -.I \-\-follow command line option is equivalent to the -.I geninfo_follow_symlinks -config file option. See man -.B lcovrc(5) for more information. -.RE - -.RE - -.B \-\-sort\-input -.br -.RS -Specify whether to sort file names before capture and/or aggregation. -Sorting reduces certain types of processing order-dependent output differences. -See the -.BI sort_input -section in -man -.B lcovrc(5). - -.RE - -.B \-\-gcov\-tool -.I tool -.br -.RS -Specify the location of the gcov tool. - -If the -.B \-\-gcov\-tool -option is used multiple times, then the arguments are concatenated when the callback -is executed - similar to how the gcc -.B \-Xlinker -parameter works. This provides a possibly easier way to pass arguments to -your tool, without requiring a wrapper script. -In that case, your callback will be executed as: -.I tool\-0 'tool\-1; ... 'filename'. -Note that the second and subsequent arguments are quoted when passed to -the shell, in order to handle parameters which contain spaces. - -The -.B \-\-gcov\-tool -argument may be a -.I split_char -separated string - see -.B man(4) lcovrc. - -A common use for this option is to enable LLVM: -.br - -.RS -.BR "geninfo \-\-gcov-tool " "llvm-cov " "\-\-gcov-tool " "gcov ..." -.br -.BR "geninfo \-\-gcov-tool " "llvm-cov,gcov ..." -.RE -.br - -Note: 'llvm-cov gcov da_file_name' will generate output in gcov-compatible format as required by lcov. - -If not specified, 'gcov' is used by default. - -.RE - -.B \-h -.br -.B \-\-help -.RS -Print a short help text, then exit. -.RE - -.B \-\-include -.I pattern -.br -.RS -Include source files matching -.IR pattern . - -Use this switch if you want to include coverage data for only a particular set -of source files matching any of the given patterns. Multiple patterns can be -specified by using multiple -.B \-\-include -command line switches. The -.I patterns -will be interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). - -See the lcov man page for details - -.RE - -.B \-\-exclude -.I pattern -.br -.RS -Exclude source files matching -.IR pattern . - -Use this switch if you want to exclude coverage data from a particular set -of source files matching any of the given patterns. Multiple patterns can be -specified by using multiple -.B \-\-exclude -command line switches. The -.I patterns -will be interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). -Note: The pattern must be specified to match the -.B absolute -path of each source file. - -Can be combined with the -.B \-\-include -command line switch. If a given file matches both the include pattern and the -exclude pattern, the exclude pattern will take precedence. - -See the lcov man page for details. - -.RE - -.B \-\-erase\-functions -.I regexp -.br -.RS -Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the \-\-demangle\-cpp option is used or not. - -Note that this option requires that you use a gcc version which is new enough to support function begin/end line reports or that you configure the tool to derive the required dta - see the -.BI derive_function_end_line -discussion in the -.B lcovrc -man page. - - -.RE - -.B \-\-substitute -.I regexp_pattern -.br -.RS -Apply Perl regexp -.IR regexp_pattern -to source file names found during processing. This is useful when the path name reported by gcov does not match your source layout and the file is not found. See the lcov man page for more details. - -.RE - -.B \-\-omit\-lines -.I regexp -.br -.RS -Exclude coverage data from lines whose content matches -.IR regexp . - -Use this switch if you want to exclude line, branch, and MC/DC coverage data for some particular constructs in your code (e.g., some complicated macro). -See the lcov man page for details. - -.RE - -.B \-\-forget\-test\-names -.br -.RS -If non\-zero, ignore testcase names in tracefile - -.I i.e., -treat all coverage data as if it came from the same testcase. -This may improve performance and reduce memory consumption if user does -not need per-testcase coverage summary in coverage reports. - -This option can also be configured permanently using the configuration file -option -.IR forget_testcase_names . -.RE - -.B \-\-msg\-log -.I [ log_file_name ] -.br -.RS -Specify location to store error and warning messages (in addition to writing to STDERR). -If -.I log_file_name -is not specified, then default location is used. -.RE - -.B \-\-ignore\-errors -.I errors -.br -.RS -Specify a list of errors after which to continue processing. - -Use this option to specify a list of one or more classes of errors after which -.B geninfo -should continue processing instead of aborting. -Note that the tool will generate a warning (rather than a fatal error) unless you ignore the error two (or more) times: -.br -.RS -geninfo ... \-\-ignore\-errors unused,unused -.RE - -.I errors -can be a comma\-separated list of the following keywords: - -.IP branch: 3 -branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. -.PP - -.IP callback: 3 -Version script error. -.PP - -.IP child: 3 -child process returned non-zero exit code during -.I \-\-parallel -execution. This typically indicates that the child encountered an error: see the log file immediately above this message. -In contrast: the -.B parallel -error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. -.PP - -.IP corrupt: 3 -corrupt/unreadable file found. -.PP - -.IP count: 3 -An excessive number of messages of some class have been reported - subsequent messages of that type will be suppressed. -The limit can be controlled by the 'max_message_count' variable. See the lcovrc man page. -.PP - -.IP deprecated: 3 -You are using a deprecated option. -This option will be removed in an upcoming release - so you should change your -scripts now. -.PP - -.IP empty: 3 -the .info data file is empty (e.g., because all the code was 'removed' or excluded. -.PP - -.IP excessive: 3 -your coverage data contains a suspiciously large 'hit' count which is unlikely -to be correct - possibly indicating a bug in your toolchain. - -See the -.I excessive_count_threshold -section in man -.B lcovrc(5) -for details. -.PP - -.IP fork: 3 -Unable to create child process during -.I \-\-parallel -execution. -.br -If the message is ignored ( -.I \-\-ignore\-errors fork -), then genhtml -will wait a brief period and then retry the failed execution. -.br -If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. -.PP - -.IP format: 3 -Unexpected syntax or value found in .info file - for example, negative number or -zero line number encountered. -.PP - -.IP gcov: 3 -the gcov tool returned with a non\-zero return code. -.PP - -.IP graph: 3 -the graph file could not be found or is corrupted. -.PP - -.IP inconsistent: 3 -your coverage data is internally inconsistent: it makes two or more mutually -exclusive claims. For example, some expression is marked as both an exception branch and not an exception branch. (See man -.B genhtml(1) -for more details. - -.IP internal: 3 -internal tool issue detected. Please report this bug along with a testcase. -.PP - -.IP mismatch: 3 -Incorrect information found in coverage data and/or source code - for example, -the source code contains overlapping exclusion directives. -.PP - -.IP missing: 3 -File does not exist or is not readable. -.PP - -.IP negative: 3 -negative 'hit' count found. - -Note that negative counts may be caused by a known GCC bug - see - - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 - -and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. -.PP - -.IP package: 3 -a required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. -.PP - -.IP parallel: 3 -various types of errors related to parallelism - -.I i.e., -a child process died due to an error. The corresponding error message appears in the log file immediately before the -.I parallel -error. - -If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the \-\-parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. -.PP - -.IP parent: 3 -the parent process exited while child was active during -.I \-\-parallel -execution. This happens when the parent has encountered a fatal error - -.I e.g. -an error in some other child which was not ignored. This child cannot continue working without its parent - and so will exit. - -.PP - -.IP path: 3 -some file paths were not resolved - e.g., .gcno file corresponding to -some .gcda was not found see -.I \-\-build\-directory -option for additional information. - -.PP - -.IP range: 3 -Coverage data refers to a line number which is larger than the number of -lines in the source file. This can be caused by a version mismatch or -by an issue in the -.I gcov -data. -.PP - -.IP source: 3 -the source code file for a data set could not be found. -.PP - -.IP unreachable: 3 -a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. -If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the -.I retain_unreachable_coverpoints_if_executed -configuration parameter. -See man -.B lcovrc(5) -and the -.I "Exclusion markers" -section, above. -.PP - -.IP unsupported: 3 -the requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. -.PP - -.IP unused: 3 -the include/exclude/erase/omit/substitute pattern did not match any file pathnames. -.PP - -.IP usage: 3 -unsupported usage detected - e.g. an unsupported option combination. -.PP - -.IP utility: 3 -a tool called during processing returned an error code (e.g., 'find' encountered an unreadable directory). -.PP - -.IP version: 3 -revision control IDs of the file which we are trying to merge are not the same - line numbering and other information may be incorrect. -.PP - -Also see the -.I \-\-ignore\-errors -section in man -.B genhtml(1). -The description there may be more complete and/or more fully explained. - -See man -.B lcovrc(5) - for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. - -.RE - -.BI "\-\-expect\-message\-count message_type:expr[,message_type:expr]" -.RS -Give -.B geninfo -a constraint on the number of messages of one or more types which are expected to -be produced during execution. If the constraint is not true, then generate an -error of type -.I "count" -(see above). - -See man -.B genhtml(1) -for more details about the flag, as well as the -.I "expect_message_count" -section in man -.B lcovrc(5) -for a description of the equivalent configuration file option. -.RE - -.BI "\-\-keep\-going " -.RS -Do not stop if error occurs: attempt to generate a result, however flawed. - -This command line option corresponds to the -.I stop_on_error [0|1] -lcovrc option. See man -.B lcovrc(5) for more details. - -.RE - -.BI "\-\-fail-under-lines " -.I percentage -.br -.RS -Use this option to tell geninfo to exit with a status of 1 if the total -line coverage is less than -.I percentage. -See -.B man lcov(1) -for more details. -.RE - -.BI "\-\-preserve " -.RS -Preserve intermediate data files (e.g., for debugging). - -By default, intermediate files are deleted. - -.RE -.BI "\-\-filter " -.I filters -.RS -Specify a list of coverpoint filters to apply to input data. -See the genhtml man page for details. - -.RE -.BI "\-\-demangle\-cpp " [param] -.RS -Demangle C++ method and function names in captured output. -See the genhtml man page for details. - -.RE -.B \-i -.br -.B \-\-initial -.RS -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 -correct even when not all object code files were loaded during the test. -Also see the -.I \-\-all -flag, below. - -Note: the -.B \-\-initial -option is not supported for gcc versions less than 6, and does not generate branch coverage information for gcc versions less than 8. -.RE - -.B \-\-all -.RS -Capture coverage data from both compile time (.gcno) data files which do not have corresponding runtime (.gcda) data files, as well as from those that -.I do -have corresponding runtime data. -There will be no runtime data unless some executable which links the corresponding object file has run to completion. - -Note that the execution count of coverpoints found only in files which do not have any runtime data will be zero. - -This flag is ignored if the -.I \-\-initial -flag is set. - -Using the -.B \-\-all -flag is equivalent to executing both -.I geninfo --initial ... -and -.I geninfo ... -and merging the result. - -Also see the -.I geninfo_capture_all -entry in -.B man(5) lcovrc. - -.RE - - -.B \-\-no\-markers -.br -.RS -Unless the -.I \-\-no\-markers -option is used, -.BR geninfo -will apply both -.I region -and -.I branch_region -filters to the captured coverae data. -Use this option if you want to get coverage data without regard to exclusion -markers in the source code file. - -If any -.I \-\-filter -options are applied, then the default region filters are not used. - -.I \-\-no\-markers should not be specified along with -.I \-\-filter. -.RE - -.B \-\-no\-recursion -.br -.RS -Use this option if you want to get coverage data for the specified directory -only without processing subdirectories. -.RE - -.BI "\-o " output\-filename -.br -.BI "\-\-output\-filename " output\-filename -.RS -Write all data to -.IR output\-filename . - -If you want to have all data written to a single file (for easier -handling), use this option to specify the respective filename. By default, -one tracefile will be created for each processed .gcda file. -.RE - -.RE -.B \-\-context\-script -.I script -.br -.RS - -Use -.I script -to collect additional tool execution context information - to aid in -infrastructure debugging and/or tracking. - -See the genhtml man page for more details on the context script. - -.br - -.RE -.B \-\-criteria\-script -.I script -.br -.RS - -Use -.I script -to test for coverage acceptance criteria. - -See the genhtml man page for more details on the criteria script. -Note that geninfo does not keep track of date and owner information (see the -.I \-\-annotate\-script -entry in the genhtml man page) - so this information is not passed to the geninfo callback. - -.br - -.RE -.B \-\-resolve\-script -.I script -.br -.RS -Use -.I script -to find the file path for some source or GCNO file which appears in -an input data file if the file is not found after applying -.I \-\-substitute -patterns and searching the -.I \-\-source\-directory -or -.I \-\-build\-directory -list. - -This option is equivalent to the -.B resolve_script -config file option. -.br -In addition, the -.I geninfo_follow_path_links -config file option can be used to resolve source paths to their actual -target. - -See man -.B lcovrc(5) -for details. -.RE - -.RE -.B \-\-version\-script -.I script -.br -.RS -Use -.I script -to get a source file's version ID from revision control when -extracting data. The ID is used for error checking when merging .info files. -.br - -See the genhtml man page for more details on the version script. - -.RE -.B \-\-unreachable\-script -.I module -.br -.RS -Use -.I module -to decide whether particular branch expressions and/or MC/DC conditions -should be removed from the coverage report. -This option is equivalent to the -.B unreachable_script -config file option. See man -.B lcovrc(5) -for details. - -Note that -.I \"module\" -is required to be a Perl module. - -See the genhtml man page and the -.I \"Exclusion markers\" -section, above, for more information. - -.B \-v -.br -.B \-\-verbose -.RS -Increment informational message verbosity. This is mainly used for script and/or flow debugging - e.g., to figure out which data file are found, where. -Also see the -.B \-\-quiet -flag. - -Messages are sent to stdout unless there is no output file (i.e., if the coverage data is written to stdout rather than to a file) and to stderr otherwise. - -.RE -.B \-q -.br -.B \-\-quiet -.RS -Decrement informational message verbosity. - -Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. - -.RE -.B \-\-debug -.RS -Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. - -.RE -.B \-\-comment comment_string -.RS -Append -.I comment_string -to list of comments emitted into output result file. -This option may be specified multiple times. -Comments are printed at the top of the file, in the order they were specified. - -Comments can be useful to document the conditions under which the trace file was -generated: host, date, environment, -.I etc. - - -.RE - -.BI "\-\-parallel " -.I [ integer ] -.br -.BI "\-j " -.I [ integer ] -.RS -Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). - -The -.I \-\large\-file -option described below may be necessary to enable parallelism to succeed -in the presence of data files which consume excessive memory in -.B gcov. - -Also see the -.I memory, memory_percentage, max_fork_fails, fork_fail_timeout, geninfo_chunk_size -and -.I geninfo_interval_update -entries in man -.B lcovrc(5) -for a description of some options which may aid in parameter tuning and performance optimization. -.br -A previously generated execution profile may help to enable better utilization -and faster parallel execution. See the -.I "\-\-profile" -and -.I "\-\-history\-script" -sections of this man page. - -.RE -.BI "\-\-large\-file " -.I regexp -.RS - -GCDA files whose name matches a -.I \-\-large\-file -regexp are processed serially - not in parallel with other files - so that -their -.B gcov -process can use all available system memory. -.br -Use this option is you see errors related to memory allocation from gcov. -.br -This feature is exactly as if you had moved the matching GCDA files to another location and processed them serially, then processed remaining GDCA files in parallel and merged the results. - -This option may be used multiple times to specify more than one regexp. - -.RE -.BI "\-\-memory " -.I integer -.RS -Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. - -This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does now know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. - -The configuration file -.I memory_percentage -option provided another way to set the maximum memory consumption. -See man -.B lcovrc(5) -for details. - -.RE - -.B \-\-rc -.IR keyword = value -.br -.RS -Override a configuration directive. - -Use this option to specify a -.IR keyword = value -statement which overrides the corresponding configuration statement in -the lcovrc configuration file. You can specify this option more than once -to override multiple configuration statements. -See man -.BR lcovrc (5) -for a list of available keywords and their meaning. -.RE - -.BI "\-t " testname -.br -.BI "\-\-test\-name " testname -.RS -Use test case name -.I 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. -.RE - -.B \-\-version -.RS -Print version number, then exit. -.RE - -.B \-\-tempdir -.I dirname -.br -.RS -Write temporary and intermediate data to indicated directory. Default is "/tmp". -.RE - - -.SH "TRACEFILE FORMAT" - -Following is a quick description of the tracefile format as used by -.BR genhtml ", " geninfo " and " lcov . - -A tracefile is made up of several human\-readable lines of text, -divided into sections. If the -.BI "--\-comment\ comment_string" -option is supplied, then - -.RS - #comment_string -.RE -will appear at the top of the tracefile. There is no space before or after the -.I # -character. - - -If available, a tracefile begins with the -.I testname -which is stored in the following format: - -.RS -TN: -.RE - -For each source file referenced in the .gcda file, there is a section containing -filename and coverage data: - -.RS -SF: -.RE - -An optional source code version ID follows: -.br - -.RS -VER: -.RE - -If present, the version ID is compared before file entries are merged (see -.B "lcov \-\-add\-tracefile" -), and before the 'source detail' view is generated by genhtml. -See the -.BI "\-\-version\-script " callback_script -documentation and the sample usage in the lcov regression test examples. - -Function coverage data follows. -Note that the format of the function coverage data has changed from LCOV 2.2 onward. -The tool continues to be able to read the old format but now writes only the -new format. -This change was made so that -.B function -filter outcome is persistent in the generated tracefile. - -Functions and their aliases are recorded contiguously: - -First, the leader: - -.RS -FNL:,[,line number of function end>] -.RE - -Then the aliases of the function; there will be at least one alias. All aliases of a particular function share the same index. - -.RS -FNA:,, -.RE - - -The now-obsolete function data format is: - -.RS - -.RS -FN:,[,] -.RE - -The 'end' line number is optional, and is generated only if the compiler/toolchain -version is recent enough to generate the data (e.g., gcc 9 or newer). -This data is used to support the -.B \-\-erase\-functions -and -.B \-\-show\-proportions -options. If the function end line data is not available, then these features will not work. - -Next, there is a list of execution counts for each instrumented function: - -.RS -FNDA:, -.RE -.RE - -This list is followed by two lines containing the number of functions found -and hit: - -.RS -FNF: -.br -FNH: -.RE - -Note that, as of LCOV 2.2, these numbers count function groups - not the individual aliases. - -Branch coverage information is stored one line per branch: - -BRDA:,[][],, - -.I -.RS -is the line number where the branch is found - and is expected to be a non-zero integer. -.RE -.br -.I -and -.I -.RS -serve to uniquely define a particular edge in the expression tree of a particular conditional found on the associated line. -.br -Within a particular line, -.I -is an integer numbered from zero with no gaps. For some languages and some coding styles, there will only be one block (index value zero) on any particular line. -.br -.I -is a string which serves to uniquely identify a particular edge. For some languages and tools - e.g., C/C++ code compiled with gcc or llvm - -.I -is an ordered integer index related to expression tree traversal order of the associated conditional. For others, it may be a meaningful string - see below. -.I -appears in the 'tooltip' popup of the associated branch in the -.B genhtml -output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage. -.RE -.br -.I -.RS -is either '-' if the corresponding expression was never evaluated (e.g., the basic block containing the branch was never executed) or -a number indicating how often that branch was taken. -.RE -.br -.I -.RS -is 'e' (single character) if this is a branch related to exception handling - and is not present if the branch is not related to exceptions. -Exception branch identification requires compiler support. geninfo will be able to identify exception branches only if your toolchain version is new enough to support the feature. -.RE -.br -.I -.RS -is 'f' (single character) if this is a branch is marked as 'fallthrough' (e.g., in the gcov output) - and is not present if the branch is not marked. -Fallthrough branch identification requires compiler support. geninfo will be able to identify fallthrough branches only if your toolchain version is new enough to support the feature. -A branch may be marked as '' or ' -.RS -is 'U' (single character) if this branch is associated with an 'unreachable directive, and is not present if the branch is reachable. -Unreachablility is intended to mark branch expressions which are should not appear in coverage reports - enabling users to ignore uncovered branches which can never be covered, to concentrate on other areas of the coverage report. -.br -See the -.I \"\-\-unreachable\-script\" -discussion in man -.B genhtml(1) -and the -.I \"ignore_unreachable_flag\" -discussion in man -.B lcovrc(5) -for more information on how branch exclusion markers are set and used. -.RE - -The following are example branch records whose -.I -expression values are human-readable strings. - -.RS - BRDA:10,0,enable,1 -.br - BRDA:10,0,!enable,0 -.RE -In this case, the corresponding code from line 10 is very likely similar to: -.br -.RS - if (enable) { -.br - ... -.br - } -.br -.RE -such that the associated testcase entered the block ('enable' evaluated to 'true'). - -Arbitrarily complicated branch expressions are supported - including branch expressions which contain commas ( -.I e.g., -in an expression containing a function call). - -Note that particular tools may or may not suppress expressions which are statically true or statically false - -.I e.g., -expressions using template parameters. -This makes it potentially complicated to compare coverage data generated by two different tools. - -A note on branch identification, matching, and merging: -.RS -As noted previously: lcov merely presents coverage data which is identified by other tools such as gcov. -Unfortunately, gcov (and other tools) do not produce sufficient information to uniquely identify branch expressions - so lcov is forced to use a heuristic solution based on the order of appearance as well as the number and type of individual branch elements - say, in the gcov output. - -lcov computes a 'signature' for each "". If the block ID and signature found while capturing data from multiple files or while merging coverage data - then the block is considered identical and corresponding expression counts are combined. -.br -Within a particular line, there may be one or more blocks with the same signature - for example, corresponding to independent branch expressions in function call arguments on that line, or to different macro or template expansion. -lcov keeps track of the order that branch blocks were found (say, in the gcov output or in an lcov .info file). - -When merging branch data on a particular line: - -.IP o 3 -Blocks which have different signatures are considered to be distinct. -.PP - -.IP o 3 -Blocks which have identical signatures are matched in order: the zeroth block with signature -.I s1 -in coverage DB A -is merged with the zeroth block with signature -.I s1 -in coverage DB B - and so on. -.PP - -.IP o 3 -If one or the other DB does not contain some signature, or one DB contains more blocks with the same signature: then those non-matching blocks are simply copied to the merged output. -.PP - -This heuristic can cause ambiguity in the generated report - especially for cases that a particular line expands in different ways in different compilation units - -.I e.g., -due to template or macro expansion. -In such cases, it may not be possible for lcov to know that some block whose signature and order appear to match, is not actually the same block. -It may be possible to refactor the code slightly to introduce explicit temporaries (on their own line) to resolve the ambiguity. -.RE - -Branch coverage summaries are stored in two lines: - -.RS -BRF: -.RS -Note that this count does not include 'excluded' branches. -Excluded branches -.I do -appear as BRDA records. -.RE - - -BRH: -.RS -Note that this count does not include 'excluded' branches. -Excluded branches -.I do -appear as BRDA records. -.RE - -.RE - -MC/DC information is stored one line per expression: - -MCDC:,[],,,, - -where: - -.I -.RS -is the line number where the condition is found - and is expected to be a non-zero integer. -.RE -.br -.I -and -.I -.RS -serve to uniquely define a particular element in the expression tree of a particular conditional found on the associated line. -.br -Within a particular line and group, -.RE -.I -.RS -is an integer numbered from zero to -.I - 1 -with no gaps. For some languages and some coding styles, there will only be one group on any particular line. -.RE -.br -.I -.RS -is either -.I "f" -or -.I "t", -indicating whether the condition is sensitive to the indicated change - that is, does the condition outcome change if the corresponding changes from 'false' to 'true' or from 'tru' to 'false, respectively. -.RE -.br - -.I -.RS -is a count - 0 (zero) if the expression was not senstized, non-zero if it was senstized. -Note that tome tools may treat -.I -as the number of times that the expression was sensitized where others may treat it -as a boolean - 1:sensitized or 0: not sensitized. -.RE - -.I -.RS -is an arbitrary string, intended to be a meaningful string which will help the user to understand the condition context - see below. -.I -appears in the 'tooltip' popup of the associated MC/DC condition in the -.B genhtml -output - so human-readable values are helpful to users who are trying to understand coverage results - for example, in order to develop additional regression tests, to improve coverage. -.br -For a given and , the should be identical for both -"t" and "f" senses. -.RE -.br - -.I -.RS -is 'U' (single character) if this condition is associated with an 'unreachable directive, and is not present if the condition is reachable. -Unreachability is intended to mark conditions which should not appear in coverage reports - enabling users to ignore uncovered conditions which can never be covered, to concentrate on other areas of the coverage report. -.br -See the -.I \"\-\-unreachable\-script\" -discussion in man -.B genhtml(1) -and the -.I \"ignore_unreachable_flag\" -discussion in man -.B lcovrc(5) -for more information on how branch exclusion markers are set and used. -.RE -.RE -.br - -The following are example MC/DC records whose -.I -values are human-readable strings. - -.RS - MCDC:10,2,f,0,0,enable -.br - MCDC:10,2,t,1,0,enable -.br - ... -.RE -In this case, the corresponding code from line 10 is very likely similar to: -.br -.RS - if (enable ...) { -.br - ... -.br - } -.br -.RE -such that the associated testcase was sensitive to a change of 'enable' from true to false (but not the converse). - -Arbitrarily complicated expressions are supported - including expressions which contain commas ( -.I e.g., - in an expression containing a function call). - -Note that particular tools may or may not suppress expressions which are statically true or statically false - -.I e.g., -expressions using template parameters. -This makes it potentially complicated to compare coverage data generated by two different tools. - - -MCDC coverage summaries are stored in two lines: - -.RS -MCF: -.RS -Note that this count does not include 'excluded' conditions -Excluded branches -.I do -appear as MCDC records. -.RE - -MCH: -.RS -Note that this count does not include 'excluded' conditions -Excluded branches -.I do -appear as MCDC records. -.RE - -.RE - - -Then there is a list of execution counts for each instrumented line -(i.e. a line which resulted in executable code): - -.RS -DA:,[,] -.RE - -Note that there may be an optional checksum present for each instrumented -line. The current -.B 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: - -.RS -LH: -.br -LF: -.RE - -Each sections ends with: - -.RS -end_of_record -.RE - -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 interpreting -the contents of the respective .gcno file (see -.BR "gcov " (1) -for more information on this file type). Relative filenames are prefixed -with the directory in which the .gcno file is found. - -Note also that symbolic links to the .gcno file will be resolved so that the -actual file path is used instead of the path to a link. This approach is -necessary for the mechanism to work with the /proc/gcov files. - - -.SH FILES - -.I /etc/lcovrc -.RS -The system\-wide configuration file. -.RE - -.I ~/.lcovrc -.RS -The per\-user configuration file. -.RE - -.I \*[scriptdir]/getp4version -.RS -Sample script for use with -.B --version-script -that obtains version IDs via Perforce. -.br -.RE - -.I \*[scriptdir]/get_signature -.RS -Sample script for use with -.B --version-script -that uses md5hash as version IDs. -.br -.RE - - -.SH AUTHOR -Peter Oberparleiter - -Henry Cox -.RS -Filtering, error management, parallel execution sections. -.RE - -.SH SEE ALSO -.BR lcov (1), -.BR lcovrc (5), -.BR genhtml (1), -.BR genpng (1), -.BR gendesc (1), -.BR gcov (1) -.br - -.I \*[lcovurl] -.br diff --git a/man/genpng.1 b/man/genpng.1 deleted file mode 100644 index b5f2ab92..00000000 --- a/man/genpng.1 +++ /dev/null @@ -1,115 +0,0 @@ -\" Define project URL -.ds lcovurl https://github.com/linux\-test\-project/lcov - -.TH genpng 1 "LCOV 2.0" 2023\-05\-12 "User Manuals" -.SH NAME -genpng \- Generate an overview image from a source file -.SH SYNOPSIS -.B genpng -.RB [ \-h | \-\-help ] -.RB [ \-v | \-\-version ] -.RS 7 -.br -.RB [ \-t | \-\-tab\-size -.IR tabsize ] -.RB [ \-w | \-\-width -.IR width ] -.RB [ \-d | \-\-dark\-mode ] -.br -.RB [ \-o | \-\-output\-filename -.IR output\-filename ] -.br -.IR source\-file -.SH DESCRIPTION -.B genpng -creates an overview image for a given source code file of either -plain text or .gcov file format. - -Note that the -.I GD.pm -Perl module has to be installed for this script to work -(it may be obtained from -.IR http://www.cpan.org ). - -Note also that -.B genpng -is called from within -.B genhtml -so that there is usually no need to call it directly. - -.SH OPTIONS -.B \-h -.br -.B \-\-help -.RS -Print a short help text, then exit. -.RE - -.B \-v -.br -.B \-\-version -.RS -Print version number, then exit. -.RE - -.BI "\-t " tab\-size -.br -.BI "\-\-tab\-size " tab\-size -.RS -Use -.I tab\-size -spaces in place of tab. - -All occurrences of tabulator signs in the source code file will be replaced -by the number of spaces defined by -.I tab\-size -(default is 4). -.RE - -.BI "\-w " width -.br -.BI "\-\-width " width -.RS -Set width of output image to -.I width -pixel. - -The resulting image will be exactly -.I width -pixel wide (default is 80). - -Note that source code lines which are longer than -.I width -will be truncated. -.RE - -.B \-d -.br -.B \-\-dark\-mode -.RS -Use a light-display-on-dark-background color scheme rather than the default dark-display-on-light-background. -.RE - -.BI "\-o " filename -.br -.BI "\-\-output\-filename " filename -.RS -Write image to -.IR filename . - -Specify a name for the resulting image file (default is -.IR source\-file .png). -.RE -.SH AUTHOR -Peter Oberparleiter - -.SH SEE ALSO -.BR lcov (1), -.BR genhtml (1), -.BR geninfo (1), -.BR gendesc (1), -.BR gcov (1) -.br - -.I \*[lcovurl] -.br diff --git a/man/lcov.1 b/man/lcov.1 deleted file mode 100644 index f205ed45..00000000 --- a/man/lcov.1 +++ /dev/null @@ -1,1992 +0,0 @@ -\" Define project URL -.ds lcovurl https://github.com/linux\-test\-project/lcov - -.TH lcov 1 "LCOV 2.0" 2023\-05\-17 "User Manuals" -.SH NAME -lcov \- a graphical GCOV front\-end -.SH SYNOPSIS - -Capture coverage data tracefile (from compiler-generated data). -.br -The lcov tracefile -.I (".info" file) -format is described in man -.B geninfo(1). - -.br - -.RS 3 -.B lcov -.BR \-c | \-\-capture -.RS 4 -.br -.RB [ \-d | \-\-directory -.IR directory ] -.RB [ \-k | \-\-kernel\-directory -.IR directory ] -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.RB [ \-t | \-\-test\-name -.IR testname ] -.br -.RB [ \-b | \-\-base\-directory -.IR directory ] -.br -.RB [ \-\-build\-directory -.IR directory ] -.br -.RB [ \-\-source\-directory -.IR directory ] -.br -.RB [ \-i | \-\-initial ] -.br -.RB [ \-\-all ] ] -.br -.RB [ \-\-gcov\-tool -.IR tool ] -.br -.RB [ \-\-branch\-coverage ] -.br -.RB [ \-\-mcdc\-coverage ] -.br -.RB [ \-\-demangle\-cpp -.IR [ param ] ] -.br -.RB [ \-\-checksum ] -.RB [ \-\-no\-checksum ] -.RB [ \-\-no\-recursion ] -.RB [ \-f | \-\-follow ] -.br -.RB [ \-\-sort\-input ] -.br -.RB [ \-\-compat\-libtool ] -.RB [ \-\-no\-compat\-libtool ] -.br -.RB [ \-\-msg\-log -.IR [ log_file_name ] ] -.br -.RB [ \-\-ignore\-errors -.IR errors ] -.br -.RB [\-\-expect\-message\-count -.IR message_type=expr[,message_type=expr..]] -.br -.RB [ \-\-preserve ] -.RB [ \-\-to\-package -.IR package ] -.RB [ \-\-from\-package -.IR package ] -.RB [ \-\-no\-markers ] -.RB [ \-\-external ] -.RB [ \-\-no\-external ] -.br -.RB [ \-\-compat -.IR mode =on|off|auto] -.br -.RB [ \-\-context\-script -.IR script_file ] -.br -.RB [ \-\-criteria\-script -.IR script_file ] -.br -.RB [ \-\-history\-script -.IR callback ] -.br -.RB [ \-\-resolve-\-script -.IR script_file ] -.br -.RB [ \-\-version\-script -.IR script_file ] -.br -.RB [ \-\-unreachable\-script -.IR callback ] -.br -.RB [ \-\-comment -.IR comment_string ] -.br -.RB [ \-\-large\-file -.IR regexp ] -.br -.RE -RE - -Generate tracefile (from compiler-generated data) with all counter values set to zero: -.br - -.RS 3 -.B lcov -.BR \-z | \-\-zerocounters -.RS 4 -.br -.RB [ \-d | \-\-directory -.IR directory ] -.RB [ \-\-no\-recursion ] -.RB [ \-f | \-\-follow ] -.br -.RE -.RE - -Show coverage counts recorded in previously generated tracefile: -.br - -.RS 3 -.B lcov -.BR \-l | \-\-list -.I tracefile -.RS 4 -.br -.RB [ \-\-list\-full\-path ] -.RB [ \-\-no\-list\-full\-path ] -.br -.RE -.RE - -Aggregate multiple coverage tracefiles into one: -.br - -.RS 3 -.B lcov -.BR \-a | \-\-add\-tracefile -.I tracefile_pattern -.RS 4 -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.br -.RB [ \-\-prune\-tests ] -.br -.RB [ \-\-forget\-test\-names ] -.br -.RB [ \-\-map\-functions ] -.br -.RB [ \-\-branch\-coverage ] -.br -.RB [ \-\-mcdc\-coverage ] -.br -.RB [ \-\-checksum ] -.RB [ \-\-no\-checksum ] -.br -.RB [ \-\-sort\-input ] -.br -.RE - -Depending on your use model, it may not be necessary to create aggregate coverage data files. -For example, if your regression tests are split into multiple suites, you may want to keep separate suite data and to compare both per-suite and aggregate results over time. -.B genhtml -allows you specify tracefiles via one or more glob patterns - which enables you -generate aggregate reports without explicitly generating aggregated trace files. -See the -.B genhtml -man page. -.RE - - -Generate new tracefile from existing tracefile, keeping only data from files matching pattern: -.br - -.RS 3 -.B lcov -.BR \-e | \-\-extract -.I tracefile pattern -.RS 4 -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.RB [ \-\-checksum ] -.RB [ \-\-no\-checksum ] -.br -.RE -.RE - -Generate new tracefile from existing tracefile, removing data from files matching pattern: -.br - -.RS 3 -.B lcov -.BR \-r | \-\-remove -.I tracefile pattern -.RS 4 -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.RB [ \-\-checksum ] -.RB [ \-\-no\-checksum ] -.br -.RE -.RE - -Generate new tracefile from existing tracefiles by performing set operations on coverage data: -.br - -.RS 3 -.B lcov -.BR \-\-intersect -.I rh_glob_pattern -.RS 4 -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.br -lh_glob_pattern - - -The output will reflect -.RS 2 -.I (union of files matching lh_glob_patterns) -.I intersect -.I (union of files matching rh_glob_patterns) -.RE -such that coverpoints found in both sets are merged (summed) whereas coverpoints found in only one set are dropped. -Note that branch blocks are defined to be the same if and only if their block ID and the associated branch expressions list are identical. -Functions are defined to be the same if their name and location are identical. -.RE -.RE - -.RS 3 -.B lcov -.BR \-\-subtract -.I rh_glob_pattern -.RS 4 -.br -.RB [ \-o | \-\-output\-file -.IR tracefile ] -.br -lh_glob_pattern - -The output will reflect -.RS 2 -.I (union of files matching lh_glob_patterns) -.I subtract -.I (union of files matching rh_glob_patterns) -.RE -such that coverpoints found only in the set on the left will be retained and all others are dropped. -.RE - -.RE - - -Summarize tracefile content: -.br - -.RS 3 -.B lcov -.BR \-\-summary -.I tracefile -.RE - -Print version or help message and exit: -.br - -.RS 3 -.B lcov -.RB [ \-h | \-\-help ] -.RB [ \-\-version ] -.RE - -Common lcov options - supported by all the above use cases: -.br - -.RS 3 -.B lcov -.RB [ \-\-keep\-going ] -.br -.RS 5 -.RB [ \-\-filter -.IR type ] -.br -.br -.RB [ \-q | \-\-quiet ] -.br -.RB [ \-v | \-\-verbose ] -.br -.RB [ \-\-comment -.IR comment_string ] -.br -.RB [ \-\-debug ] -.br -.RB [ \-\-parallel | -j -.IR [integer] ] -.br -.RB [ \-\-memory -.IR integer_num_Mb ] -.br -.RB [ \-\-tempdir -.IR dirname ] -.br -.RB [ \-\-branch\-coverage ] -.br -.RB [ \-\-mcdc\-coverage ] -.br -.RB [ \-\-config\-file -.IR config\-file ] -.RB [ \-\-rc -.IR keyword = value ] -.br -.RB [ \-\-profile -.IR [ profile\-file ] ] -.br -.RB [ \-\-include -.IR glob_pattern ] -.br -.RB [ \-\-exclude -.IR glob_pattern ] -.br -.RB [ \-\-erase\-functions -.IR regexp_pattern ] -.br -.RB [ \-\-substitute -.IR regexp_pattern ] -.br -.RB [ \-\-omit\-lines -.IR regexp_pattern ] -.br -.RB [ \-\-fail\-under\-branches -.IR percentage ] -.br -.RB [ \-\-fail\-under\-lines -.IR percentage ] -.br -.RE -.RE - -.SH DESCRIPTION -.B lcov -is a graphical front\-end for GCC's coverage testing tool gcov. It collects -line, function and branch coverage data for multiple source files and creates -HTML pages containing the source code annotated with coverage information. -It also adds overview pages for easy navigation within the file structure. - -Use -.B lcov -to collect coverage data and -.B genhtml -to create HTML pages. Coverage data can either be collected from the -currently running Linux kernel or from a user space application. To do this, -you have to complete the following preparation steps: - -For Linux kernel coverage: -.RS -Follow the setup instructions for the gcov\-kernel infrastructure: -.I https://docs.kernel.org/dev-tools/gcov.html -.br -.RE - -For user space application coverage: -.RS 3 -Compile the application with GCC using the options -"\-fprofile\-arcs" and "\-ftest\-coverage" or "\-\-coverage". -.RE - -Please note that this man page refers to the output format of -.B lcov -as ".info file" or "tracefile" and that the output of GCOV -is called ".da file". - -Also note that when printing percentages, 0% and 100% are only printed when -the values are exactly 0% and 100% respectively. Other values which would -conventionally be rounded to 0% or 100% are instead printed as nearest -non-boundary value. This behavior is in accordance with that of the -.BR gcov (1) -tool. - -By default, -.B lcov -and related tools generate and collect line and function coverage data. -Branch data is not collected or displayed by default; all tools support the -.B\ \--branch\-coverage -and -.B \-\-mdcd\-coverage -options to enable branch and MC/DC coverage, respectively - or you can permanently enable branch coverage by adding the appropriate -settings to your personal, group, or site lcov configuration file. See man -.B lcovrc(5) -for details. - -.SH OPTIONS - -In general, (almost) all -.B lcov -options can also be specified in a configuration file - see man -.B lcovrc(5) -for details. - - -.B \-a -.I tracefile_pattern -.br -.B \-\-add\-tracefile -.I tracefile_pattern -.br -.RS -Add contents of all files matching glob pattern -.IR tracefile_pattern. - -Specify several tracefiles using the \-a switch to combine the coverage data -contained in these files by adding up execution counts for matching test and -filename combinations. - -The result of the add operation will be written to stdout or the tracefile -specified with \-o. - -Only one of \-z, \-c, \-a, \-e, \-r, \-l or \-\-summary may be -specified at a time. - -.RE - -.B \-b -.I directory -.br -.B \-\-base\-directory -.I directory -.br -.RS -.RI "Use " directory -as base directory for relative paths. - -Use this option to specify the base directory of a build\-environment -when lcov produces error messages like: - -.RS -ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c -.RE - -In this example, use /home/user/project as base directory. - -This option is required when using lcov on projects built with libtool or -similar build environments that work with a base directory, i.e. environments, -where the current working directory 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 multiple base -directories are used. In that case use configuration file setting -.B geninfo_auto_base=1 -(see man -.BR lcovrc (5) -). - -.RE - -.B \-\-build\-directory -.I build_directory -.br -.RS -search for .gcno data files from build_directory rather than -adjacent to the corresponding .gcda file. - -See man -.BR geninfo (1)) -for details. - - -.RE -.BI "\-\-source\-directory " dirname -.RS -Add 'dirname' to the list of places to look for source files. -.br - -For relative source file paths listed in -.I e.g. -paths found in -.IR tracefile, -or found in gcov output during -.I \-\-capture -\- possibly after substitutions have been applied - -.B lcov - will first look for the path from 'cwd' (where genhtml was -invoked) and -then from each alternate directory name in the order specified. -The first location matching location is used. - -This option can be specified multiple times, to add more directories to the source search path. - - -.RE -.B \-c -.br -.B \-\-capture -.br -.RS -Capture runtime coverage data. - -By default captures the current kernel execution counts and writes the -resulting coverage data to the standard output. Use the \-\-directory -option to capture counts for a user space program. - -The result of the capture operation will be written to stdout or the tracefile -specified with \-o. - -When combined with the -.BR \-\-all -flag, both runtime and compile-time coverage will be extracted in one step. -See the description of the -.BR \-\-initial -flag, below. - -See man -.BR geninfo (1)) -for more details about the capture process and available options and parameters. - - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-\-branch\-coverage -.RS -.br -Collect and/or retain branch coverage data. - -This is equivalent to using the option "\-\-rc branch_coverage=1"; the option was added to better match the genhml interface. - -.RE - -.B \-\-mcdc\-coverage -.RS -.br -Collect retain MC/DC data. - -This is equivalent to using the option "\-\-rc mcdc_coverage=1". -MC/DC coverage is supported for GCC versions 14.2 and higher, or -LLVM 18.1 and higher. -.br -See -.I llvm2lcov \-\-help -for details on MC/DC data capture in LLVM. - -.br -See the MC/DC section of man -.B genhtml(1) -for more details - -.RE - -.B \-\-checksum -.br -.B \-\-no\-checksum -.br -.RS -Specify whether to generate checksum data when writing tracefiles and/or to -verify matching checksums when combining trace files. - -Use \-\-checksum to enable checksum generation or \-\-no\-checksum to -disable it. Checksum generation is -.B disabled -by default. - -When checksum generation is enabled, a checksum will be generated for each -source code line and stored along with the coverage data. This checksum will -be used to prevent attempts to combine 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. - -Note that this options is somewhat subsumed by the -.B \-\-version\-script -option - which does something similar, but at the 'whole file' level. -.RE - -.B \-\-compat -.IR mode = value [, mode = value ,...] -.br -.RS -Set compatibility mode. - -Use \-\-compat to specify that lcov should enable one or more compatibility -modes when capturing coverage data. You can provide a comma-separated list -of mode=value pairs to specify the values for multiple modes. - -Valid -.I values -are: - -.B on -.RS -Enable compatibility mode. -.RE -.B off -.RS -Disable compatibility mode. -.RE -.B auto -.RS -Apply auto-detection to determine if compatibility mode is required. Note that -auto-detection is not available for all compatibility modes. -.RE - -If no value is specified, 'on' is assumed as default value. - -Valid -.I modes -are: - -.B libtool -.RS -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'. - -.RE -.B hammer -.RS -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 versions. 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'. - -.RE -.B split_crc -.RS -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 lcov 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' -.RE - -.RE - -.B \-\-compat\-libtool -.br -.B \-\-no\-compat\-libtool -.br -.RS -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 -.B enabled -by default. - -When libtool compatibility mode is enabled, lcov will assume that the source -code relating to a .da file located in a directory 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. -.RE - -.B \-\-config\-file -.I config\-file -.br -.RS -Specify a configuration file to use. -See man -.B lcovrc(5) -for details of the file format and options. Also see the -.I config_file -entry in the same man page for details on how to include one config file into -another. - -When this option is specified, neither the system\-wide configuration 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 -.B lcov -with different configuration file options in parallel. - -Note that this option must be specified in full - abbreviations are not supported. - -.RE - -.B \-\-profile -.I [ profile\-data\-file ] -.br -.RS -Tell the tool to keep track of performance and other configuration data. -If the optional -.I profile\-data\-file -is not specified, then the profile data is written to a file named with the same -basename as the -.I \-\-output\-filename, with suffix -.I ".json" -appended. -Profile data is useful if you are trying to optimize the -.B lcov -implementation (see -.B $LCOV_ROOT/share/lcov/support\-scripts/spreadsheet.py -), and can also enable faster -.I --parallel -execution (see the -.I "\-\-history\-script" - section of this man page). - -.B \-\-history-script -.I callback -.br -.RS -Use -.I callback -to predict current runtime cost using observed cost from prior execution. - -See man -.B genhtml(1) -for more information. -.RE - - -.RE - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-d -.I directory -.br -.B \-\-directory -.I directory -.br -.RS -Use .da files in -.I directory -instead of kernel. - -If you want to work on coverage data for a user space program, use this -option to specify the location where the program was compiled (that's -where the counter files ending with .da will be stored). - -Note that you may specify this option more than once. -.RE - -.B \-\-exclude -.I pattern -.br -.RS -Exclude source files matching -.IR pattern . - -Use this switch if you want to exclude coverage data for a particular set -of source files matching any of the given patterns. Multiple patterns can be -specified by using multiple -.B --exclude -command line switches. The -.I patterns -will be interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). - -Note: The pattern must be specified to match the -.B absolute -path of each source file. -If you specify a pattern which does not seem to be correctly applied - files that you expected to be excluded still appear in the output - you can look for warning messages in the log file. -.B lcov -will emit a warning for every pattern which is not applied at least once. - -Can be combined with the -.B --include -command line switch. If a given file matches both the include pattern and the -exclude pattern, the exclude pattern will take precedence. -.RE - -.B \-\-erase\-functions -.I regexp -.br -.RS -Exclude coverage data from lines which fall within a function whose name matches the supplied regexp. Note that this is a mangled or demangled name, depending on whether the \-\-demangle\-cpp option is used or not. - -Note that this option requires that you use a gcc version which is new enough to support function begin/end line reports or that you configure the tool to derive the required dta - see the -.BI derive_function_end_line -discussion in man -.B lcovrc(5). - -.RE -.B \-\-substitute -.I regexp_pattern -.br -.RS -Apply Perl regexp -.IR regexp_pattern -to source file names found during processing. This is useful, for example, when the path name reported by gcov does not match your source layout and the file is not found, or in more complicated environments where the build directory structure does not match the source code layout or the layout in the projects's revision control system. - -Use this option in situations where geninfo cannot find the correct -path to source code files of a project. By providing a -.I regexp_pattern -in Perl regular expression format (see man -.BR perlre (1) -), you can instruct geninfo to -remove or change parts of the incorrect source path. -Also see the -.B \-\-resolve\-script -option. - -One or more -.I \-\-substitution -patterns and/or a -.I \-\-resolve-script -may be specified. When multiple patterns are specified, they are applied in the order specified, substitution patterns first followed by the resolve callback. -The file search order is: -.RS -.IP 1. 3 -Look for file name (unmodified). -.br -If the file exits: return it. -.PP -.IP 2. 3 -Apply all substitution patterns in order - the result of the first pattern is used as the input of the second pattern, and so forth. -.br -If a file corresponding to the resulting name exists: return it. -.PP -.IP 3. 3 -Apply the 'resolve' callback to the final result of pattern substitutions. -.br -If a file corresponding to the resulting name exists: return it. -.PP -.IP 4. 3 -Otherwise: return original (unmodified) file name. -.br -Depending on context, the unresolved file name may or may not result in an error. -.RE - -Substitutions are used in multiple contexts by lcov/genhtml/geninfo: -.RS -.IP \- 3 -during -.I \-\-capture, -applied to source file names found in gcov-generated coverage data files (see man -.B gcov(1) -). -.PP - -.IP \- 3 -during -.I \-\-capture, -applied to alternate -.I \-\-build\-dir -paths, when looking for the -.I .gcno -(compile time) data file corresponding to some -.I .gcda -(runtime) data file. -.PP - -.IP \- 3 -applied to file names found in lcov data files (".info" files) - -.I e.g., -during lcov data aggregation or HTML and text report generation. -.br -For example, substituted names are used to find source files for -text-based filtering (see the -.I \-\-filter -section, below) and are passed to -.I \-\-version\-script, \-\-annotate\-script, -and -.I \-criteria\-script -callbacks. -.PP - -.IP \- 3 -applied to file names found in the -.I \-\-diff\-file -passed to genhtml. -.PP -.RE - - -.B Example: -.br - -1. When geninfo reports that it cannot find source file -.br - - /path/to/src/.libs/file.c -.br - -while the file is actually located in -.br - - /path/to/src/file.c -.br - -use the following parameter: -.br - - \-\-substitute 's#/.libs##g' - -This will remove all "/.libs" strings from the path. - -2. When geninfo reports that it cannot find source file -.br - - /tmp/build/file.c -.br - -while the file is actually located in -.br - - /usr/src/file.c -.br - -use the following parameter: -.br - - \-\-substitute 's#/tmp/build#/usr/src#g' -.br - -This will change all "/tmp/build" strings in the path to "/usr/src". -.PP - -.RE - -.B \-\-omit\-lines -.I regexp -.br -.RS -Exclude coverage data from lines whose content matches -.IR regexp . - -Use this switch if you want to exclude line and branch coverage data for some particular constructs in your code (e.g., some complicated macro). Multiple patterns can be -specified by using multiple -.B --omit\-lines -command line switches. The -.I regexp -will be interpreted as perl regular expressions (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). -If you want the pattern to explicitly match from the start or end of the line, your regexp should start and/or end with "^" and/or "$". - -Note that the -.B lcovrc -config file setting -.B lcov_excl_line = regexp -is similar to -.B \-\-omit\-lines. -.B \-\-omit\-lines -is useful if there are multiple teams each of which want to exclude certain patterns. -.B \-\-omit\-lines -is additive and can be specified across multiple config files whereas each call to -.B lcov_excl_line -overrides the previous value - and thus teams must coordinate. - -.RE - -.B \-\-external -.br -.B \-\-no\-external -.br -.RS -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 -.I \-\-directory -or -.I \-\-base\-directory. -Use -.I \-\-external -to include -coverpoints in external source files while capturing coverage data or -.I \-\-no\-external -to exclude them. -If your -.I \-\-directory -or -.I \-\-base\-directory -path contains a soft link, then actual target directory is not considered to be -"internal" unless the -.I \-\-follow -option is used. - -The -.I \-\-no\-external -option is somewhat of a blunt instrument; the -.I \-\-exclude -and -.I \-\-include -options provide finer grained control over which coverage data is and is not -included if your project structure is complex and/or -.I \-\-no\-external -does not do what you want. - -Data for external source files is -.B included -by default. - -.RE - -.B \-\-forget\-test\-names -.br -.RS -If non\-zero, ignore testcase names in .info file - -.I i.e., -treat all coverage data as if it came from the same testcase. -This may improve performance and reduce memory consumption if user does -not need per-testcase coverage summary in coverage reports. - -This option can also be configured permanently using the configuration file -option -.IR forget_testcase_names . - -.RE - -.B \-\-prune\-tests -.br -.RS -Determine list of unique tracefiles. - -Use this option to determine a list of unique tracefiles from the list -specified by -.BR \-\-add\-tracefile . -A tracefile is considered to be unique if it is the only tracefile that: - -.RS - -.IP 1. 3 -contains data for a specific source file -.br -.PP -.IP 2. 3 -contains data for a specific test case name -.br -.PP -.IP 3. 3 -contains non-zero coverage data for a specific line, function or branch -.br -.PP - -.RE - -Note that the list of retained files may depend on the order they are processed. For example, if -.I A -and -.I B -contain identical coverage data, then the first one we see will be retained and the second will be pruned. -The file processing order is nondeterministic when the -.BR \-\-parallel -option is used - implying that the pruned result may differ from one execution to the next in this case. - -.BR \-\-prune\-tests must be specified together with -.BR \-\-add\-tracefile . -When specified, -.B lcov -will emit the list of unique files rather than combined tracefile data. -.br - -.RE - -.B \-\-map\-functions -.br -.RS -List tracefiles with non-zero coverage for each function. -.br - -Use this option to determine the list of tracefiles that contain non-zero -coverage data for each function from the list of tracefiles specified by -.BR \-\-add\-tracefile . - -This option must be specified together with -.BR \-\-add\-tracefile . -When specified, -.B lcov -will emit the list of functions and associated tracefiles rather than combined tracefile data. -.br - -.RE -.B \-\-context\-script -.I script -.br -.RS - -Use -.I script -to collect additional tool execution context information - to aid in -infrastructure debugging and/or tracking. - -See the genhtml man page for more details on the context script. - -.br - -.RE -.B \-\-criteria\-script -.I script -.br -.RS - -Use -.I script -to test for coverage acceptance criteria. - -See the genhtml man page for more details on the criteria script. -Note that lcov does not keep track of date and owner information (see the -.I \-\-annotate\-script -entry in the genhtml man page) - so this information is not passed to the lcov callback. - -.br - -.RE -.B \-\-resolve\-script -.I script -.br -.RS -Use -.I script -to find the file path for some source file which appears in -an input data file if the file is not found after applying -.I \-\-substitute -patterns and searching the -.I \-\-source\-directory -list. This option is equivalent to the -.B resolve_script -config file option. See man -.B lcovrc(5) -for details. -.RE - -.RE -.B \-\-version\-script -.I script -.br -.RS - -Use -.I script -to get a source file's version ID from revision control when -extracting data and to compare version IDs for the purpose of error checking when merging .info files. -.br - -See the genhtml man page for more details on the version script. - -.br - -.RE -.B \-\-unreachable\-script -.I module -.br -.RS - -Use -.I module -to decide whether particular branch expressions and/or MC/DC conditions -should be removed from the coverage report. -This option is equivalent to the -.B unreachable_script -config file option. See man -.B lcovrc(5) -for details. - -Note that -.I \"module\" -is required to be a Perl module. - -See the genhtml man page for more details. - -.br - -.RE -.B \-\-comment -.I comment_string -.br -.RS - -Append -.I comment_string -to list of comments emitted into output result file. -This option may be specified multiple times. -Comments are printed at the top of the file, in the order they were specified. - -Comments may be useful to document the conditions under which the trace file was -generated: host, date, environment, -.I etc. - -Note that this option has no effect for lcov overations which do not write an -output result file: -.I \-\-list -.I \-\-summary, -.I \-\-prune\-tests, -and -.I \-\-map\-functions. - -See the -.B geninfo -man page for a description of the comment format in the result file. - -.RE - -.B \-e -.I tracefile -.I pattern -.br -.B \-\-extract -.I tracefile -.I pattern -.br -.RS -Extract data from -.IR tracefile . - -Use this switch if you want to extract coverage data for only a particular -set of files from a tracefile. Additional command line parameters will be -interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). -Every file entry in -.I tracefile -which matches at least one of those patterns will be extracted. - -Note: The pattern must be specified to match the -.B absolute -path of each source file. - -The result of the extract operation will be written to stdout or the tracefile -specified with \-o. - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-f -.br -.B \-\-follow -.br -.RS -Follow links when searching for .da files. -.RE - -.BI "\-\-large\-file " -.I regexp -.RS -See the -.I \-\-large\-file -section of man -.B geninfo(1) -for details. -.RE - -.B \-\-from\-package -.I package -.br -.RS -Use .da files in -.I package -instead of kernel or directory. - -Use this option if you have separate machines for build and test and -want to perform the .info file creation on the build machine. See -\-\-to\-package for more information. -.RE - -.B \-\-sort\-input -.br -.RS -Specify whether to sort file names before capture and/or aggregation. -Sorting reduces certain types of processing order-dependent output differences. -See the -.BI sort_input -section in -man -.B lcovrc(5). - -.RE - -.B \-\-gcov\-tool -.I tool -.br -.RS -Specify the location of the gcov tool. - -See the geninfo man page for more details. -.RE - -.B \-h -.br -.B \-\-help -.br -.RS -Print a short help text, then exit. -.RE - -.B \-\-include -.I pattern -.br -.RS -Include source files matching -.IR pattern . - -Use this switch if you want to include coverage data for only a particular set -of source files matching any of the given patterns. Multiple patterns can be -specified by using multiple -.B --include -command line switches. The -.I patterns -will be interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). - -Note: The pattern must be specified to match the -.B absolute -path of each source file. -.br - -If you specify a pattern which does not seem to be correctly applied - files that you expected to be included in the output do not appear - lcov will generate an error message of type 'unused'. See the \-\-ignore\-errors option for how to make lcov ignore the error or turn it into a warning. -.RE - -.B \-\-msg\-log -.I [ log_file_name ] -.br -.RS -Specify location to store error and warning messages (in addition to writing to STDERR). -If -.I log_file_name -is not specified, then default location is used. -.RE - -.B \-\-ignore\-errors -.I errors -.br -.RS -Specify a list of errors after which to continue processing. - -Use this option to specify a list of one or more classes of errors after which -lcov should continue processing instead of aborting. -Note that the tool will generate a warning (rather than a fatal error) unless you ignore the error two (or more) times: -.br -.RS -lcov ... --ignore-errors source,source ... -.RE - -.I errors -can be a comma\-separated list of the following keywords: - -.IP branch: 3 -branch ID (2nd field in the .info file 'BRDA' entry) does not follow expected integer sequence. -.PP - -.IP callback: 3 -Version script error. -.PP - -.IP child: 3 -child process returned non-zero exit code during -.I \-\-parallel -execution. This typically indicates that the child encountered an error: see the log file immediately above this message. -In contrast: the -.B parallel -error indicates an unexpected/unhandled exception in the child process - not a 'typical' lcov error. -.PP - -.IP corrupt: 3 -corrupt/unreadable file found. -.PP - -.IP count: 3 -An excessive number of messages of some class have been reported - subsequent messages of that type will be suppressed. -The limit can be controlled by the 'max_message_count' variable. See man -.B lcovrc(5). -.PP - -.IP deprecated: 3 -You are using a deprecated option. -This option will be removed in an upcoming release - so you should change your -scripts now. -.PP - -.IP empty: 3 -the .info data file is empty (e.g., because all the code was 'removed' or excluded. -.PP - -.IP excessive: 3 -your coverage data contains a suspiciously large 'hit' count which is unlikely -to be correct - possibly indicating a bug in your toolchain. -See the -.I excessive_count_threshold -section in man -.B lcovrc(5) -for details. -.PP - -.IP fork: 3 -Unable to create child process during -.I \-\-parallel -execution. -.br -If the message is ignored ( -.I \-\-ignore\-errors fork -), then genhtml -will wait a brief period and then retry the failed execution. -.br -If you see continued errors, either turn off or reduce parallelism, set a memory limit, or find a larger server to run the task. -.PP - -.IP format: 3 -Unexpected syntax or value found in .info file - for example, negative number or -zero line number encountered. -.PP - -.IP gcov: 3 -the gcov tool returned with a non\-zero return code. -.PP - -.IP graph: 3 -the graph file could not be found or is corrupted. -.PP - -.IP inconsistent: 3 -your coverage data is internally inconsistent: it makes two or more mutually -exclusive claims. For example, some expression is marked as both an exception branch and not an exception branch. (See man -.B genhtml(1) -for more details. -.PP - -.IP internal: 3 -internal tool issue detected. Please report this bug along with a testcase. -.PP - -.IP mismatch: 3 -Inconsistent entries found in trace file: - - -.RS 3 -.IP \(bu 3 -branch expression (3rd field in the .info file 'BRDA' entry) of merge data does not match, or -.PP -.IP \(bu 3 -function execution count (FNDA:...) but no function declaration (FN:...). -.PP -.RE -.PP - -.IP missing: 3 -File does not exist or is not readable. -.PP - -.IP negative: 3 -negative 'hit' count found. - -Note that negative counts may be caused by a known GCC bug - see - - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 - -and try compiling with "-fprofile-update=atomic". You will need to recompile, re-run your tests, and re-capture coverage data. -.PP - -.IP package: 3 -a required perl package is not installed on your system. In some cases, it is possible to ignore this message and continue - however, certain features will be disabled in that case. -.PP - -.IP parallel: 3 -various types of errors related to parallelism - -.I i.e., -a child process died due to an error. The corresponding error message appears in the log file immediately before the -.I parallel -error. - -If you see an error related to parallel execution that seems invalid, it may be a good idea to remove the \-\-parallel flag and try again. If removing the flag leads to a different result, please report the issue (along with a testcase) so that the tool can be fixed. -.PP - -.IP parent: 3 -the parent process exited while child was active during -.I \-\-parallel -execution. This happens when the parent has encountered a fatal error - -.I e.g. -an error in some other child which was not ignored. This child cannot continue working without its parent - and so will exit. -.PP - -.IP range: 3 -Coverage data refers to a line number which is larger than the number of -lines in the source file. This can be caused by a version mismatch or -by an issue in the -.I gcov -data. -.PP - -.IP source: 3 -the source code file for a data set could not be found. -.PP - -.IP unreachable: 3 -a coverpoint (line, branch, function, or MC/DC) within an "unreachable" region is executed (hit); either the code, directive placement, or both are wrong. -If the error is ignored, the offending coverpoint is retained (not excluded) or not, depending on the value of the -.I retain_unreachable_coverpoints_if_executed -configuration parameter. -See man -.B lcovrc(5) -and the -.I "Exclusion markers" -section of man -.B geninfo(1) -for more information. -.PP - -.IP unsupported: 3 -the requested feature is not supported for this tool configuration. For example, function begin/end line range exclusions use some GCOV features that are not available in older GCC releases. -.PP - -.IP unused: 3 -the include/exclude/erase/omit/substitute pattern did not match any file pathnames. -.PP - -.IP usage: 3 -unsupported usage detected - e.g. an unsupported option combination. - -.PP - -.IP utility: 3 -a tool called during processing returned an error code (e.g., 'find' encountered an unreadable directory). -.PP - -.IP version: 3 -revision control IDs of the file which we are trying to merge are not the same - line numbering and other information may be incorrect. -.PP - -Also see man -.B lcovrc(5) -for a discussion of the 'max_message_count' parameter which can be used to control the number of warnings which are emitted before all subsequent messages are suppressed. This can be used to reduce log file volume. - -.RE - -.BI "\-\-expect\-message\-count message_type:expr[,message_type:expr]" -.RS -Give -.B lcov -a constraint on the number of messages of one or more types which are expected to -be produced during execution. If the constraint is not true, then generate an -error of type -.I "count" -(see above). - -See man -.B genhtml(1) -for more details about the flag, as well as the -.I "expect_message_count" -section in man -.B lcovrc(5) -for a description of the equivalent configuration file option. -.RE - -.BI "\-\-keep\-going " -.RS -Do not stop if error occurs: attempt to generate a result, however flawed. - -This command line option corresponds to the -.I stop_on_error [0|1] -lcovrc option. See man -.B lcovrc(5) -for more details. - -.RE -.BI "\-\-preserve " -.RS -Preserve intermediate data files generated by various steps in the tool - e.g., for debugging. By default, these files are deleted. - -.RE -.BI "\-\-filter " -.I filters -.RS -Specify a list of coverpoint filters to apply to input data. -See the genhtml man page for details. - - -.RE -.BI "\-\-demangle\-cpp " [param] -.RS -Demangle C++ function names. See the genhtml man page for details. - - -.RE - -.B \-i -.br -.B \-\-initial -.RS -Capture initial zero coverage data - i.e., from the compile-time '.gcno' data -files. -Also see the -.B \-\-all -flag, which tells the tool to capture both compile-time ('.gcno') and runtime -('.gcda') data at the same time. - -Run lcov with \-c and 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. -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 -correct even when not all source code files were loaded during the test. - -Recommended procedure when capturing data for a test case: - -1. create baseline coverage data file -.RS -# lcov \-c \-i \-d appdir \-o app_base.info -.br - -.RE -2. perform test -.RS -# appdir/test -.br - -.RE -3. create test coverage data file -.RS -# lcov \-c \-d appdir \-o app_test.info -.br - -.RE -4. combine baseline and test coverage data -.RS -# lcov \-a app_base.info \-a app_test.info \-o app_total.info -.br -.RE - -The above 4 steps are equivalent to -.br -.RS -# lcov \-\-capture \-\-all -o app_total.info \-d appdir -.RE - -The combined compile- and runtime data will produce a different result than -capturing runtime data alone if your project contains some compilation units -which are not used in any of your testcase executables or shared libraries - -that is, there are some '.gcno' (compile time) data files that do not -have matching '.gcda' (runtime) data files. -In that case, the runtime-only report will not contain any coverpoints from -the unused files, whereas those coverpoints will appear (with all zero 'hit' -counts) in the combined report. - -The -.BR \-\-initial -flag is ignored except in -.BR \-\-capture -mode. The -.BR \-\-all -flag is ignored if the -.BR \-\-initial -flag is specified. -.RE - -.B \-k -.I subdirectory -.br -.B \-\-kernel\-directory -.I subdirectory -.br -.RS -Capture kernel coverage data only from -.IR subdirectory . - -Use this option if you don't want to get coverage data for all of the -kernel, but only for specific subdirectories. This option may be specified -more than once. - -Note that you may need to specify the full path to the kernel subdirectory -depending on the version of the kernel gcov support. -.RE - -.B \-l -.I tracefile -.br -.B \-\-list -.I tracefile -.br -.RS -List the contents of the -.IR tracefile . - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-\-list\-full\-path -.br -.B \-\-no\-list\-full\-path -.br -.RS -Specify whether to show full paths during list operation. - -Use \-\-list\-full\-path to show full paths during list operation -or \-\-no\-list\-full\-path to show shortened paths. Paths are -.B shortened -by default. -.RE - -.B \-\-no\-markers -.br -.RS -Use this option if you want to get coverage data without regard to exclusion -markers in the source code file. See -.BR "geninfo " (1) -for details on exclusion markers. -.RE - -.B \-\-no\-recursion -.br -.RS -Use this option if you want to get coverage data for the specified directory -only without processing subdirectories. -.RE - -.B \-o -.I tracefile -.br -.B \-\-output\-file -.I tracefile -.br -.RS -Write data to -.I tracefile -instead of stdout. - -Specify "\-" as a filename to use the standard output. - -By convention, lcov\-generated coverage data files are called "tracefiles" and -should have the filename extension ".info". -.RE - -.B \-v -.br -.B \-\-verbose -.RS -Increment informational message verbosity. This is mainly used for script and/or flow debugging - e.g., to figure out which data file are found, where. -Also see the \-\-quiet flag. - -Messages are sent to stdout unless there is no output file (i.e., if the coverage data is written to stdout rather than to a file) and to stderr otherwise. - -.RE -.B \-q -.br -.B \-\-quiet -.RS -Decrement informational message verbosity. - -Decreased verbosity will suppress 'progress' messages for example - while error and warning messages will continue to be printed. - -.RE -.B \-\-debug -.RS -Increment 'debug messages' verbosity. This is useful primarily to developers who want to enhance the lcov tool suite. - -.RE - -.BI "\-\-parallel " -.I [ integer ] -.br -.BI "\-j " -.I [ integer ] -.RS -Specify parallelism to use during processing (maximum number of forked child processes). If the optional integer parallelism parameter is zero or is missing, then use to use up the number of cores on the machine. Default is to use a single process (no parallelism). -.br -Also see the -.I memory, memory_percentage, max_fork_fails -and -.I fork_fail_timeout -entries in man -.B lcovrc(5). -A previously generated execution profile may help to enable better utilization -and faster parallel execution. See the -.I "\-\-profile" -and -.I "\-\-history" -sections of this man page. - -.RE -.BI "\-\-memory " -.I integer -.RS -Specify the maximum amount of memory to use during parallel processing, in Mb. Effectively, the process will not fork() if this limit would be exceeded. Default is 0 (zero) - which means that there is no limit. - -This option may be useful if the compute farm environment imposes strict limits on resource utilization such that the job will be killed if it tries to use too many parallel children - but the user does now know a priori what the permissible maximum is. This option enables the tool to use maximum parallelism - up to the limit imposed by the memory restriction. - -The configuration file -.I memory_percentage -option provided another way to set the maximum memory consumption. -See man -.B lcovrc(5) -for details. - -.RE - -.B \-\-rc -.IR keyword = value -.br -.RS -Override a configuration directive. - -Use this option to specify a -.IR keyword = value -statement which overrides the corresponding configuration statement in -the lcovrc configuration file. You can specify this option more than once -to override multiple configuration statements. -See man -.BR lcovrc (5) -for a list of available keywords and their meaning. -.RE - -.B \-r -.I tracefile -.I pattern -.br -.B \-\-remove -.I tracefile -.I pattern -.br -.RS -Remove data from -.IR tracefile . - -Use this switch if you want to remove coverage data for a particular -set of files from a tracefile. Additional command line parameters will be -interpreted as shell wildcard patterns (note that they may need to be -escaped accordingly to prevent the shell from expanding them first). -Every file entry in -.I tracefile -which matches at least one of those patterns will be removed. - -Note: The pattern must be specified to match the -.B absolute -path of each source file. - -The result of the remove operation will be written to stdout or the tracefile -specified with \-o. - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-\-summary -.I tracefile -.br -.RS -Show summary coverage information for the specified tracefile. - -Note that you may specify this option more than once. - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-\-fail\-under\-branches -.I percentage -.br -.RS -Use this option to tell lcov to exit with a status of 1 if the total -branch coverage is less than -.I percentage. -.RE - -.B \-\-fail\-under\-lines -.I percentage -.br -.RS -Use this option to tell lcov to exit with a status of 1 if the total -line coverage is less than -.I percentage. -.RE - -.B \-t -.I testname -.br -.B \-\-test\-name -.I testname -.br -.RS -Specify test name to be stored in the tracefile. - -This name identifies a coverage data set when more than one data set is merged -into a combined tracefile (see option \-a). - -Valid test names can consist of letters, decimal digits and the underscore -character ("_"). -.RE - -.B \-\-to\-package -.I package -.br -.RS -Store .da files for later processing. - -Use this option if you have separate machines for build and test and -want to perform the .info file creation on the build machine. To do this, -follow these steps: - -On the test machine: -.RS -.br -\- run the test -.br -\- run lcov \-c [\-d directory] \-\-to-package -.I file -.br -\- copy -.I file -to the build machine -.RE -.br - -On the build machine: -.RS -.br -\- run lcov \-c \-\-from-package -.I file -[\-o and other options] -.RE -.br - -This works for both kernel and user space coverage data. Note that you might -have to specify the path to the build directory using \-b with -either \-\-to\-package or \-\-from-package. Note also that the package data -must be converted to a .info file before recompiling the program or it will -become invalid. -.RE - -.B \-\-version -.br -.RS -Print version number, then exit. -.RE - -.B \-z -.br -.B \-\-zerocounters -.br -.RS -Reset all execution counts to zero. - -By default tries to reset kernel execution counts. Use the \-\-directory -option to reset all counters of a user space program. - -Only one of \-z, \-c, \-a, \-e, \-r, \-l, \-\-diff or \-\-summary may be -specified at a time. -.RE - -.B \-\-tempdir -.I dirname -.br -.RS -Write temporary and intermediate data to indicated directory. Default is "/tmp". -.RE - -.SH FILES - -.I /etc/lcovrc -.RS -The system\-wide configuration file. -.RE - -.I ~/.lcovrc -.RS -The per\-user configuration file. -.RE - -.SH AUTHOR -Peter Oberparleiter - -Henry Cox -.RS -Filtering, error management, parallel execution sections. -.RE - -.SH SEE ALSO -.BR lcovrc (5), -.BR genhtml (1), -.BR geninfo (1), -.BR genpng (1), -.BR gendesc (1), -.BR gcov (1) -.br - -.I \*[lcovurl] -.br diff --git a/man/lcovrc.5 b/man/lcovrc.5 deleted file mode 100644 index 73861ca8..00000000 --- a/man/lcovrc.5 +++ /dev/null @@ -1,3238 +0,0 @@ -.TH lcovrc 5 "LCOV 2.0" 2023\-05\-17 "User Manuals" - -.SH NAME -lcovrc \- lcov configuration file - -.SH DESCRIPTION -The -.I lcovrc -file contains configuration information for the -.B lcov -code coverage tool (see -.BR lcov (1)). -.br - -The system\-wide configuration file is located at -.IR $LCOV_HOME/etc/lcovrc . -This is typically either -.IR /etc/lcovrc -or -.IR /usr/local/etc/lcovrc -but may be wherever you have installed the lcov package. -To change settings for a single user, place a customized copy of this file at -location -.IR ~/.lcovrc . -Where available, command\-line options override configuration file settings. - -The -.I genhtml, lcov, -and -.I geninfo -commands also support the -.I \-\-config\-file -option, which can be used to specify one or more files which should be used instead of the system or user default rc files. -Multiple options files may be useful if you have both project- and team-specific common options and want to ensure consistency across multiple users. If multiple \-\-config\-file options are applied in the order they appear. -Note that the "\-\-config\-file" option name must be specified in full and cannot be abbreviated. An error will occur if the option is not recognized. - -Lines in a configuration file can either be: -.IP " *" -empty lines or lines consisting only of white space characters. These lines are -ignored. -.IP " *" -comment lines which start with a hash sign ('#'). These are treated like empty -lines and will be ignored. -.IP " *" -statements in the form -.RI ' key " = " value '. - -.IP " *" -Values may be taken from environment variables via the syntax - -.RI ' key " = " ... $ENV{ENV_VAR_NAME} ...'. - -.RI -The substring '$ENV{ENV_VAR_NAME}' is replaced by the value of the environment variable. - -.RI -One or more environment variables may be used to set the RC value. -'key' is ignored if any of the environment variables are not set in your user environment. - -.PP -A list of valid statements and their description can be found in -section 'OPTIONS' below. -.br -.B NOTE -that there is no error checking of keys in the options file: spelling errors -are simply seen as values which are not used by some particular tool. -If you are unsure of whether your options file is read or its values -applied, you can use the -.I \-\-verbose \-\-verbose -flag to enable printing of option value overrides. -(The option appears twice to enable a higher level of verbosity.) - -Both 'list' and 'scalar' (non list) options are supported in the lcovrc file. - -For scalar (non list) options: -.IP " *" -if specified on the command line and in the lcovrc file, the value specified on the command line wins. -The value from the RC file is ignored. -.IP " *" -Scalar options include: -.RI 'criteria_script " = " ...' -, -.RI 'genhtml_annotate_script " = " ...' -, -.RI 'version_script " = " ...' -, etc. -.PP -.PP - -.PP -For list options: -.IP " *" -the RC file entry can be used multiple times; each use appends to the list. -.br -For example, the entry below will result in two 'omit' patterns which will both be checked: -.IP " " -# note explicit start/end line markers in the regexp -.br -omit_lines = ^\\s+//\\s*MY_EXCLUDE_MARKER\\s*$ -.br -# Note that the regexp below matches anywhere on the line -.br -omit_lines = NR_CM_DBG_PRINT - -.IP " *" -If entries are specified on the command line, then the RC file entries are ignored: command line wins. -If entries are specified in more than one RC file (i.e., multiple \-\-config\-file arguments are supplied), then RC files are applied in order of appearance, and list entries are appended in order. For most list-type options, order is not important. - - -.IP " *" -list options include: -.br -.RI " filter = " ... -.br -.RI " exclude = " ... -.br -.RI " ignore = " ... -.br -.RI " substitute = " ... -.br -.RI " omit_lines = " ... -.br -.RI " erase_functions = " ... -.br -.RI " genhtml_annotate_script = " ... -.br -.I etc. -For a complete set of list options, see the documentation of each configuration option, below. -.PP - -.PP -.PP - -.B Example configuration: - -Note that this example does not include all possible configuration -options. -.br -In general: (almost) all command line options can be specified in -the configuration file instead, whereas some configuration file options -have no command line equivalent. - -See the OPTIONS section below for details. -.IP -# -.br -# Example LCOV configuration file -.br -# -.br -# include some other config file -.br -# e.g, user-specific options. Note the environment variable expansion -.br -# config_file = $ENV{HOME}/.user_lcovrc -.br -# or project specific - hard-coded from environment variable -.br -# config_file = /path/to/myproject/.lcovrc -.br -# or in the current run directory -.br -# config_file = $ENV{PWD}/.lcovrc -.br -.br -# External style sheet file -.br -#genhtml_css_file = gcov.css -.br - -# Use 'dark' mode display (light foreground/dark background) -.br -# rather than default -.br -#genhtml_dark_mode = 1 -.br - -# Alternate header text to use at top of each page -.br -#genhtml_header = Coverage report for my project - -.br - -# Alternate footer text to use at the bottom of each page -.br -#genhtml_footer = My footer text -.br - -# Coverage rate limits -.br -genhtml_hi_limit = 90 -.br -genhtml_med_limit = 75 -.br - -# Ignore some errors (comma-separated list) -.br -#ignore_errors = empty,mismatch -.br - -# Stop emitting message after this number have been printed -.br -# 0 == no limit -.br -max_message_count = 100 - -.br -# If nonzero, do not stop when an 'ignorable error' occurs - try -.br -# to generate a result, however flawed. This is equivalent to -.br -# the '--keep-going' command line switch. -.br -# Default is 1: stop when error occurs -.br -#stop_on_error = 1 - -.br -# If nonzero, treat warnings as error -.br -# note that ignored messages will still appear as warnings -.br -# Default is 0 -.br -#treat_warning_as_error = 1 - -.br -# If set to non-zero, only issue particular warning once per file -.br -# Default is 1 -.br -#warn_once_per_file = 1 - -.br -# extension associated with lcov trace files - glob match pattern -.br -# used as argument to 'find' - to find coverage files contained in -.br -# a directory argument -.br -#info_file_pattern = *.info -.br - -# list of file extensions which should be treated as C/C++ code -.br -# (comma-separated list) -.br -#c_file_extensions = h,c,cpp,hpp -.br - -# list of file extensions which should be treated as RTL code -.br -# (e.g., Verilog) (comma-separated list) -.br -#rtl_file_extensions = v,vh,sv -.br - -# list of file extensions which should be treated as Java code -.br -#java_file_extensions = java - -# list of file extensions which should be treated as perl code -.br -#perl_file_extensions = pl,pm -.br - -# list of file extensions which should be treated as python code -.br -#python_file_extensions = py -.br - -# maximum number of lines to look at, when filtering bogus branch expressions -.br -#filter_lookahead = 5 -.br - -# if nonzero, bitwise operators '|', '&', '~' indicate conditional expressions -.br -#filter_bitwise_conditional = 1 -.br -.br -# if nonzero, '--filter blank' is applied to blank lines, regardless -.br -# of their hit count -.br -#filter_blank_aggressive = 1 -.br -.br - -# Width of line coverage field in source code view -.br -genhtml_line_field_width = 12 -.br - -# Width of branch coverage field in source code view -.br -genhtml_branch_field_width = 16 -.br - -# Width of MC/DC coverage field in source code view -.br -genhtml_mcdc_field_width = 14 -.br - -# width of 'owner' field in source code view - default is 20 -.br -genhtml_owner_field_width = 20 -.br -# width of 'age' field in source code view - default is 5 -.br -genhtml_age_field_width = 5 -.br - -# Width of overview image -.br -genhtml_overview_width = 80 -.br - -# Resolution of overview navigation -.br -genhtml_nav_resolution = 4 -.br - -# Offset for source code navigation -.br -genhtml_nav_offset = 10 -.br - -# Do not remove unused test descriptions if non\-zero -.br -genhtml_keep_descriptions = 0 -.br - -# Do not remove prefix from directory names if non\-zero -.br -genhtml_no_prefix = 0 -.br - -# Do not create source code view if non\-zero -.br -genhtml_no_source = 0 -.br - -# Specify size of tabs -.br -genhtml_num_spaces = 8 -.br - -# Include color legend in HTML output if non\-zero -.br -genhtml_legend = 0 -.br - -# Include HTML file at start of HTML output -.br -#genhtml_html_prolog = prolog.html -.br - -# Include HTML file at end of HTML output -.br -#genhtml_html_epilog = epilog.html -.br - -# Use custom HTML file extension -.br -#genhtml_html_extension = html -.br - -# Compress all generated html files with gzip. -.br -#genhtml_html_gzip = 1 -.br - -# Include sorted overview pages -.br -genhtml_sort = 1 -.br - -# Display coverage data in hierarchical directory structure -.br -# (rather than flat/3 level) -.br -#genhtml_hierarchical = 1 -.br - -# Display coverage data using 'flat' view -.br -#genhtml_flat_view = 1 -.br - -# Specify the character set of all generated HTML pages -.br -genhtml_charset=UTF\-8 -.br - -# Allow HTML markup in test case description text if non\-zero -.br -genhtml_desc_html=0 -.br - -# Specify the precision for coverage rates -.br -#genhtml_precision=1 -.br - -# Show missed counts instead of hit counts -.br -#genhtml_missed=1 -.br - -# group function aliases in report - see '--merge' section in man(1) genhtml -.br -#merge_function_aliasess = 1 -.br - -# If set, suppress list of aliases in function detail table -.br -#suppress_function_aliases = 1 -.br - -# If set, derive function end line from line coverpoint data - default ON -.br -#derive_function_end_line = 1 -.br - -# If set, derive function end lines for all file types. -# By default, we derive end lines for C/C++ files only -# -.br -#derive_end_line_all_files = 0 -.br - -# Maximum size of function (number lines) which will be checked by '--filter trivial' -.br -#trivial_function_threshold = 5 -.br - -# Set threshold for hit count which tool should deem likely to indicate -.br -# a toolchain bug (corrupt coverage data) -.br -# excessive_count_theshold = number -.br - -# Demangle C++ symbols -.br -# Call multiple times to specify command and command line arguments -.br -# ('-Xlinker'-like behaviour) -.br -#demangle_cpp = c++filt -.br - -# Location of the gcov tool -.br -#geninfo_gcov_tool = gcov -.br - -# Adjust test names if non\-zero -.br -#geninfo_adjust_testname = 0 -.br - -# Ignore testcase names in .info file -forget_testcase_names = 0 - -# Calculate and/or compute checksum for each line if non\-zero -.br -checksum = 0 -.br - -# Enable libtool compatibility mode if non\-zero -.br -geninfo_compat_libtool = 0 -.br - -# Specify whether to capture coverage data for external source -.br -# files -.br -#geninfo_external = 1 -.br - -# Specify whether to capture coverage data from compile-time data files -.br -# which have no corresponding runtime data. -.br -#geninfo_capture_all = 1 -.br - -# Use gcov's --all-blocks option if non-zero -.br -#geninfo_gcov_all_blocks = 1 -.br - -# Adjust 'executed' non-zero hit count of lines which contain no branches -.br -# and have attribute '"unexecuted_blocks": true' -.br -#geninfo_unexecuted_blocks = 0 -.br - -# Specify compatibility modes (same as \-\-compat option -.br -# of geninfo) -.br -#geninfo_compat = libtool=on, hammer=auto, split_crc=auto -.br - -# Specify if geninfo should try to automatically determine -.br -# the base-directory when collecting coverage data. -.br -geninfo_auto_base = 1 -.br - -# Use gcov intermediate format? Valid values are 0, 1, auto -.br -geninfo_intermediate = auto -.br - -# Specify if exception branches should be excluded from branch coverage. -.br -no_exception_branch = 0 -.br - -# Directory containing gcov kernel files -.br -lcov_gcov_dir = /proc/gcov -.br - -# Location for temporary directories -.br -lcov_tmp_dir = /tmp -.br - -# Show full paths during list operation if non\-zero -.br -lcov_list_full_path = 0 -.br - -# Specify the maximum width for list output. This value is -.br -# ignored when lcov_list_full_path is non\-zero. -.br -lcov_list_width = 80 -.br - -# Specify the maximum percentage of file names which may be -.br -# truncated when choosing a directory prefix in list output. -.br -# This value is ignored when lcov_list_full_path is non\-zero. -.br -lcov_list_truncate_max = 20 - -# Specify if function coverage data should be collected, processed, and -.br -# displayed. -.br -function_coverage = 1 -.br - -# Specify if branch coverage data should be collected, processed, and -.br -# displayed. -.br -branch_coverage = 0 -.br - -# Specify if Modified Condition / Decision Coveage data should be collected, -.br -# processed, and displayed. -.br -mcdc_coverage = 0 -.br - -# Ask lcov/genhtml/geninfo to return non-zero exit code if branch coverage is -.br -# below specified threshold percentage. -.br -fail_under_branches = 75.0 -.br - -# Ask lcov/genhtml/geninfo to return non-zero exit code if line coverage is -.br -# below specified threshold percentage. -.br -#fail_under_lines = 97.5 -.br - -# Specify JSON module to use, or choose best available if -.br -# set to auto -.br -lcov_json_module = auto -.br - -# Specify maximum number of parallel slaves -.br -# default: 1 (no parallelism) -.br -#parallel = 1 -.br - -.br -# Specify maximum memory to use during parallel processing, in Mb. -.br -# Do not fork if estimated memory consumption exceeds this number. -.br -# default: 0 (no limit) -.br -#memory = 1024 -.br - -.br -# Specify the number of consecutive fork() failures to allow before -.br -# giving up -.br -# max_fork_fails = 5 -.br - -.br -# Seconds to wait after failing to fork() before retrying -.br -# fork_fail_timeout = 10 -.br - -.br -# Throttling control: specify a percentage of system memory to use as -.br -maximum during parallel processing. -.br -# Do not fork if estimated memory consumption exceeds the maximum. -.br -# this value is used only if the maximum memory is not set. -.br -# default: not set -.br -#memory_percentage = 75 -.br - -.br -# Character used to split list-type parameters -.br -# \- for example, the list of "--ignore_errors source,mismatch" -.br -# default: , (comma) -.br -#split_char = , -.br - - -.br -# use case insensitive compare to find matching files, for include/exclude -.br -# directives, etc -.br -#case_insensitive = 0 -.br - -.br -# override line default line exclusion regexp -.br -#lcov_excl_line = LCOV_EXCL_LINE -.br - -.br -# override branch exclusion regexp -.br -#lcov_excl_br_line = LCOV_EXCL_BR_LINE -.br - -.br -# override exception branch exclusion regexp -.br -#lcov_excl_exception_br_line = LCOV_EXCL_EXCEPTION_BR_LINE -.br - -.br -# override start of exclude region regexp -.br -#lcov_excl_start = LCOV_EXCL_START -.br - -.br -# override end of exclude region regexp -.br -#lcov_excl_stop = LCOV_EXCL_STOP -.br - -.br -# override unreachable line default line exclusion regexp -.br -#lcov_unreachable_line = LCOV_UNREACHABLE_LINE -.br -.br -# override start of unreachable region regexp -.br -#lcov_unreachable_start = LCOV_UNREACHABLE_START -.br - -.br -# override end of unreachable region regexp -.br -#lcov_unreachable_stop = LCOV_UNREACHABLE_STOP -.br - - -.br -# override start of branch exclude region regexp -.br -#lcov_excl_br_start = LCOV_EXCL_BR_START -.br - -.br -# override start of exclude region regexp -.br -#lcov_excl_br_stop = LCOV_EXCL_BR_STOP -.br - -.br -# override start of exclude region regexp -.br -#lcov_excl_exception_br_start = LCOV_EXCL_EXCEPTION_BR_START -.br - -.br -# override start of exclude region regexp -.br -#lcov_excl_exception_br_stop = LCOV_EXCL_EXCEPTION_BR_STOP - -.PP - -.SH OPTIONS - -.BR config_file " =" -.I filename -.IP - -Include another config file. - -Inclusion is equivalent to inserting the text from -.I filename -at this point in the current file. As a result, settings from the included -file are processed after earlier settings in the current file, but before later settings from the current file. -As a result: - -.BR "Scalar options" -set earlier in the current file are overridden by settings from the included file, and scalar options from the included file are overridden by later setting in the current file. - -.BR "Array options" -from earlier in the current file appear before setting from the included file, and array options from later in the current file appear after. - -Config file inclusion is recursive: an included config file may include another file - and so on. -Inclusion loops are not supported and will result in a -.I usage -error. - -The most common usecase for config file inclusion is so that a site-wide or project-wide options file can include a user-specific or module-specific options file - for example, as - -.RS 3 -.IP - ... -.br -config_file = $ENV{HOME}/.lcovrc_user -.br - ... -.PP -.RE - - -.PP - -.BR genhtml_css_file " =" -.I filename -.IP -Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by -.BR genhtml . -During output generation, a copy of this file will be placed in the output -directory. -.br - -This option corresponds to the \-\-css\-file command line option of -.BR genhtml . -.br - -By default, a standard CSS file is generated. -.PP - -.BR genhtml_header " =" -.I string -.IP - -Specify header text to use ta top of each HTML page. -.br - -This option corresponds to the \-\-header\-title command line option of -.BR genhtml . -.br -Default is "LCOV - (differential )? coverage report" - -.PP - -.BR genhtml_footer " =" -.I string -.IP -Specify footer text to use at bottom of each HTML page. -.br - -This option corresponds to the \-\-footer command line option of -.BR genhtml . -.br - -Default is LCOV tool version string. - -.PP - -.BR genhtml_dark_mode " =" -.IR 0 | 1 -.IP -If non-zero, display using light text on dark background rather than dark text on light background. -.br - -This option corresponds to the \-\-dark\-mode command line option of -.BR genhtml . -.br - -By default, a 'light' palette is used. -.PP - -.BR genhtml_hi_limit " =" -.I hi_limit -.br -.BR genhtml_med_limit " =" -.I med_limit -.br -.IP -Specify coverage rate limits for classifying file entries. Use this option to -modify the coverage rates (in percent) for line, function and branch coverage at -which a result is classified as high, medium or low coverage. This -classification affects the color of the corresponding entries on the overview -pages of the HTML output: -.br - -High: hi_limit <= rate <= 100 default color: green -.br -Medium: med_limit <= rate < hi_limit default color: yellow -.br -Low: 0 <= rate < med_limit default color: red -.br - -Defaults are 90 and 75 percent. - -There are also options to configure different thresholds for line, branch, and function coverages. See below. -.PP - -.BR genhtml_line_hi_limit " =" -.I line_hi_limit -.br -.BR genhtml_line_med_limit " =" -.I line_med_limit -.br -.IP -Specify specific threshold for line coverage limits used to decide whether a particular line coverage percentage is classified as high, medium, or low coverage. -If the line-specific values are not specified, then the default -.I genhtml_med_limit -or -.I genhtml_hi_limit -values are used. -.PP - -.BR genhtml_branch_hi_limit " =" -.I branch_hi_limit -.br -.BR genhtml_branch_med_limit " =" -.I branch_med_limit -.br -.IP -Specify specific threshold for branch coverage limits used to decide whether a particular branch coverage percentage is classified as high, medium, or low coverage. -If the branch-specific values are not specified, then the default -.I genhtml_med_limit -or -.I genhtml_hi_limit -values are used. -.PP - -.BR genhtml_function_hi_limit " =" -.I function_hi_limit -.br -.BR genhtml_function_med_limit " =" -.I function_med_limit -.br -.IP -Specify specific threshold for function coverage limits used to decide whether a particular function coverage percentage is classified as high, medium, or low coverage. -If the function-specific values are not specified, then the default -.I genhtml_med_limit -or -.I genhtml_hi_limit -value is used. -.PP - -.BR rtl_file_extensions " =" -.IR str[,str]+ -.IP -Specify a comma-separated list of file extensions which should be assumed to be RTL code (e.g., Verilog). -.br - -If not specified, the default set is 'v,vh,sv,vhdl?'. -There is no command line option equivalent. -.br -This option is used by genhtml and lcov. - -.PP - -.BR info_file_pattern " =" -.IR str -.IP -Specify a glob-match pattern associated with lcov trace files (suitable as an argument to 'find'. -If not specified, the default is '*.info'. - -.PP - -.BR c_file_extensions " =" -.IR str[,str]+ -.IP -Specify a comma-separated list of file extensions which should be assumed to be C/C++ code. -.br - -If not specified, the default set is 'c,h,i,C,H,I,icc,cpp,cc,cxx,hh,hpp,hxx'. -If you want all files to be treated as C/C++ code, you can use: -.I c_file_extensions = .* - -This parameter must be set from the lcovrc file or via the -.I \-\-rc name=value -command line option; note that you may need to protect the value from shell expansion in the latter case. -.br - -.PP - -.BR java_file_extensions " =" -.IR str[,str]+ -.IP -Specify a comma-separated list of file extensions which should be assumed to be Java code. -.br - -If not specified, the default set is 'java'. -If you want all files to be treated as Java code, you can use: -.I java_file_extensions = .* - -This parameter must be set from the lcovrc file or via the -.I \-\-rc name=value -command line option; note that you may need to protect the value from shell expansion in the latter case. -.br - -.PP - -.BR perl_file_extensions " =" -.IR str[,str]+ -.IP -Specify a comma-separated list of file extensions which should be assumed to be Perl code. -.br - -If not specified, the default set is 'pl,pm'. -If you want all files to be treated as Perl code, you can use: -.I perl_file_extensions = .* - -This parameter must be set from the lcovrc file or via the -.I \-\-rc name=value -command line option; note that you may need to protect the value from shell expansion in the latter case. -.br - -.PP - -.BR python_file_extensions " =" -.IR str[,str]+ -.IP -Specify a comma-separated list of file extensions which should be assumed to be Python code. -.br - -If not specified, the default set is 'py'. -If you want all files to be treated as Python code, you can use: -.I python_file_extensions = .* - -This parameter must be set from the lcovrc file or via the -.I \-\-rc name=value -command line option; note that you may need to protect the value from shell expansion in the latter case. -.br - - -.PP - -.BR filter_lookahead " =" -.IR integer -.IP -Specify the maximum number of lines to look at when filtering bogus branch expressions. -A larger number may catch more cases, but will increase execution time. -.br - -If not specified, the default set is 10. -There is no command line option equivalent. -.br -This option is used by genhtml and lcov. - -.PP - -.BR filter_bitwise_conditional " =" -.IR 0|1 -.IP -If set to non-zero value, bogus branch filtering will assume that expressions containing bitwise operators '&', '|', '~' are conditional expressions - and will not filter them out. -.br - -If not specified, the default set is 0 (do not treat them as conditional). -There is no command line option equivalent. -.br -This option is used by genhtml and lcov. - -.PP - -.BR filter_blank_aggressive " =" -.IR 0|1 -.IP -If set to non-zero value, then blank source lines will be ignored whether -or not their 'hit' count is zero. -See the -.I \-\-filter blank -section in man -.B genhtml(1). -.br - -If not specified, the default set is 0 (filter blank lines only if they are not hit). -.br -There is no command line option equivalent. - -.PP - -.BR ignore_errors " =" -.IR message_type(,message_type)* -.IP -Specify a message type which should be ignored. -.br - -This option can be used multiple times in the lcovrc file to ignore multiple message types. - -This option is equivalent to the \-\-ignore\-errors option to geninfo, genhtml, or lcov. Note that the lcovrc file message list is not applied (those messages NOT ignored) if the '\-\-ignore\-errors' command line option is specified. -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR ignore_unreachable_flag " =" -.IR 0 | 1 -.IP -When parsing a trace file, ignore 'unreachable' flags on branch expressions -and MC/DC conditions - effectively, treating them as reachable. - -Note that the -.I ignore_unreachable_flag -is used only when reading a trace file. It has no effect on unreachable -flags set by your -.I unreachable_script -callback. -See the -.I unreachable_script -section, below. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR expect_message_count " =" -.IR message_type:expr(,message_type:expr)* -.IP -Specify -a constraint on the number of messages of one or more types which are expected to -be produced during tool execution. If the constraint is not true, an -error of type -.I "count" -will be generated. - -Multiple constraints can be specified using a comma-separated list or -by using the option multiple times. - - -Substitutions are performed on the expression before it is evaluated: - -For example: - -.RS 3 - -.IP \- 3 -expect_message_count = inconsistent : %C == 5 -.br -says that you expect exactly 5 messages of this type -.PP - -.IP \- 3 -expect_message_count inconsistent : %C > 6 && %C <= 10 -.br -says that you expect the number of messages to be in the range (6:10]. -.PP - -.RE - -This option is useful if errors are caused by conditions that you cannot -fix - for example, due to inconsistent coverage data generated by your -toolchain. In those scenarios, you may decide: - -.RS 3 - -.IP \- 3 -to exclude the offending code, or -.PP -.IP \- 3 -to exclude the entire offending file(s), or -.PP -.IP \- 3 -to ignore the -messages, either by converting them to warnings or suppressing them entirely. -.PP -.RE - -In the latter case, this option provides some additional safety by warning -you when the count differs due to some change which occurred, giving you -the opportunity to diagnose the change and/or to review message changes. - -This option is equivalent to the -.I "\-\-expect\-message\-count" -command line flag. - -.PP - -.BR max_message_count " =" -.IR integer -.IP -Set the maximum number of warnings of any particular type which should be emitted. This can be used to reduce the size of log files. -.br - -No more warnings will be printed after this number is reached. 0 (zero) is interpreted as 'no limit'. -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR message_log " =" -.IR filename -.IP -Specify location to store error and warning messages (in addition to writing to STDERR). -If not specified, then the default location is used. -.br - -.br -This attribute is equivalent to the -.I \-\-msg\-log -command line option. The command line option takes precedence if both are specified. - -.PP - -.BR stop_on_error " = " -.IR 0|1 -.IP -If set to 0, tell the tools to ignore errors and keep going to try to generate a result - however flawed or incomplete that result might be. -Note that some errors cannot be ignored and that ignoring some errors may lead to other errors. -.br -The tool will return a non-zero exit code if one or more errors are detected -during execution when -.I stop_on_error -is disabled. That is, the tool will continue execution in the presence -of errors but will return an exit status. - -.br - -This is equivalent to the -.I '\-\-keep\-going' -command line option. - -Default is 1: stop when error occurs. - -If the -.I 'ignore_error msgType' -option is also used, then those messages will be treated as warnings rather than errors (or will be entirely suppressed if the message type appears multiple times in the ignore_messages option). Warnings do not cause a non-zero exit status. - -This option is used by genhtml, lcov, and geninfo. - - -.PP - -.BR treat_warning_as_error " = " -.IR 0|1 -.IP -If set to 1, tell the tools that messages which are normally treated as -warnings ( -.I e.g., -certain usage messages) should be treated as errors. - -Note that ignored messages will still appear as warnings: see the -.I ignore_errors -entry, above. - -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR warn_once_per_file " = " -.IR 0|1 -.IP -If set to 1, tell the tools to emit certain errors only once per file -(rather than multiple times, if the issue occurs multiple times in the same -file). - -Default is 1: do not report additional errors. - -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR check_data_consistency " = " -.IR 0|1 -.IP -If set to 1, tell the tools to execute certain data consistency checks - -.I e.g., -that function with a non-zero hit count contains at least one line with a non-zero -hit count - and vice versa. - -It may be useful to use this option to disable checking if you have inconsistent -legacy data and have -no way to correct or exclude it. - -Default is 1: execute consistency checks. - -.PP - -.BR genhtml_line_field_width " =" -.I number_of_characters -.IP -Specify the width (in characters) of the source code view column containing -line coverage information. -.br - -Default is 12. -.PP - -.BR genhtml_branch_field_width " =" -.I number_of_characters -.IP -Specify the width (in characters) of the source code view column containing -branch coverage information. -.br - -Default is 16. -.PP - -.BR genhtml_mcdc_field_width " =" -.I number_of_characters -.IP -Specify the width (in characters) of the source code view column containing -MC/DC coverage information. -.br - -Default is 14. -.PP - -.BR genhtml_owner_field_width " =" -.I number_of_characters -.IP -Specify the width (in characters) of the source code view column containing -owner information (as reported by your annotation script. This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page. -.br - -Default is 20. -.PP - -.BR genhtml_age_field_width " =" -.I number_of_characters -.IP -Specify the width (in characters) of the source code view column containing -age of the corresponding block (as reported by your annotation script). This option has an effect only if you are using a source annotation script: see the \-\-annotation-script option in the genhtml man page. -.br - -Default is 5. -.PP - -.BR genhtml_frames " =" -.I 0 | 1 -.IP -Specify whether source detail view should contain a navigation image. -See the -.I \-\-frame -entry in the -.B genhtml -man page. -.PP - -.BR genhtml_overview_width " =" -.I pixel_size -.IP -Specify the width (in pixel) of the overview image created when generating HTML -output using the \-\-frames option of -.BR genhtml . -.br - -Default is 80. -.PP - -.BR genhtml_nav_resolution " =" -.I lines -.IP -Specify the resolution of overview navigation when generating HTML output using -the \-\-frames option of -.BR genhtml . -This number specifies the maximum difference in lines between the position a -user selected from the overview and the position the source code window is -scrolled to. -.br - -Default is 4. -.PP - - -.BR genhtml_nav_offset " =" -.I lines -.IP -Specify the overview navigation line offset as applied when generating HTML -output using the \-\-frames option of -.BR genhtml. -.br - -Clicking a line in the overview image should show the source code view at -a position a bit further up, so that the requested line is not the first -line in the window. This number specifies that offset. -.br - -Default is 10. -.PP - - -.BR genhtml_keep_descriptions " =" -.IR 0 | 1 -.IP -If non\-zero, keep unused test descriptions when generating HTML output using -.BR genhtml . -.br - -This option corresponds to the \-\-keep\-descriptions option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_no_prefix " =" -.IR 0 | 1 -.IP -If non\-zero, do not try to find and remove a common prefix from directory names. -.br - -This option corresponds to the \-\-no\-prefix option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_no_source " =" -.IR 0 | 1 -.IP -If non\-zero, do not create a source code view when generating HTML output using -.BR genhtml . -.br - -This option corresponds to the \-\-no\-source option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_num_spaces " =" -.I num -.IP -Specify the number of spaces to use as replacement for tab characters in the -HTML source code view as generated by -.BR genhtml . -.br - -This option corresponds to the \-\-num\-spaces option of -.BR genhtml . -.br - -Default is 8. - -.PP - -.BR genhtml_legend " =" -.IR 0 | 1 -.IP -If non\-zero, include a legend explaining the meaning of color coding in the HTML -output as generated by -.BR genhtml . -.br - -This option corresponds to the \-\-legend option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_html_prolog " =" -.I filename -.IP -If set, include the contents of the specified file at the beginning of HTML -output. - -This option corresponds to the \-\-html\-prolog option of -.BR genhtml . -.br - -Default is to use no extra prolog. -.PP - -.BR genhtml_html_epilog " =" -.I filename -.IP -If set, include the contents of the specified file at the end of HTML output. - -This option corresponds to the \-\-html\-epilog option of -.BR genhtml . -.br - -Default is to use no extra epilog. -.PP - -.BR genhtml_html_extension " =" -.I extension -.IP -If set, use the specified string as filename extension for generated HTML files. - -This option corresponds to the \-\-html\-extension option of -.BR genhtml . -.br - -Default extension is "html". -.PP - -.BR genhtml_html_gzip " =" -.IR 0 | 1 -.IP -If set, compress all html files using gzip. - -This option corresponds to the \-\-html\-gzip option of -.BR genhtml . -.br - -Default extension is 0. -.PP - -.BR genhtml_sort " =" -.IR 0 | 1 -.IP -If non\-zero, create overview pages sorted by coverage rates when generating -HTML output using -.BR genhtml . -.br - -This option can be set to 0 by using the \-\-no\-sort option of -.BR genhtml . -.br - -Default is 1. -.PP - -.BR genhtml_hierarchical " =" -.IR 0 | 1 -.IP -If non\-zero, the HTML report will follow the hierarchical directory structure of the source code. -.br - -This option is equivalent to using the \-\-hierarchical command line option of -.BR genhtml . -'Hierarchical' and 'flat' views are mutually exclusive. -.br - -Default is 0. -.PP - -.BR genhtml_flat_view " =" -.IR 0 | 1 -.IP -If non\-zero, the top-level HTML table will contain all of the files in the project and there will be no intermediate directory pages. -.br - -This option is equivalent to using the \-\-flat command line option of -.BR genhtml . -'Hierarchical' and 'flat' views are mutually exclusive. -.br - -Default is 0. -.PP - -.BR genhtml_show_navigation " =" -.IR 0 | 1 -.IP -If non\-zero, the 'source code' view summary table will contain hyperlinks from the number to the first source line in the corresponding category ('Hit' or 'Not hit') in the non-differential coverage report. -Source code hyperlinks are always enabled in differential coverage reports. -.br - -This option is equivalent to using the \-\-show\-navigation command line option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_show_owner_table " =" -.IR 0 | 1 | all -.IP -If non\-zero, equivalent to the genhtml -.I \-\-shwow\-owners -flag: see man -.B genhtml(1) -for details. -.br - -Default is 0. -.PP - -.BR compact_summary_tables " =" -.IR 0 | 1 -.IP -If non\-zero, suppress the 'Total' row in the 'date' and 'owner' summary table if there is only one element in the corresponding bin. -.br -When there are a large number of files with a single author, this can cut the summary table size by almost half. -.br - -Default is 1 (enabled). -.PP - -.BR owner_table_entries " =" -.IR integer -.IP -This option is used to tell genhtml the number of 'owner' table entries to -retain in the summary table (at the top of the page) if owner table truncation is requested. Authors are sorted by quantity of un-exercised code - so elided entries will be smaller offenders: maximal offenders are retained. -If the option is not set, then owner tables are not truncated. - -This option has no effect unless -.I "genhtml \-\-show\-owners" -is enabled. -See the -.I \-\-show-owners -option in -.B genhtml(1) -for details. - -.br - -Default is not set ( -.I i.e., -do not truncate owner tables). -.PP - -.BR truncate_owner_table " =" -.IR comma_separated_list -.IP -This option is used to tell genhtml whether to truncate the 'owner' table -at the top, directory, or file level. -This option acts together with the -.I owner_table_entries -parameter to determine how many author entries are retained. - -This option has no effect unless -.I "genhtml \-\-show\-owners" -is enabled and and the -.I owner_table_entries -configuration is set. - -If this option is set multiple times in the lcovrc file, the values are -combined to form the list of levels where truncation will occur. -Similarly, if this option is not set and -.I owner_table_entries -is set, then the table will be truncated everywhere. - -See the -.I \-\-show-owners -option in -.B genhtml(1) -for details. -.br - -Default is to not truncate the list. -.PP - - - -.BR genhtml_show_noncode_owners " =" -.IR 0 | 1 -.IP -If non\-zero, equivalent to the genhtml -.I \-\-shwow\-noncode -flag: see man -.B genhtml(1) -for details. -.br - -Default is 0. -.PP - -.BR genhtml_show_function_proportion " =" -.IR 0 | 1 -.IP - -If nonzero, add column to "function coverage detail" table to show the proportion of lines and branches within the function which are exercised. -.br - -This option is equivalent to using the \-\-show\-proportion command line option of -.BR genhtml . -.br - -Default is 0. -.PP - -.BR genhtml_synthesize_missing " =" -.IR 0 | 1 -.IP -If non\-zero, equivalent to the genhtml -.I \-\-synthesize\-missing -flag: see man -.B genhtml(1) -for details. -.br - -Default is 0. -.PP - -.BR genhtml_charset " =" -.I charset -.IP -Specify the character set of all generated HTML pages. -.br - -Use this option if the source code contains characters which are not -part of the default character set. Note that this option is ignored -when a custom HTML prolog is specified (see also -.BR genhtml_html_prolog ). -.br - -Default is UTF-8. -.PP - -.BR demangle_cpp " =" -.IR c++filt -.IP -If set, this option tells genhtml/lcov/geninfo to demangle C++ function names in function overviews, -and gives the name of the tool used for demangling. -Set this option to one if you want to convert C++ internal function -names to human readable format for display on the HTML function overview -page. - -If the -.I demangle_cpp -option is used multiple times, then the arguments are concatenated when the callback -is executed - similar to how the gcc -.I \-Xlinker -parameter works. This provides a possibly easier way to pass arguments to -your tool, without requiring a wrapper script. -In that case, your callback will be executed as: -.I | tool\-0 'tool\-1; ... -Arguments are quoted when passed to -the shell, in order to handle parameters which contain spaces. - -Note that the demangling tool is called via a pipe, and is expected to read from stdin and write to stdout. - -This option corresponds to the \-\-demangle\-cpp command line option of -.BR genhtml . -.br - -Default is not set (C++ demangling is disabled). -.PP - -.BR genhtml_desc_html " =" -.IR 0 | 1 -.IP -If non-zero, test case descriptions may contain HTML markup. - -Set this option to one if you want to embed HTML markup (for example to -include links) in test case descriptions. When set to zero, HTML markup -characters will be escaped to show up as plain text on the test case -description page. -.br - -Default is 0. -.PP - -.BR genhtml_precision " =" -.IR 1 | 2 | 3 | 4 -.IP -Specify how many digits after the decimal-point should be used for -displaying coverage rates. -.br - -Default is 1. -.PP -.BR merge_function_aliases " =" -.IR 0 | 1 -.IP -If non-zero, group function aliases in the function detail tabile. -See man(1) genhtml. -.br - -Default is 0. -.PP - -.PP -.BR genhtml_missed " =" -.IR 0 | 1 -.IP -If non-zero, the count of missed lines, functions, or branches is shown -as negative numbers in overview pages. -.br - -Default is 0. -.PP - -.BR suppress_function_aliases " =" -.IR 0 | 1 -.IP -If non-zero, do not show aliases in the function detail table. -.br -If nonzero, implies that -.B merge_function_aliases -is enabled. -.br -See the genhtml man page for more details. -.br - -Default is 0. -.PP - -.BR derive_function_end_line " =" -.IR 0 | 1 -.IP -If non-zero, use 'line' coverage data to deduce the end line of each function -definition. This is useful when excluding certain functions from your coverage report. See the -.I \-\-erase\-functions, -.I \-\-filter trivial -and -.I \-\-show\-proportion -options. - -Default is 1. - -This option is not required if you are using gcc/9 or newer; these versions report function begin/end lines directly. - -Note that end lines are derived only for C/C++ files unless the -.I derive_function_end_lines_all_files -option is enabled; see the -.I c_file_extensions -setting, above, for the list of extensions used to identify C/C++ these files. -.br -Lambda functions are ignored during end line computation. Note that lambdas -are identified via function name matching - so you must enable demangling -if your toolchain is too old to report demangled names in the GCOV output. -See the -.I demangle_cpp -setting, above. - -For languages other than C/C++: end-line derivation may compute the wrong -value - -.I e.g., -in cases where there are lines of code in global scope following -some function definition. In this case, lcov will incorrectly associate the -following code with the preceding function. -.br -If this creates problems - for example, causes lcov to warn about inconsistent -coveage data - then there are several possible workarounds: - -.RS -.IP \- 3 -disable end-line derivation - -.I e.g., -via -.I "\-\-rc derive_function_end_line=0". -.PP -.IP \- 3 -exclude the offending code and/or then entire associated file. -.PP -.IP \- 3 -ignore the error message, -.I e.g., -via the -.I \-\-ignore\-errors -command line option -.PP -.IP \- 3 -disable coverage DB consistency checks - -.I e.g., -via -.I "\-\-rc check_data_consistency=0". -.PP -.RE -. -.PP - -.BR derive_function_end_line_all_files " =" -.IR 0 | 1 -.IP -If non-zero, derive end lines for all functions, regardless of source language. -By default, end lines are computed only in C/C++ files. -.br -This option has no effect if -.I derive_function_end_lines -is disabled. - -Default is 0 (disabled). -.PP - -.BR trivial_function_threshold " =" -.IR integer -.IP -Set the maximum size of function (in number of lines) which will be checked -by -.I \-\-filter trivial filter. -.br - -Default is 5. -.PP - -.BR excessive_count_threshold " =" -.IR number -.IP -Set the threshold for hit count that lcov deems excessive/unlikely/indicating -a bug somewhere in your toolchain. -.br For example, it is unlikely that your job can run long enough to rack up -tens of billions of hits. -.br Message type -.B excessive -is used to report potential issue - see the -.B genhtml(1), lcov(1), geninfo(1) -man pages. - -Default is not set. (Do not check for excessive counts.) -.PP - -. -.BR geninfo_gcov_tool " =" -.I path_to_gcov -.IP -Specify the location of the gcov tool (see -.BR gcov (1)) -which is used to generate coverage information from data files. -.br - -This option can be used multiple times - e.g., to add arguments to the gcov -callback. See the geninfo man page for details. - -.PP - -.BR geninfo_adjust_testname " =" -.IR 0 | 1 -.IP -If non\-zero, adjust test names to include operating system information -when capturing coverage data. -.br - -Default is 0. -.PP - -.BR forget_testcase_names " =" -.IR 0 | 1 -.IP -If non\-zero, ignore testcase names in .info file. -This may improve performance and reduce memory consumption if user does -not need per-testcase coverage summary in coverage reports. - -This is equivalent to the "\-\-forget\-test\-names" lcov/genhtml option. -.br - -Default is 0. -.PP - -.BR checksum " =" -.IR 0 | 1 -.IP -If non\-zero, generate source code checksums when capturing coverage data. -Checksums are useful to prevent merging coverage data from incompatible -source code versions but checksum generation increases the size of coverage -files and the time used to generate those files. -.br - -This option can be overridden by the \-\-checksum and \-\-no\-checksum command line -options. -.br - -Default is 0. - -Note that this options is somewhat subsumed by the -.I version_script -option - which does something similar, but at the 'whole file' level. - -.PP - -.BR geninfo_compat_libtool " =" -.IR 0 | 1 -.IP -If non\-zero, enable libtool compatibility mode. When libtool compatibility -mode is enabled, lcov will assume that the source code relating to a .da file -located in a directory named ".libs" can be found in its parent directory. -.br - -This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool -command line option of -.BR geninfo . -.br - -Default is 1. -.PP - -.BR geninfo_external " =" -.IR 0 | 1 -.IP -If non\-zero, capture coverage data for external source files. - -External source files are files which are not located in one of the directories -(including sub-directories) -specified by the \-\-directory or \-\-base\-directory options of -.BR lcov / geninfo . -Also see the -.I \-\-follow -option and the -.I geninfo_follow_symlinks -and -.I geninfo_follow_file_links -for additional path controls. - -Default is 1. -.PP - -.BR geninfo_capture_all " =" -.IR 0 | 1 -.IP -If non\-zero, capture coverage data from both runtime data files as -well as compile time data files which have no corresponding runtime data. -See the -.I \-\-all -flag description in -.B man(1) geninfo -for more information. - -Default is 0: do not process bare compile-time data files. -.PP - -.BR geninfo_external " =" -.IR 0 | 1 -.IP -If non\-zero, capture coverage data for external source files. - -External source files are files which are not located in one of the directories -(including sub-directories) -specified by the \-\-directory or \-\-base\-directory options of -.BR lcov / geninfo . -Also see the -.I \-\-follow -option and the -.I geninfo_follow_file_links -for additional path controls. - -Default is 1. -.PP - -.BR geninfo_follow_symlinks " =" -.IR 0 | 1 -.IP -Equivalent to the lcov/geninfo -.I \-\-follow -command line option. -See man -.B geninfo(1) -for details. - -Default is 0: do not modify follow symbolic links. -.PP - -.BR geninfo_follow_file_links " =" -.IR 0 | 1 -.IP -If non\-zero and the lcov/geninfo -.I \-\-follow -command line option is specified, then source file pathnames which contain -symlinks are resolved to their actual target. -Note that the parent directory of the link target may be considered 'external' -and thus be removed by the -.I \-\-no\-external -flag. - -Default is 0: do not modify pathnames. -.PP - - -.BR geninfo_gcov_all_blocks " =" -.IR 0 | 1 -.IP -If non\-zero, call the gcov tool with option --all-blocks. - -Using --all-blocks will produce more detailed branch coverage information for -each line. Set this option to zero if you do not need detailed branch coverage -information to speed up the process of capturing code coverage or to work -around a bug in some versions of gcov which will cause it to endlessly loop -when analyzing some files. - -Default is 1. -.PP - -.BR geninfo_unexecuted_blocks " =" -.IR 0 | 1 -.IP -If non\-zero, adjust the 'hit' count of lines which have attribute -.I "unexecuted_block": true -but which contain no branches and have a non-zero count. -Assume that these lines are not executed. - -Note that this option is effective only for gcov versions 9 and newer. - -Default is 0. -.PP - -.BR geninfo_compat " =" -.IR mode = value [, mode = value ,...] -.IP -Specify that geninfo should enable one or more compatibility modes -when capturing coverage data. - -This option corresponds to the \-\-compat command line option of -.BR geninfo . - -Default is 'libtool=on, hammer=auto, split_crc=auto'. -.PP - -.BR geninfo_adjust_src_path " =" -.IR pattern " => " replacement -.br -.BR geninfo_adjust_src_path " =" -.I pattern -.IP -Adjust source paths when capturing coverage data. - -Use this option in situations where geninfo cannot find the correct -path to source code files of a project. By providing a -.I pattern -in Perl regular expression format (see -.BR perlre (1)) -and an optional replacement string, you can instruct geninfo to -remove or change parts of the incorrect source path. - -.B Example: -.br - -1. When geninfo reports that it cannot find source file -.br - - /path/to/src/.libs/file.c -.br - -while the file is actually located in -.br - - /path/to/src/file.c -.br - -use the following parameter: -.br - - geninfo_adjust_src_path = /.libs - -This will remove all "/.libs" strings from the path. - -2. When geninfo reports that it cannot find source file -.br - - /tmp/build/file.c -.br - -while the file is actually located in -.br - - /usr/src/file.c -.br - -use the following parameter: -.br - - geninfo_adjust_src_path = /tmp/build => /usr/src -.br - -This will change all "/tmp/build" strings in the path to "/usr/src". - -The -.I adjust_src_path -option is similar to the -.I substitution = ... -option - which is somewhat more general and allows you to specify -multiple substitution patterns. Also see the -.I resolve_script -option. -.PP - -.BR source_directory " =" -.IR dirname -.IP - -Add 'dirname' to the list of places to look for source files. -Also see the -.I \-\-source\-directory -entry in the -.B lcov, geninfo, -and -.B genhtml -man pages. -.br - -For relative source file paths -.I e.g., -found in some -.IR tracefile -or in gcov output, -first look for the path from 'cwd' (where genhtml was -invoked) and -then from each alternate directory name in the order specified. -The first location matching location is used. - -This option can be specified multiple times, to add more directories to the source search path. - -Note that the command line option overrides the RC file entries (if any). -.PP - -.BR build_directory " =" -.IR dirname -.IP - -Add 'dirname' to the list of places to look for matching GCNO files (geninfo) or source file soft links (genhtml). -See the the -.I \-\-build\-directory -description in the -.B geninfo -and in the -.B genhtml -man page. -.br - -This option can be specified multiple times, to add more directories to the source search path. - -Note that the command line option overrides the RC file entries (if any). -.PP - -.BR geninfo_auto_base " =" -.IR 0 | 1 -.IP -If non\-zero, apply a heuristic to determine the base directory when -collecting coverage data. -.br - -Use this option when using geninfo on projects built with libtool or -similar build environments that work with multiple base directories, -i.e. environments, where the current working directory when invoking the -compiler is not the same directory in which the source code file is -located, and in addition, is different between files of the same project. -.br - -Default is 1. -.PP - -.BR geninfo_intermediate " =" -.IR 0 | 1 | auto -.IP -Specify whether to use gcov intermediate format -.br - -Use this option to control whether geninfo should use the gcov intermediate -format while collecting coverage data. The use of the gcov intermediate format -should increase processing speed. It also provides branch coverage data when -using the \-\-initial command line option. -.br - -Valid values are 0 for off, 1 for on, and "auto" to let geninfo automatically -use immediate format when supported by gcov. -.br - -Default is "auto". -.PP - -.BR no_exception_branch " =" -.IR 0 | 1 -.IP -Specify whether to exclude exception branches from branch coverage. -Whether C++ exception branches are identified and removed is dependent on your compiler/toolchain correctly marking them in the generated coverage data. - -This option is used by lcov, geninfo, genhtml. - -The value -.I no_exception_branch = 1 -is equivalent to the -.I \-\-filter exception -command line option. - -Default is 0. -.PP - -.BR geninfo_chunk_size " =" -.IR integer [%] -.IP -Specify the number of GCDA files which should be processed per-call in each child process. -This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism. - -The default is 80% of -.I total_number_of_gcda_files / maximum_number_of_parallel_children, -the average number of files expected to be processed by each child. -See the -.I \-\-parallel -entry in the -.B geninfo -man page. - -The argument may be either an integer value to be used as the chunk size or -a percentage of the average number files processed per child. - -This option has no effect unless the -.I \-\-parallel -option has been specified. - -.PP -.BR geninfo_interval_update " =" -.IR integer -.IP -Seet the percentage of GCDA files which should be processed between console/progress -updates. This setting may be useful for parameter tuning and debugging apparent performance issues. - -The default is 5%. - -This option has no effect unless the -.I \-\-parallel -option has been specified. - -.PP - -.BR lcov_filter_chunk_size " =" -.IR integer [%] -.IP -Specify the number of source files which should be processed per-call in each child process when applying coverpoint filters - see the -.BR filter = ... -parameter, below. -This parameter affects the balance of CPU time spent in the child and thus the number of completed child processes which are queued to be merged into the parent - which then affects the queuing delay. Higher queuing delay lowers the effective parallelism. - -The default is 80% of -.I total_number_of_source_files / maximum_number_of_parallel_children. - -The argument may be either an integer value to be used as the chunk size or -a percentage of the average number files processed per child. - -This option has no effect unless the -.I \-\-parallel -option has been specified and -.BR lcov_filter_parallel -is not zero. - -.PP - -.BR lcov_filter_parallel " = 0 | 1" -.IP - -This option specifies whether coverpoint filtering should be done serially or in parallel. If the number of files to process is very large, then parallelization may improve performance. - -This option has no effect unless the -.I \-\-parallel -option has been specified. - -The default is 1 (enabled). - - -.PP -.BR lcov_gcov_dir " =" -.I path_to_kernel_coverage_data -.IP -Specify the path to the directory where kernel coverage data can be found -or leave undefined for auto-detection. -.br - -Default is auto-detection. -.PP - -.BR lcov_tmp_dir " =" -.I temp -.IP -Specify the location of a directory used for temporary files. -.br - -Default is '/tmp'. -.PP - -.BR lcov_list_full_path " =" -.IR 0 | 1 -.IP -If non-zero, print the full path to source code files during a list operation. -.br - -This option corresponds to the \-\-list\-full\-path option of -.BR lcov . -.br - -Default is 0. -.PP - -.BR lcov_list_max_width " =" -.IR width -.IP -Specify the maximum width for list output. This value is ignored when -lcov_list_full_path is non\-zero. -.br - -Default is 80. -.PP - -.BR lcov_list_truncate_max -.B " =" -.IR percentage -.IP -Specify the maximum percentage of file names which may be truncated when -choosing a directory prefix in list output. This value is ignored when -lcov_list_full_path is non\-zero. -.br - -Default is 20. -.PP - -.BR function_coverage " =" -.IR 0 | 1 -.IP -Specify whether lcov/geninfo/genhtml should generate, process, and -display function coverage data. -.br - -Turning off function coverage by setting this option to 0 can -sligly reduce memory and CPU time consumption -when lcov is collecting and processing coverage data, as well as -reduce the size of the resulting data files. -.br - -This option can be overridden by the -.I \-\-function\-coverage -and -.I \-\-no\-function\-coverage -command line options. -.br - -Default is 1. -.PP - -.BR branch_coverage " =" -.IR 0 | 1 -.IP -Specify whether lcov/geninfo should generate, process, and display branch -coverage data. -.br - -Turning off branch coverage by setting this option to 0 can reduce -memory and CPU time consumption -when lcov is collecting and processing coverage data, as well as -reduce the size of the resulting data files. -.br - -This option can be overridden by the -.I \-\-branch\-coverage -and -.I \-\-no\-branch\-coverage - command line options. -.br - -Default is 0. -.PP - -.BR mcdc_coverage " =" -.IR 0 | 1 -.IP -Specify whether lcov/geninfo should generate, process, and display Modified -Condition / Decision Coverage (MC/DC) -coverage data. -.br - -Turning off MC/DC coverage by setting this option to 0 can reduce -memory and CPU time consumption -when lcov is collecting and processing coverage data, as well as -reduce the size of the resulting data files. -.br - -This option can be overridden by the -.I \-\-mcdc\-coverage - command line option. -.br - -Default is 0 (not enabled). - -.br -See the MC/DC section of man -.B genhtml(1) -for more details -.PP - -.BR lcov_excl_line " =" -.I expression -.IP -Specify the regular expression of lines to exclude. -Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped. -.br - -There are at least 2 (moderately) common use cases for custom exclusion markers: -.br -- You are using multiple tools for coverage analysis, each of which has its own directives, and you don't want to complicate your source code with directives for each of them. -.br -- You want to exclude different regions/different types of code in different contexts - for example, to ignore or not ignore debug/trace code depending on your team. - -Default is 'LCOV_EXCL_LINE'. -.PP - -.BR lcov_excl_br_line " =" -.I expression -.IP -Specify the regular expression of lines to exclude from branch coverage. -Branch coverpoints are associated with lines where this regexp is found are dropped. (Line and function coverpoints are not affected.) -.br - -Default is 'LCOV_EXCL_BR_LINE'. -.PP - -.BR lcov_excl_exception_br_line " =" -.I expression -.IP -Specify the regular expression of lines to exclude from exception branch coverage. -Exception-related Branch coverpoints associated with lines where this regexp is found are dropped. (Line, function coverpoints are not affected. Branch coverpoints which are not associated with exceptions are also not affected.) - -Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed. - -.br -Note that this feature requires support from your compiler - and thus may not ignore all exception-related coverpoints. -.br - -Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'. -.PP - -.BR lcov_excl_start " =" -.IR expression -.IP -Specify the regexp mark the start of an exception region -All coverpoints within exception regions are dropped. -.br - -Default is 'LCOV_EXCL_START'. - -.PP - -.BR lcov_excl_stop " =" -.IR expression -.IP -Specify the regexp mark the end of an exception region -.br - -Default is 'LCOV_EXCL_STOP'. - -.PP - -.BR lcov_excl_br_start " =" -.IR expression -.IP -Specify the regexp used to mark the start of a region where branch coverpoints are excluded. -Line and function coverpoints within the region are not excluded. -.br - -Default is 'LCOV_EXCL_BR_START'. - -.PP - -.BR lcov_excl_br_stop " =" -.IR expression -.IP -Specify the regexp used to mark the end of a region where branch coverpoints are excluded. -.br - -Default is 'LCOV_EXCL_BR_STOP'. - - -.PP - -.BR lcov_excl_exception_br_start " =" -.IR expression -.IP -Specify the regexp used to mark the start of a region where branch coverpoints associated with exceptions are excluded. -Line, function, and non-exception branch coverpoints within the region are not excluded. - -Also see 'geninfo_no_exception_branch'; if nonzero, then all identified exception branches will be removed. - -Note that exception branch coverpoint identification requires support from your compiler - and thus may not ignore all exception-related coverpoints. -.br - -Default is 'LCOV_EXCL_EXCEPTION_BR_START'. - -.PP - -.BR lcov_excl_exception_br_stop " =" -.IR expression -.IP -Specify the regexp used to mark the end of a region where exception-related branch coverpoints are excluded. -.br - -Default is 'LCOV_EXCL_EXECEPTION_BR_STOP'. - -.BR lcov_unreachable_line " =" -.I expression -.IP -Specify the regular expression of unreachable line which should be excluded from reporting, but should generate an "inconsistent" error if hit. -That is: we believe that the marked code is unreachable, so there is a bug in the code, the placement of the directive, or both if the "unreachable" code is executed. -Line, branch, and function coverpoints are associated with lines where this regexp is found are dropped. -.br - -Default is 'LCOV_UNREACHABLE_LINE'. -.PP - -.BR lcov_unreachable_start " =" -.IR expression -.IP -Specify the regexp mark the start of an unreachable code block. -All coverpoints within exception regions are dropped, but the tool will generate -an "inconsistent" error if any code in the block is executed. -.br - -Default is 'LCOV_UNREACHABLE_START'. - -.PP - -.BR lcov_unreachable_stop " =" -.IR expression -.IP -Specify the regexp mark the end of the unreachable code block. -.br - -Default is 'LCOV_UNREACHABLE_STOP'. - -.PP - -.BR fail_under_branches " =" -.I percentage -.IP -Specify branch coverage threshold: if the branch coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code. -.br - -This option is equivalent to the \-\-fail\-under\-branches lcov/genhtml/geninfo command line argument. See -.B man lcov(1) -for more detailes. - -.br -The default is 0 (no threshold). -.PP - -.BR retain_unreachable_coverpoints_if_executed " =" -.I [0 | 1] -.IP -Specify whether coverpoints in "unreachable" regions which are 'hit' are -dropped (0) - because the region is excluded - or retained (1) - because -the directive appears to be incorrect. -.br -See the "Exclusion markers" section in man -.B geninfo(1) -for more details. - - -The default is 1 (retain the coverpoints). -.PP - -.BR fail_under_lines " =" -.I percentage -.IP -Specify line coverage threshold to lcov. If the line coverage is below this threshold, lcov/genhtml/geninfo will generate all the normal result files and messages, but will return a non-zero exit code. -.br - -This option is equivalent to the \-\-fail\-under\-lines lcov/genhtml/geninfo command line argument. - -.br -The default is 0 (no threshold). - -.PP - -.BR profile " =" -.IR filename -.IP -If set, tells genhtml, lcov, or geninfo to generate some execution -time/profile data which can be used to motivate future optimizations. -It is equivalent to the -.I \-\-profile -command line option. - -If -.I filename -is empty, then the profile is written to the default location chosen by the application. - -.br -This option is used by genhtml, lcov, and geninfo. - -The default is unset: no data generated. - -.PP - -.BR parallel " =" -.IR integer -.IP -Tells genhtml, lcov, or geninfo the maximum number of simultaneous processes -to use. Zero means to use as many cores as are available on the machine. -The default is 1 (one) - which means to process sequentially (no parallelism). - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR memory " =" -.IR integer_Mb -.IP -Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing -operations. Effectively, the process will not fork() if this limit would be -exceeded. -Zero means that there is no limit. -The default is 0 (zero) - which that there is no explicit limit. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR memory_percentage " =" -.IR number -.IP -Tells genhtml, lcov, or geninfo the maximum memory to use during parallel processing -operations. Maximum is computed as a percentage of the total memory -available on the system; for example, '75' would use limit to 75% of -total memory, whereas 150.5 would limit to 150.5% ( -.I i.e., -larger than the total available. -Effectively, the process will not fork() if this limit would be -exceeded. -Note that this value is used only if the maximum memory value is not -set explicitly - either by a the -.I \-\-memory -command line option or the -.I memory = integer -configuration file setting. - -The default is not not set. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR max_fork_fails " =" -.IR integer -.IP -Tells genhtml, lcov, or geninfo the number of consecutive fork() failures -to ignore during -.I \-\-parallel -execution before giving up. -Note that genhtml/lcov/geninfo fail and stop immediately unless the -.I fork -error message ignored - either via the -.I ignore_errors -directive (above), the -.I \-\-ignore\-errors -command line option, or if -.I stop_on_error -is disabled or the -.I \-\-keep-going -command line option is used. - -The default fork failure maximum is 5. - -.PP - -.BR fork_fail_timeout " =" -.IR integer_seconds -.IP -Tells genhtml, lcov, or geninfo how long to wait after a fork() failure -before retrying. - -The default is 10 (seconds). - -.PP - -.BR max_tasks_per_core " =" -.IR integer -.IP -This is the maximum number of files that genhtml will handle in a single -child process during parallel execution. - -The default is 20. - -.PP - -.BR genhtml_date_bins " =" -.IR integer[,integer..] -.IP -This option is equivalent to the "genhtml \-\-date\-bins" option. -See man -.B genhtml(1) -for details. - -This option can be used multiple times in the lcovrc file to set multiple cutpoints. - -.PP - -.BR genhtml_datelabels " =" -.IR string[,string..] -.IP -This option is equivalent to the "genhtml \-\-date\-labels" option. -See man -.B genhtml(1) -for details. - -This option can be used multiple times in the lcovrc file to set multiple labels. -The number of labels should equal one greater than number of cutpoints. - -.PP - -.BR genhtml_annotate_script " =" -.IR path_to_executable | parameter -.IP -This option is equivalent to the "genhtml \-\-annotate\-script" option. - -This option can be used multiple times in the lcovrc file to specify both an annotation script and additional options which are passed to the script. - -See the genhtml man page for details. - -.PP - -.BR genhtml_annotate_tooltip " =" -.IR tooltip_string -.IP - -This option sets the 'tooltip' popup which appears if user hovers mouse over -the associated source code. -Note that the tooltop is generated only if the annotation-script callback -is successful and returns a commit ID other than "NONE". -Set -.I tooltip_string -to "" (empty string) to force genhtml to not produce the tooltip. - -Substitutions are performed on -.I tooltip_string: - -.IP " %C:" -commit ID (from annotate callback - see -.I --anotate-script -entry in the -.B genhtml -man page) -.IP " %U:" -commit author abbreviated name (returned by annotate callback) -.IP " %F:" -commit author full name (returned by annotate callback) -.IP " %D:" -commit date (as returned by annotate callback) -.IP " %d:" -commit date with time of day removed (i.e., date part only) -.IP " %A:" -commit age. -.IP " %l" -source line number. - -.PP - - -.BR context_script " =" -.IR path_to_executable_or_module | parameter -.IP -This option is equivalent to the -.I \-\-context\-script -option of genhtml/lcov/geninfo - -This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script. - -See the genhtml man page for details. - -.PP - - - -.BR criteria_script " =" -.IR path_to_executable_or_module | parameter -.IP -This option is equivalent to the -.I \-\-criteria\-script -option of genhtml/lcov/geninfo - -This option can be used multiple times in the lcovrc file to specify both a criteria script and additional options which are passed to the script. - -See the genhtml man page for details. - -.PP - -.BR criteria_callback_data " =" -.IR comma_separated_list -.IP -This option is used to tell genhtml whether you want date and/or owner summary -data passed back to your criteria callback. -Note that summary data is always passed. - -Note that lcov and geninfo do not record date or owner data - and so do not pass -it to the callback. - -This option can be used multiple times in the lcovrc file to specify both date and owner data should be returned, or you can specify both in a comma-separated list. -Date and/or owner data will be returned if and only if your genhtml command -has enabled annotation. - -If this option is appears multiple times in the lcovrc file; the values are combined to form the list of binning types which are passed to your callback. - -See the genhtml man page for details. - -.PP - -.BR criteria_callback_levels " =" -.IR comma_separated_list -.IP -This option is used to tell genhtml whether criteria callbacks should occur -at the top, directory, or file level. - -If this option is appears multiple times in the lcovrc file, the values are combined to form the list of report levels when your callback will be executed. - -See the genhtml man page for details. - -.PP - -.BR check_existence_before_callback " =" -.IR 0 | 1 -.IP -This option configures the tool to check that the file exists before calling -the -.I annotate-script -or -.I version-script -callback. If set and file does not exist, a -.B source -error is triggered. (Note that the error may be ignored - see the -.I \-\-ignore\-error -option.) - -You may want to NOT check for file existence if your callback looks -up information in a non-local repository. - -The default is 1 (check for file existence). - -.PP - -.BR compute_file_version " =" -.IR 0 | 1 -.IP -This option is used to tell the tool to generate missing file version -information when reading a .info (coverage data) file. -Version information may be missing because the data was generated by a tool which did not support versioning, or because the data was generated without the required -.I \-\-version\-script -argument - or for some other reason. - -Note that this option has no effect without a version\-script callback - -defined by either the -.I \-\-version\-script -command line option or the -.I version_script -config file option. - -The default is 0: do not generate missing information. - -.PP - -.BR version_script " =" -.IR path_to_executable | parameter -.IP -This option is equivalent to the geninfo/lcov/genhtml "\-\-version\-script" option. - -This option can be used multiple times in the lcovrc file to specify both a version script and additional options which are passed to the script. - -See the genhtml man page for details. - -.PP - -.BR resolve_script " =" -.IR path_to_executable | parameter -.IP -This option is equivalent to the geninfo/lcov/genhtml "\-\-resolve\-script" option. - -This option can be used multiple times in the lcovrc file to specify both a resolve script and additional options which are passed to the script. - -The resolve script provides a mechanism to find a -source or data file that cannot be found by simply modify paths via substitution -patterns (see -.I "substitute = replace_regexp" -above) and searching along the corresponding directory list: -.RS -.IP -.B geninfo: -the -.I "'build_directory = dirname'" -config file entry -or -.I \-\-build\=directory -command line option, used to search for GCNO files, -.PP -.IP -.B geninfo/genhtml/lcov: -the -.I "'source_directory = dirname'" -config file entry -or -.I \-\-source\=directory -command line option, used to search for source files. -.PP -.RE - -.RS -The resolve script is called as: -.IP -.B resolve_script -[callback_args] -.I " file_name" -.PP - -or -.IP -.I $resolve_callback = -.B resolve_module -.I ->new([callback_args]) -.PP -to initialize the callback, then -.IP -.I $resolve_callback-> -.B resolve -.I (file_name) -.PP -to find the actual file location. - -If necessary, the callback can check the suffix of the filename to determine -whether it should look for either a source or data file. -.PP - -The script should return either empty string (file not found/no such file) or the actual -path name. The returned path may be either absolute or relative to CWD. -.RE -.PP - -.BR select_script " =" -.IR path_to_executable | parameter -.IP -This option is equivalent to the genhtml "\-\-select\-script" option. - -This option can be used multiple times in the lcovrc file to specify both a select script and additional options which are passed to the script. - -The select script provides a mechanism to decide whether a particular -source line is interesting - whether it should be included in the -generated -coverage report - or not. - -Lines which are not selected but fall within -.I num_context_lines -of a selected line are also included in the report. See below. - -Note that selection is fundamentally intended to show regions of code with some surrounding context. It might not do what you expect if there is no code - e.g., if the region of interest has been compiled out via compiler or exclusion directives. -For example: when selecting based on SHA or changelist ID, an inserted comment will not be selected unless it is within -.I num_context_lines -of an inserted or changed line of code. - -The select script is called as: - -.B " select_script" -[callback_args] -.I lineDataJson annotateDataJson fileName lineNumber - -or as: - -.I " $selectCallback =" -.B select_module -.I ->new([callback_args]) - -to initialize the callback object, then as - -.I " " $selectCallback -.B select -.I (lineDataRef annotateDataRef fileName lineNumber) - -.RS -to determine selection, -where -.IP \- 3 -.I fileName -is the name of the source file and -.PP -.IP \- 3 -.I lineNumber -is the source file line number, indexed from zero, -.PP -.IP \- 3 -.I lineDataJson -is a json-encoded LineData structure (see the lcovutil.pm source code), and -.PP -.IP \- 3 -.I annotateDataJson -is the json-encoded data returned by your -.I annotate\-script -(see the -.I \-\-annotate\-script -parameter in man -.B genhtml(1). -), or the empty string if there are no annotations for this file. -.PP -The module callback is similar except that is is passed objects rather than JSON encodings of the objects. -.RE - -The script should return "1" or "0". - -See example implementation -.I $LCOV_HOME/share/lcov/support-scripts/select.pm. -.RE - -.PP - -.BR unreachable_script " =" -.IR path_to_module | parameter -.IP -This option is equivalent to the geninfo/lcov/genhtml "\-\-unreachable\-script" option. - -This option can be used multiple times in the lcovrc file to specify both a module script and additional options which are passed to the callback. - -See the genhtml man page for details. - -.PP - -.BR num_context_lines " = " -.IR integer -.IP -Set the number of lines around each selected line which is included in the -report - see -.I select_script = ... -above and the -.I \-\-select\-script -command line option in man -.B genhtml(1). -.PP - -.BR filter " =" -.IR str[,str...] -.IP - -This option is equivalent to the \-\-filter option to geninfo, lcov, and genhtml. -See the genhtml man page for details. - -This option can be used multiple times in the lcovrc file to enable multiple filters. -The filters specified in the lcovrc file are appended to the list specified on the command line. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR exclude " =" -.IR glob_pattern -.IP - -This option is equivalent to the \-\-exclude option to geninfo, lcov, and genhtml. -See the lcov man page for details.; - -This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. -The patterns specified in the lcovrc file are appended to the list specified on the command line. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR include " =" -.IR glob_pattern -.IP - -This option is equivalent to the \-\-include option to geninfo, lcov, and genhtml. -See the lcov man page for details.; - -This option can be used multiple times in the lcovrc file to specify multiple patterns to include. -The patterns specified in the lcovrc file are appended to the list specified on the command line. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR simplify_script " =" -.IR path_to_executable | parameter -.IP - -This option is equivalent to the genhtml -.I \-\-simplify\-script - option. -This option can be used multiple times in the lcovrc file to specify both a simplify script and additional options which are passed to the script. - -See man -.B genhtml(1) -for details. - -.PP - -.BR substitute " =" -.IR regexp -.IP - -This option is equivalent to the \-\-substitute option to geninfo, lcov, and genhtml. -See the lcov man page for details.; - -This option can be used multiple times in the lcovrc file to specify multiple substitution patterns. -If patterns are specified on both the command line and in the lcovrc file, then -the command line patterns are used and the lcovrc patterns are dropped. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR omit_lines " =" -.IR regexp -.IP - -This option is equivalent to the \-\-omit\-lines option to geninfo, lcov, and genhtml. -See the genhtml man page for details. - -This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. -The patterns specified in the lcovrc file are appended to the list specified on the command line. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR erase_functions " =" -.IR regexp -.IP - -This option is equivalent to the \-\-erase\-functions option to geninfo, lcov, and genhtml. -See the genhtml man page for details. - -This option can be used multiple times in the lcovrc file to specify multiple patterns to exclude. -The patterns specified in the lcovrc file are appended to the list specified on the command line. - -.br -This option is used by genhtml, lcov, and geninfo. - -.PP - -.BR lcov_json_module " =" -.IR module | auto -.IP -Specify the JSON module to use, or choose best available from a set of -alternatives if set to 'auto'. Note that some JSON modules are slower than -others (notably JSON::PP can be very slow compared to JSON::XS). -.br - -Default is 'auto'. - -.PP - -.BR split_char " =" -.IR char -.IP -Specify the character (or regexp) used to split list-like parameters which have -been passed as a single string. -This parameter is useful in the case that you need want to use a multi-option -string but one or more of the options contains a comma character which would -otherwise be seen as a delimiter. -.br - -Default is ',' (comma - no quotes). - -.PP - -.BR scope_regexp " =" -.IR regexp -.IP -Print debug messages for data in filenames which match -.I regexp. -.br -Only certain categories of message are logged; the set changes from time -to time - depending on debug need. - -.PP - -.BR case_insensitive " =" -.IR [0|1] -.IP -Specify whether string comparison is case insensitive when finding matching -filenames, checking include/exclude directives, etc. -.br - -Note that mixed-case or lower-case pathnames may be passed to your \-\-version\-script and \-\-annotate\-script callbacks when case-insensitive matching is used. Your callbacks must handle potential differences in case. - -Default is '0': case sensitive matching. - -.PP - -.BR sort_input " =" -.IR [0|1] -.IP -Specify whether to sort file names before capture and/or aggregation. -Sorting reduces certain types of processing order-dependent output differences - -.I e.g., -due to ambiguities in branch data generated by gcc. -.br - -Default is '0': no sorting - process files in the order they were specified on the command line and/or were found during traversal of the filesystem. - -.PP - - -.SH FILES - -.TP -.I $LCOV_HOME/etc/lcovrc -The system\-wide -.B lcov -configuration file. - -.TP -.I ~/.lcovrc -The individual per\-user configuration file. -.PP - -.SH SEE ALSO -.BR lcov (1), -.BR genhtml (1), -.BR geninfo (1), -.BR gcov (1) diff --git a/scripts/P4version.pm b/scripts/P4version.pm index e008ef41..587ba891 100644 --- a/scripts/P4version.pm +++ b/scripts/P4version.pm @@ -131,7 +131,7 @@ sub new my $depot_path = $1; my $version = $2 ? "#$2" : '@head'; my $filename = $3; - next unless -e $filename; # filename has ben deleted + next unless -e $filename; # filename has been deleted my $full = Cwd::abs_path($filename); die("unexpected depot filename $filename") unless $root eq substr($filename, 0, $len); diff --git a/scripts/annotateutil.pm b/scripts/annotateutil.pm index cbe39e2a..ef9c48d1 100644 --- a/scripts/annotateutil.pm +++ b/scripts/annotateutil.pm @@ -51,7 +51,7 @@ sub not_in_repo while (my $line = ) { chomp $line; # Also remove CR from line-end - s/\015$//; + $line =~ s/\015$//; push(@$lines, [$line, $owner, undef, $mtime, "NONE"]); } diff --git a/scripts/batchGitVersion.pm b/scripts/batchGitVersion.pm index 0cedcba6..9339db80 100644 --- a/scripts/batchGitVersion.pm +++ b/scripts/batchGitVersion.pm @@ -90,7 +90,7 @@ EOF might have expected. The second call queries DB to find 'pathname'. - - 'pathname' may be be a file name which is found in the git repo, but + - 'pathname' may be a file name which is found in the git repo, but with some prefix prepended. For example: pathname: /build/directory/path/repo/dir/file filename: repo/dir/file @@ -189,7 +189,7 @@ sub new $db{File::Spec->catfile(@prepend, $2)} = $1; } elsif (/^\d+\s+commit\s+(\S+)\s+(\S+)$/) { # line format: mode commit sha path - die("duplicate submodule etnry for $2") if exists($submodule{$2}); + die("duplicate submodule entry for $2") if exists($submodule{$2}); $submodule{$2} = $1; } else { print(STDERR "$errLeader$_"); diff --git a/scripts/get_signature b/scripts/get_signature index 86e9b1ff..7aefd55b 100755 --- a/scripts/get_signature +++ b/scripts/get_signature @@ -63,7 +63,7 @@ unless (-e $filename) { die("Error: $filename does not exist - perhaps you need the '--allow-missing' flag" ); } -$pathname = abs_path($filename); +my $pathname = abs_path($filename); #my $sum = `sha512sum $pathname`; my $sum = `md5sum $pathname`; diff --git a/scripts/gitblame.pm b/scripts/gitblame.pm index 766d9a36..0a4ff34b 100644 --- a/scripts/gitblame.pm +++ b/scripts/gitblame.pm @@ -159,7 +159,7 @@ sub annotate_callback while (my $line = ) { chomp $line; # Also remove CR from line-end - s/\015$//; + $line =~ s/\015$//; if ($line =~ m/^(\S+)[^(]+\(<([^>]*)>\s+([-0-9]+\s+[0-9:]+\s+[-+0-9]+)\s+([0-9]+)\) (.*)$/ diff --git a/scripts/gitdiff b/scripts/gitdiff index 96ba49b2..0080188c 100755 --- a/scripts/gitdiff +++ b/scripts/gitdiff @@ -9,7 +9,7 @@ use Getopt::Long; use strict; -use Cwd /realpath/; +use Cwd qw(realpath); my $verbose = 0; @@ -155,7 +155,7 @@ while () { } close(HANDLE) or die("failed to close git diff pipe: $!"); if (0 != $?) { - $? & 0x7F & die("git diff died from signal ", ($? & 0x7F), "\n"); + $? & 0x7F && die("git diff died from signal ", ($? & 0x7F), "\n"); die("git diff exited with error ", ($? >> 8), "\n"); } @@ -181,7 +181,7 @@ while () { } close(HANDLE) or die("failed to close git ls-tree pipe: $!"); if (0 != $?) { - $? & 0x7F & die("git ls-tree died from signal ", ($? & 0x7F), "\n"); + $? & 0x7F && die("git ls-tree died from signal ", ($? & 0x7F), "\n"); die("git ls-tree exited with error ", ($? >> 8), "\n"); } exit 0; diff --git a/scripts/p4annotate.pm b/scripts/p4annotate.pm index 768f2deb..1e779143 100644 --- a/scripts/p4annotate.pm +++ b/scripts/p4annotate.pm @@ -164,7 +164,7 @@ sub annotate_callback while ($line = ) { chomp $line; # Also remove CR from line-end - s/\015$//; + $line =~ s/\015$//; if ($line =~ m/^([0-9]+)(,([0-9]+))?([acd])([0-9]+)(,([0-9]+))?/) { # change @@ -184,7 +184,7 @@ sub annotate_callback } close(PIPE) or die("unable to close p4 diff pipe: $!\n"); if (0 != $?) { - $? & 0x7F & + ($? & 0x7F) && die("p4 pipe died from signal ", ($? & 0x7F), "\n"); die("p4 pipe exited with error ", ($? >> 8), "\n"); } @@ -215,7 +215,7 @@ sub annotate_callback chomp $line; # Also remove CR from line-end - s/\015$//; + $line =~ s/\015$//; if ($line =~ m/([0-9]+):\s+(\S+)\s+([0-9\/]+)\s(.*)/) { my $changelist = $1; diff --git a/scripts/p4udiff b/scripts/p4udiff index 647eeead..4fb3e2e1 100755 --- a/scripts/p4udiff +++ b/scripts/p4udiff @@ -113,13 +113,14 @@ sub new while (my $line = ) { chomp $line; - s/\015$//; + $line =~ s/\015$//; $self->append(P4File->new($line)); } close(HANDLE) or die("unable to close 'p4 files $p4tag' pipe: $!\n"); if (0 != $?) { - $? & 0x7F & die("p4 files $p4tag died from signal ", ($? & 0x7F), "\n"); + ($? & 0x7F) && + die("p4 files $p4tag died from signal ", ($? & 0x7F), "\n"); die("p4 files $p4tag exited with error ", ($? >> 8), "\n"); } return $self; @@ -300,12 +301,12 @@ if ($curr_changelist eq 'sandbox') { while (my $line = ) { chomp $line; - s/\015$//; + $line =~ s/\015$//; $curr_files->append(P4File->new($line), 1); # overwrite } close(HANDLE) or die("unable to close 'p4 opened' pipe: $!\n"); if (0 != $?) { - $? & 0x7F & die("p4 opened died from signal ", ($? & 0x7F), "\n"); + ($? & 0x7F) && die("p4 opened died from signal ", ($? & 0x7F), "\n"); die("'p4 opened' exited with error ", ($? >> 8), "\n"); } } @@ -345,7 +346,7 @@ my $prev_filename; my $skip = 0; while (my $line = ) { chomp $line; - s/\015$//; + $line =~ s/\015$//; # the 'diff' new/old file name line may be followed by a timestamp # If so, remove it so our regexp matches more easily. @@ -381,7 +382,8 @@ while (my $line = ) { } close(HANDLE) or die("unable to close p4 files (current) pipe: $!\n"); if (0 != $?) { - $? & 0x7F & die("p4 files (current) died from signal ", ($? & 0x7F), "\n"); + ($? & 0x7F) && + die("p4 files (current) died from signal ", ($? & 0x7F), "\n"); die("p4 files (current) exited with error ", ($? >> 8), "\n"); } @@ -416,7 +418,7 @@ foreach my $f (sort keys %union) { } close(HANDLE) or die("unable to close p4 print pipe: $!\n"); if (0 != $?) { - $? & 0x7F & die("p4 print died from signal ", ($? & 0x7F), "\n"); + ($? & 0x7F) && die("p4 print died from signal ", ($? & 0x7F), "\n"); die("p4 print exited with error ", ($? >> 8), "\n"); } printf("@@ 1,%d 0,0 @@\n", scalar(@lines)); @@ -450,7 +452,8 @@ foreach my $f (sort keys %union) { } close(HANDLE) or die("unable to close $err: $!\n"); if (0 != $?) { - $? & 0x7F & die("close $err died from signal ", ($? & 0x7F), "\n"); + ($? & 0x7F) && + die("close $err died from signal ", ($? & 0x7F), "\n"); die("close $err exited with error ", ($? >> 8), "\n"); } printf("@@ 0,0 1,%d @@\n", scalar(@lines)); diff --git a/scripts/simplify.pm b/scripts/simplify.pm index b14338bc..2d96b713 100644 --- a/scripts/simplify.pm +++ b/scripts/simplify.pm @@ -1,4 +1,4 @@ -#!/usr/bin/end perl +#!/usr/bin/env perl # Copyright (c) MediaTek USA Inc., 2025 # diff --git a/scripts/spreadsheet.py b/scripts/spreadsheet.py index fb6d6d43..1f990a2c 100755 --- a/scripts/spreadsheet.py +++ b/scripts/spreadsheet.py @@ -31,7 +31,7 @@ def __init__(self, excelFile, files, args): # parse: time to generate and read gcov data # exec: time to execute gcov # append: to merge file info into parent - geninfoKeys = ('order', 'file', 'parse', 'exec', 'append') + geninfoKeys = ['order', 'file', 'parse', 'exec', 'append'] # work: productive time: process_one_chunk + merge chunk # chunk: everything from fork() to end of filesystem cleanup after child merge @@ -121,7 +121,6 @@ def insertConditional(sheet, avgRow, devRow, good = '=AND(NOT(OR(ISBLANK(%(cell)s),ISBLANK(%(dev)s))), (%(cell)s - %(avg)s) < (%(devMaxThresh)f * -%(dev)s), %(threshold)s)' % { 'cell' : dataCell, 'threshold' : threshold, - 'cell' : dataCell, 'avg' : avgCell, 'dev' : devCell, 'devMaxThresh': devMaxThreshold, @@ -286,7 +285,7 @@ def insertStats(keys, sawData, sumRow, avgRow, devRow, beginRow, endRow, col): try: sheet.write_number(row, 3, float(d2[f]), twoDecimal) except: - print("Warning: %s: unable to write %s for lcov[seg %d][%s][$s]" % (name, str(d2[f]), seg, k, f)) + print("Warning: %s: unable to write %s for lcov[seg %d][%s][%s]" % (name, str(d2[f]), seg, k, f)) row += 1 except: print("Warning: %s: unable to write %s for lcov[seg %d]" % (name, k, seg)) @@ -317,7 +316,7 @@ def insertStats(keys, sawData, sumRow, avgRow, devRow, beginRow, endRow, col): try: sheet.write_number(row, 3, float(d2[f]), twoDecimal) except: - print("Warning: %s: unable to write %s for lcov[%s][$s]" % (name, str(d2[f]), k, f)) + print("Warning: %s: unable to write %s for lcov[%s][%s]" % (name, str(d2[f]), k, f)) row += 1 except: print("Warning: %s: failed to find key '%s'" %(name, k)) @@ -746,7 +745,7 @@ def visitScope(f): help="difference from average smaller than this percentage is ignored (not colorized). Default %0.2f" % (thresholdPercent)) parser.add_argument("--low", dest='devMinThreshold', type=float, help="difference from average larger than this * stddev colored yellow. Default: %0.2f" %(devMinThreshold)) - parser.add_argument("--high", dest='devMinThreshold', type=float, + parser.add_argument("--high", dest='devMaxThreshold', type=float, help="difference from average larger than this * stddev colored red. Default: %0.2f" %(devMaxThreshold)) parser.add_argument('-v', '--verbose', dest='verbose', default=0, action='count', help='verbosity of report: more data'); diff --git a/scripts/threshold.pm b/scripts/threshold.pm index 793f4031..78da7c57 100644 --- a/scripts/threshold.pm +++ b/scripts/threshold.pm @@ -85,7 +85,7 @@ sub new $thresh{branch} = $branch if defined($branch); $thresh{function} = $function if defined($function); $thresh{mcdc} = $mcdc if defined($mcdc); - die("$script: must specify at least of of --line, --branch, --function, --mcdc" + die("$script: must specify at least one of --line, --branch, --function, --mcdc" ) unless (%thresh); foreach my $key (keys %thresh) { my $v = $thresh{$key}; diff --git a/tests/Makefile b/tests/Makefile index d7aeebb9..21a64434 100644 --- a/tests/Makefile +++ b/tests/Makefile @@ -12,7 +12,7 @@ all: check report include common.mak -TESTS := genhtml lcov gendiffcov llvm2lcov py2lcov perl2lcov xml2lcov +TESTS := genhtml lcov llvm2lcov py2lcov perl2lcov xml2lcov # there may or may not be some .info files generated for exported # tools - py2lcov, perl2lcov, etc. We want them included in the diff --git a/tests/gendiffcov/Makefile b/tests/gendiffcov/Makefile deleted file mode 100644 index 80a9de20..00000000 --- a/tests/gendiffcov/Makefile +++ /dev/null @@ -1,3 +0,0 @@ -include ../common.mak - -TESTS := simple filter function insensitive synthesize errs diff --git a/tests/genhtml/Makefile b/tests/genhtml/Makefile index fdeebbaa..bf5be93a 100644 --- a/tests/genhtml/Makefile +++ b/tests/genhtml/Makefile @@ -4,7 +4,8 @@ include ../common.mak # (line/branch/function hit/miss stats do not match). # Those tests have probably outlived their usefulness - so eliminating for now # rather than enhancing the generation to become consistent -TESTS := full.sh zero.sh demangle.sh relative lambda exception +TESTS := full.sh zero.sh demangle.sh relative lambda exception \ + simple filter function insensitive synthesize errs DISABLED := part1.sh part2.sh target.sh diff --git a/tests/genhtml/demangle.sh b/tests/genhtml/demangle.sh index db918283..d5efe9f1 100755 --- a/tests/genhtml/demangle.sh +++ b/tests/genhtml/demangle.sh @@ -136,7 +136,7 @@ fi echo echo "Run 4: Demangle with params set from command line" -# mycppfilt.sh with parameter prepends that parameter to to each function name +# mycppfilt.sh with parameter prepends that parameter to each function name run "--demangle-cpp $MYFILT --demangle-cpp 'bbb'" if grep -q 'bbbmyfunc' ${HTML} ; then echo "Success - found myfunc prefixed by custom prefix" diff --git a/tests/gendiffcov/errs/Makefile b/tests/genhtml/errs/Makefile similarity index 100% rename from tests/gendiffcov/errs/Makefile rename to tests/genhtml/errs/Makefile diff --git a/tests/gendiffcov/errs/MsgContext.pm b/tests/genhtml/errs/MsgContext.pm similarity index 100% rename from tests/gendiffcov/errs/MsgContext.pm rename to tests/genhtml/errs/MsgContext.pm diff --git a/tests/gendiffcov/errs/genError.pm b/tests/genhtml/errs/genError.pm similarity index 100% rename from tests/gendiffcov/errs/genError.pm rename to tests/genhtml/errs/genError.pm diff --git a/tests/gendiffcov/errs/mcdc_errs.dat b/tests/genhtml/errs/mcdc_errs.dat similarity index 100% rename from tests/gendiffcov/errs/mcdc_errs.dat rename to tests/genhtml/errs/mcdc_errs.dat diff --git a/tests/gendiffcov/errs/missingRestore.pm b/tests/genhtml/errs/missingRestore.pm similarity index 100% rename from tests/gendiffcov/errs/missingRestore.pm rename to tests/genhtml/errs/missingRestore.pm diff --git a/tests/gendiffcov/errs/msgtest.sh b/tests/genhtml/errs/msgtest.sh similarity index 94% rename from tests/gendiffcov/errs/msgtest.sh rename to tests/genhtml/errs/msgtest.sh index 0553b330..ad36919f 100755 --- a/tests/gendiffcov/errs/msgtest.sh +++ b/tests/genhtml/errs/msgtest.sh @@ -179,9 +179,9 @@ if [ 0 != $? ] ; then fi fi echo lcov $LCOV_OPTS --summary initial.info --prune --ignore usage -$COVER $LCOV_TOOL $LCOV_OPTS --summary initial.info --prune --ignore usgae 2>&1 | tee prune_warn.log +$COVER $LCOV_TOOL $LCOV_OPTS --summary initial.info --prune --ignore usage 2>&1 | tee prune_warn.log if [ 0 != $? ] ; then - echo "ERROR: lcov prune faled" + echo "ERROR: lcov prune failed" if [ 0 == $KEEP_GOING ] ; then exit 1 fi @@ -213,7 +213,7 @@ if [ 0 == $? ] ; then fi grep "use new '--filter' option or old" markers.err if [ 0 != $? ] ; then - echo "ERROR: didint find usage error" + echo "ERROR: didn't find usage error" if [ 0 == $KEEP_GOING ] ; then exit 1 fi @@ -248,7 +248,7 @@ if [ 0 != $? ] ; then exit 1 fi fi -if [ !-f message_file.log] ; then +if [ ! -f message_file.log ] ; then echo "ERROR: didn't honor message_log" if [ 0 == $KEEP_GOING ] ; then exit 1 @@ -333,7 +333,7 @@ if [ 0 != ${PIPESTATUS[0]} ] ; then fi fi -echo genhtml $DIFCOV_OPTS initial.info -o select --select-script $SELECT_SCRIPT --select-script -x +echo genhtml $DIFFCOV_OPTS initial.info -o select --select-script $SELECT_SCRIPT --select-script -x $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o select --select-script $SELECT_SCRIPT --select-script -x 2>&1 | tee script_err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml select passed by accident" @@ -351,7 +351,7 @@ fi # test some 'select.pm' errors: # - --cl without annotate callback -echo genhtml $DIFCOV_OPTS initial.info -o selectErr1 --select-script $SELECT_SCRIPT,--cl,123 +echo genhtml $DIFFCOV_OPTS initial.info -o selectErr1 --select-script $SELECT_SCRIPT,--cl,123 $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o selectErr1 --select-script $SELECT_SCRIPT,--cl,123 2>&1 | tee selectErr1.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml selectErr1 passed by accident" @@ -368,7 +368,7 @@ if [ 0 != $? ] ; then fi # - --tla LBC without baseline data -echo genhtml $DIFCOV_OPTS initial.info -o selectErr2 --select-script $SELECT_SCRIPT,--tla,LBC +echo genhtml $DIFFCOV_OPTS initial.info -o selectErr2 --select-script $SELECT_SCRIPT,--tla,LBC $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o selectErr2 --select-script $SELECT_SCRIPT,--tla,LBC 2>&1 | tee selectErr2.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml selectErr2 passed by accident" @@ -385,7 +385,7 @@ if [ 0 != $? ] ; then fi # - --tla GNC without diff data -echo genhtml $DIFCOV_OPTS --baseline-file initial.info build.info -o selectErr3 --select-script $SELECT_SCRIPT,--tla,GNC +echo genhtml $DIFFCOV_OPTS --baseline-file initial.info build.info -o selectErr3 --select-script $SELECT_SCRIPT,--tla,GNC $COVER $GENHTML_TOOL $DIFFCOV_OPTS --baseline-file initial.info build.info -o selectErr3 --select-script $SELECT_SCRIPT,--tla,GNC 2>&1 | tee selectErr3.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml selectErr3 passed by accident" @@ -412,7 +412,7 @@ for arg in "--annotate-script $ANNOTATE_SCRIPT --select-script $SELECT_SCRIPT,-- "--annotate-script $GITBLAME_SCRIPT" \ " --ignore version --version-script $GITVERSION_SCRIPT,--md5,--p4" \ ; do - echo genhtml $DIFCOV_OPTS initial.info -o scriptErr ${arg},-x + echo genhtml $DIFFCOV_OPTS initial.info -o scriptErr ${arg},-x $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o scriptErr ${arg},-x 2>&1 | tee script_err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml scriptErr passed by accident" @@ -428,7 +428,7 @@ for arg in "--annotate-script $ANNOTATE_SCRIPT --select-script $SELECT_SCRIPT,-- fi fi # run again without error - echo genhtml $DIFCOV_OPTS initial.info -o scriptFixed ${arg} + echo genhtml $DIFFCOV_OPTS initial.info -o scriptFixed ${arg} $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o scriptFixed ${arg} --ignore annotate --profile 2>&1 | tee script_err.log if [ 0 != ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml scriptFixed failed" @@ -438,7 +438,7 @@ for arg in "--annotate-script $ANNOTATE_SCRIPT --select-script $SELECT_SCRIPT,-- fi done -echo genhtml $DIFCOV_OPTS initial.info -o sortTables --sort +echo genhtml $DIFFCOV_OPTS initial.info -o sortTables --sort $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o sortTables --sort 2>&1 | tee sort.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml --sort passed but should not have" @@ -455,7 +455,7 @@ if [ 0 != $? ] ; then fi -echo genhtml $DIFCOV_OPTS initial.info -o p4err --version-script $P4VERSION_SCRIPT,-x +echo genhtml $DIFFCOV_OPTS initial.info -o p4err --version-script $P4VERSION_SCRIPT,-x $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o p4err --version-script $P4VERSION_SCRIPT,-x 2>&1 | tee p4err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml select passed by accident" @@ -472,7 +472,7 @@ if [ 0 != $? ] ; then fi -echo genhtml $DIFCOV_OPTS initial.info -o select --select-script ./select.sh --rc compute_file_version=1 +echo genhtml $DIFFCOV_OPTS initial.info -o select --select-script ./select.sh --rc compute_file_version=1 $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o select --select-script ./select.sh --rc compute_file_version=1 2>&1 | tee select_scr.log if [ 0 != ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml compute_version failed" @@ -501,7 +501,7 @@ fi # and again, as a differential report with annotation NOW=`date` rm -rf mycache -echo genhtml $DIFCOV_OPTS initial.info -o select --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info $IGNORE_ANNOTATE +echo genhtml $DIFFCOV_OPTS initial.info -o select --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info $IGNORE_ANNOTATE $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o select --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info --title 'selectExample' --header-title 'this is the header' --date-bins 1,5,22 --baseline-date "$NOW" --prefix x --no-prefix $IGNORE_ANNOTATE 2>&1 | tee select_scr.log if [ 0 != ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml cache failed" @@ -520,7 +520,7 @@ for i in `find mycache -type f` ; do echo xyz > $i done # have to ignore version mismatch becaure p4annotate also computes version -echo genhtml $DIFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info --ignore version $IGNORE_ANNOTATE +echo genhtml $DIFFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info --ignore version $IGNORE_ANNOTATE $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info --title 'selectExample' --header-title 'this is the header' --date-bins 1,5,22 --baseline-date "$NOW" --prefix x --no-prefix --ignore version $IGNORE_ANNOTATE 2>&1 | tee cacheFail.log if [ '' == $IGNORE_ANNOTATE ] ; then @@ -542,7 +542,7 @@ fi # make cache file unreadable find mycache -type f -exec chmod ugo-r {} \; -echo genhtml $DIFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info $IGNORE_ANNOTATE +echo genhtml $DIFFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info $IGNORE_ANNOTATE $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o cacheFail --select-script ./select.sh --annotate $ANNOTATE_SCRIPT,--cache,mycache --baseline-file initial.info --title 'selectExample' --header-title 'this is the header' --date-bins 1,5,22 --baseline-date "$NOW" --prefix x $IGNORE_ANNOTATE --no-prefix 2>&1 | tee cacheFail2.log if [ '' == $IGNORE_ANNOTATE ] ; then @@ -566,7 +566,7 @@ fi # differential report with empty diff file touch diff.txt -echo genhtml $DIFCOV_OPTS initial.info -o empty --diff diff.txt --annotate $ANNOTATE_SCTIPT --baseline-file initial.info +echo genhtml $DIFFCOV_OPTS initial.info -o empty --diff diff.txt --annotate $ANNOTATE_SCRIPT --baseline-file initial.info $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o empty --diff diff.txt --annotate $ANNOTATE_SCRIPT --baseline-file initial.info 2>&1 | tee empty_diff.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml did not fail empty diff eheck" @@ -721,7 +721,7 @@ fi for callback in select annotate criteria simplify unreachable ; do - echo genhtml $DIFCOV_OPTS initial.info -o $callback --${callback}-script ./genError.pm + echo genhtml $DIFFCOV_OPTS initial.info -o $callback --${callback}-script ./genError.pm $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o $callback --${callback}-script ./genError.pm 2>&1 | tee ${callback}_err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml $callback error passed by accident" @@ -741,7 +741,7 @@ done # check callback fails in save/restore/start/finalize callbacks SKIP_ARG='' for cb in start save restore finalize ; do - echo genhtml $DIFCOV_OPTS initial.info -o simplify_$cb --simplify-script ./parallelFail.pm$SKIP_ARG --parallel + echo genhtml $DIFFCOV_OPTS initial.info -o simplify_$cb --simplify-script ./parallelFail.pm$SKIP_ARG --parallel LCOV_FORCE_PARALLEL=1 $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o simplify_$cb --simplify-script ./parallelFail.pm$SKIP_ARG --parallel 2>&1 | tee simplify_${cb}_err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml simplify '$cb' passed by accident" @@ -760,8 +760,8 @@ for cb in start save restore finalize ; do done # test help message in 'unreach.pm' -echo genhtml $DIFCOV_OPTS initial.info -o help --unreachable $SCRIPT_DIR/unreach.pm,--help --parallel $ignore -LCOV_FORCE_PARALLEL=1 $COVER $GENHTML_TOOL $DIFCOV_OPTS initial.info -o help --unreachable $SCRIPT_DIR/unreach.pm,--help --parallel $ignore 2>&1 | tee unreach_help.log +echo genhtml $DIFFCOV_OPTS initial.info -o help --unreachable $SCRIPT_DIR/unreach.pm,--help --parallel $ignore +LCOV_FORCE_PARALLEL=1 $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o help --unreachable $SCRIPT_DIR/unreach.pm,--help --parallel $ignore 2>&1 | tee unreach_help.log if [ 0 == ${PIPESTATUS[0]} ] ; then @@ -780,7 +780,7 @@ fi for ignore in '' '--ignore package' ; do - echo genhtml $DIFCOV_OPTS initial.info -o missingRestore --simplify-script ./missingRestore.pm --parallel $ignore + echo genhtml $DIFFCOV_OPTS initial.info -o missingRestore --simplify-script ./missingRestore.pm --parallel $ignore LCOV_FORCE_PARALLEL=1 $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o missingRestore --simplify-script ./missingRestore.pm --parallel $ignore 2>&1 | tee missingRestore.log status=${PIPESTATUS[0]} if [ '' == "$ignore" ] ; then @@ -808,7 +808,7 @@ for ignore in '' '--ignore package' ; do done -echo genhtml $DIFCOV_OPTS initial.info -o unused_src --source-dir ../.. +echo genhtml $DIFFCOV_OPTS initial.info -o unused_src --source-dir ../.. $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o unused_src --source-dir ../.. 2>&1 | tee src_err.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml source-dir error passed by accident" @@ -910,7 +910,7 @@ if [ 0 != $? ] ; then fi for err in "--rc truncate_owner_table=top,x" "--rc owner_table_entries=abc" "--rc owner_table_entries=-1" ; do - echo genhtml $DIFCOV_OPTS initial.info -o subset --annotate $ANNOTATE_SCRIPT --baseline-file initial.info --show-owners $IGNORE_ANNOTATE + echo genhtml $DIFFCOV_OPTS initial.info -o subset --annotate $ANNOTATE_SCRIPT --baseline-file initial.info --show-owners $IGNORE_ANNOTATE $COVER $GENHTML_TOOL $DIFFCOV_OPTS initial.info -o subset --annotate $ANNOTATE_SCRIPT --baseline-file initial.info --title 'subset' --header-title 'this is the header' --date-bins 1,5,22 --baseline-date "$NOW" --prefix x --no-prefix $err --show-owners $IGNORE_ANNOTATE if [ 0 == $? ] ; then echo "ERROR: genhtml $err unexpectedly passed" diff --git a/tests/gendiffcov/errs/parallelFail.pm b/tests/genhtml/errs/parallelFail.pm similarity index 100% rename from tests/gendiffcov/errs/parallelFail.pm rename to tests/genhtml/errs/parallelFail.pm diff --git a/tests/gendiffcov/errs/select.sh b/tests/genhtml/errs/select.sh similarity index 100% rename from tests/gendiffcov/errs/select.sh rename to tests/genhtml/errs/select.sh diff --git a/tests/genhtml/exception/exception.sh b/tests/genhtml/exception/exception.sh index b4871682..45c30b64 100755 --- a/tests/genhtml/exception/exception.sh +++ b/tests/genhtml/exception/exception.sh @@ -149,7 +149,7 @@ BRH_th=${BASH_REMATCH[1]} # 5 bf=$(($BRF_no + $BRF_th)) bh=$(($BRH_no + $BRH_th)) if [ "$bf" != "$BRF" ] ; then - echo "unexpected BRF total: founr $bf expected $BRF" + echo "unexpected BRF total: found $bf expected $BRF" STATUS=1 if [ $KEEP_GOING == 0 ] ; then exit 1 @@ -157,7 +157,7 @@ if [ "$bf" != "$BRF" ] ; then fi if [ "$bh" != "$BRH" ] ; then - echo "unexpected BRH total: founr $bh expected $BRH" + echo "unexpected BRH total: found $bh expected $BRH" STATUS=1 if [ $KEEP_GOING == 0 ] ; then exit 1 diff --git a/tests/gendiffcov/filter/Makefile b/tests/genhtml/filter/Makefile similarity index 100% rename from tests/gendiffcov/filter/Makefile rename to tests/genhtml/filter/Makefile diff --git a/tests/gendiffcov/filter/brace.c b/tests/genhtml/filter/brace.c similarity index 100% rename from tests/gendiffcov/filter/brace.c rename to tests/genhtml/filter/brace.c diff --git a/tests/gendiffcov/filter/brace.info b/tests/genhtml/filter/brace.info similarity index 100% rename from tests/gendiffcov/filter/brace.info rename to tests/genhtml/filter/brace.info diff --git a/tests/gendiffcov/filter/expr1.c b/tests/genhtml/filter/expr1.c similarity index 100% rename from tests/gendiffcov/filter/expr1.c rename to tests/genhtml/filter/expr1.c diff --git a/tests/gendiffcov/filter/expr2.c b/tests/genhtml/filter/expr2.c similarity index 100% rename from tests/gendiffcov/filter/expr2.c rename to tests/genhtml/filter/expr2.c diff --git a/tests/gendiffcov/filter/expr3.c b/tests/genhtml/filter/expr3.c similarity index 100% rename from tests/gendiffcov/filter/expr3.c rename to tests/genhtml/filter/expr3.c diff --git a/tests/gendiffcov/filter/expr4.c b/tests/genhtml/filter/expr4.c similarity index 100% rename from tests/gendiffcov/filter/expr4.c rename to tests/genhtml/filter/expr4.c diff --git a/tests/gendiffcov/filter/filter.pl b/tests/genhtml/filter/filter.pl similarity index 99% rename from tests/gendiffcov/filter/filter.pl rename to tests/genhtml/filter/filter.pl index c4546fad..a45d116c 100755 --- a/tests/gendiffcov/filter/filter.pl +++ b/tests/genhtml/filter/filter.pl @@ -5,7 +5,8 @@ use FindBin; use lib "$FindBin::RealBin/../../../lib"; # build dir testcase -use lib (exists($ENV{LCOV_HOME}) ? $ENV{LCOV_HOME} : "../../../lib") . '/lib/lcov'; +use lib (exists($ENV{LCOV_HOME}) ? $ENV{LCOV_HOME} : "../../../lib") . + '/lib/lcov'; use lcovutil; lcovutil::parseOptions({}, {}); diff --git a/tests/gendiffcov/filter/multilineTrivial.c b/tests/genhtml/filter/multilineTrivial.c similarity index 100% rename from tests/gendiffcov/filter/multilineTrivial.c rename to tests/genhtml/filter/multilineTrivial.c diff --git a/tests/gendiffcov/filter/multilineTrivial2.c b/tests/genhtml/filter/multilineTrivial2.c similarity index 100% rename from tests/gendiffcov/filter/multilineTrivial2.c rename to tests/genhtml/filter/multilineTrivial2.c diff --git a/tests/gendiffcov/filter/notTrivial1.c b/tests/genhtml/filter/notTrivial1.c similarity index 100% rename from tests/gendiffcov/filter/notTrivial1.c rename to tests/genhtml/filter/notTrivial1.c diff --git a/tests/gendiffcov/filter/notTrivial2.c b/tests/genhtml/filter/notTrivial2.c similarity index 100% rename from tests/gendiffcov/filter/notTrivial2.c rename to tests/genhtml/filter/notTrivial2.c diff --git a/tests/gendiffcov/filter/notTrivial3.c b/tests/genhtml/filter/notTrivial3.c similarity index 100% rename from tests/gendiffcov/filter/notTrivial3.c rename to tests/genhtml/filter/notTrivial3.c diff --git a/tests/gendiffcov/filter/notTrivial_init.c b/tests/genhtml/filter/notTrivial_init.c similarity index 100% rename from tests/gendiffcov/filter/notTrivial_init.c rename to tests/genhtml/filter/notTrivial_init.c diff --git a/tests/gendiffcov/filter/notTrivial_multiline.c b/tests/genhtml/filter/notTrivial_multiline.c similarity index 100% rename from tests/gendiffcov/filter/notTrivial_multiline.c rename to tests/genhtml/filter/notTrivial_multiline.c diff --git a/tests/gendiffcov/filter/trivial1.c b/tests/genhtml/filter/trivial1.c similarity index 100% rename from tests/gendiffcov/filter/trivial1.c rename to tests/genhtml/filter/trivial1.c diff --git a/tests/gendiffcov/filter/trivial2.c b/tests/genhtml/filter/trivial2.c similarity index 100% rename from tests/gendiffcov/filter/trivial2.c rename to tests/genhtml/filter/trivial2.c diff --git a/tests/gendiffcov/filter/trivial3.c b/tests/genhtml/filter/trivial3.c similarity index 100% rename from tests/gendiffcov/filter/trivial3.c rename to tests/genhtml/filter/trivial3.c diff --git a/tests/gendiffcov/filter/trivialMethod.c b/tests/genhtml/filter/trivialMethod.c similarity index 100% rename from tests/gendiffcov/filter/trivialMethod.c rename to tests/genhtml/filter/trivialMethod.c diff --git a/tests/gendiffcov/function/Makefile b/tests/genhtml/function/Makefile similarity index 100% rename from tests/gendiffcov/function/Makefile rename to tests/genhtml/function/Makefile diff --git a/tests/gendiffcov/function/baseline_call_current_call.gold b/tests/genhtml/function/baseline_call_current_call.gold similarity index 100% rename from tests/gendiffcov/function/baseline_call_current_call.gold rename to tests/genhtml/function/baseline_call_current_call.gold diff --git a/tests/gendiffcov/function/baseline_call_current_call_region.gold b/tests/genhtml/function/baseline_call_current_call_region.gold similarity index 100% rename from tests/gendiffcov/function/baseline_call_current_call_region.gold rename to tests/genhtml/function/baseline_call_current_call_region.gold diff --git a/tests/gendiffcov/function/baseline_call_current_nocall.gold b/tests/genhtml/function/baseline_call_current_nocall.gold similarity index 100% rename from tests/gendiffcov/function/baseline_call_current_nocall.gold rename to tests/genhtml/function/baseline_call_current_nocall.gold diff --git a/tests/gendiffcov/function/baseline_call_current_nocall_region.gold b/tests/genhtml/function/baseline_call_current_nocall_region.gold similarity index 100% rename from tests/gendiffcov/function/baseline_call_current_nocall_region.gold rename to tests/genhtml/function/baseline_call_current_nocall_region.gold diff --git a/tests/gendiffcov/function/baseline_nocall_current_call.gold b/tests/genhtml/function/baseline_nocall_current_call.gold similarity index 100% rename from tests/gendiffcov/function/baseline_nocall_current_call.gold rename to tests/genhtml/function/baseline_nocall_current_call.gold diff --git a/tests/gendiffcov/function/baseline_nocall_current_call_region.gold b/tests/genhtml/function/baseline_nocall_current_call_region.gold similarity index 100% rename from tests/gendiffcov/function/baseline_nocall_current_call_region.gold rename to tests/genhtml/function/baseline_nocall_current_call_region.gold diff --git a/tests/gendiffcov/function/baseline_nocall_current_nocall.gold b/tests/genhtml/function/baseline_nocall_current_nocall.gold similarity index 100% rename from tests/gendiffcov/function/baseline_nocall_current_nocall.gold rename to tests/genhtml/function/baseline_nocall_current_nocall.gold diff --git a/tests/gendiffcov/function/baseline_nocall_current_nocall_region.gold b/tests/genhtml/function/baseline_nocall_current_nocall_region.gold similarity index 100% rename from tests/gendiffcov/function/baseline_nocall_current_nocall_region.gold rename to tests/genhtml/function/baseline_nocall_current_nocall_region.gold diff --git a/tests/gendiffcov/function/current.cpp b/tests/genhtml/function/current.cpp similarity index 100% rename from tests/gendiffcov/function/current.cpp rename to tests/genhtml/function/current.cpp diff --git a/tests/gendiffcov/function/function.sh b/tests/genhtml/function/function.sh similarity index 99% rename from tests/gendiffcov/function/function.sh rename to tests/genhtml/function/function.sh index 5246e46f..09c783a2 100755 --- a/tests/gendiffcov/function/function.sh +++ b/tests/genhtml/function/function.sh @@ -212,7 +212,7 @@ fi for opt in '' '--forget-test-names' ; do outdir="alias$opt" echo genhtml -o $outdir $opt $DIFFCOV_OPTS template.info --show-proportion - $COVER $GENHTML_TOOL -o $outdir $pt $DIFFCOV_OPTS template.info --show-proportion + $COVER $GENHTML_TOOL -o $outdir $opt $DIFFCOV_OPTS template.info --show-proportion if [ $? != 0 ] ; then echo "genhtml $outdir failed" if [ 0 == $KEEP_GOING ] ; then diff --git a/tests/gendiffcov/function/initial.cpp b/tests/genhtml/function/initial.cpp similarity index 100% rename from tests/gendiffcov/function/initial.cpp rename to tests/genhtml/function/initial.cpp diff --git a/tests/gendiffcov/function/template.cpp b/tests/genhtml/function/template.cpp similarity index 100% rename from tests/gendiffcov/function/template.cpp rename to tests/genhtml/function/template.cpp diff --git a/tests/gendiffcov/insensitive/Makefile b/tests/genhtml/insensitive/Makefile similarity index 100% rename from tests/gendiffcov/insensitive/Makefile rename to tests/genhtml/insensitive/Makefile diff --git a/tests/gendiffcov/insensitive/annotate.sh b/tests/genhtml/insensitive/annotate.sh similarity index 100% rename from tests/gendiffcov/insensitive/annotate.sh rename to tests/genhtml/insensitive/annotate.sh diff --git a/tests/gendiffcov/insensitive/insensitive.sh b/tests/genhtml/insensitive/insensitive.sh similarity index 96% rename from tests/gendiffcov/insensitive/insensitive.sh rename to tests/genhtml/insensitive/insensitive.sh index 25024ccd..7a1ce751 100755 --- a/tests/gendiffcov/insensitive/insensitive.sh +++ b/tests/genhtml/insensitive/insensitive.sh @@ -175,7 +175,7 @@ if [ 0 != $? ] ; then fi # just ignore the version check error this time.. -echo genhtml $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATATE --show-owners all --show-noncode -o differential3 ./current.info --ignore-source,annotate,version $IGNORE +echo genhtml $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATE --show-owners all --show-noncode -o differential3 ./current.info --ignore-source,annotate,version $IGNORE $COVER $GENHTML_TOOL $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATE --show-owners all --show-noncode -o differential3 ./current.info $GENHTML_PORT --ignore source,annotate,version $IGNORE 2>&1 | tee fail2.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: expected synthesize error but didn't find" @@ -194,7 +194,7 @@ if [ 0 != $? ] ; then exit 1 fi -echo genhtml $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATATE --show-owners all --show-noncode -o differential4 ./current.info --ignore-source,annotate,version --synthesize $IGNORE +echo genhtml $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATE --show-owners all --show-noncode -o differential4 ./current.info --ignore-source,annotate,version --synthesize $IGNORE $COVER $GENHTML_TOOL $DIFFCOV_OPTS --baseline-file ./baseline.info --diff-file diff.txt --annotate-script $ANNOTATE --show-owners all --show-noncode -o differential4 ./current.info $GENHTML_PORT --ignore source,annotate,version --synthesize $IGNORE 2>&1 | tee fail3.log if [ 0 != ${PIPESTATUS[0]} ] ; then echo "ERROR: unexpected synthesize error" diff --git a/tests/gendiffcov/insensitive/version.sh b/tests/genhtml/insensitive/version.sh similarity index 100% rename from tests/gendiffcov/insensitive/version.sh rename to tests/genhtml/insensitive/version.sh diff --git a/tests/gendiffcov/simple/Makefile b/tests/genhtml/simple/Makefile similarity index 100% rename from tests/gendiffcov/simple/Makefile rename to tests/genhtml/simple/Makefile diff --git a/tests/gendiffcov/simple/annotate.sh b/tests/genhtml/simple/annotate.sh similarity index 98% rename from tests/gendiffcov/simple/annotate.sh rename to tests/genhtml/simple/annotate.sh index a48fbd2a..019927ba 100755 --- a/tests/gendiffcov/simple/annotate.sh +++ b/tests/genhtml/simple/annotate.sh @@ -1,4 +1,4 @@ -#!/bin/env perl +#!/usr/bin/env perl use strict; use warnings; diff --git a/tests/gendiffcov/simple/script.sh b/tests/genhtml/simple/script.sh similarity index 98% rename from tests/gendiffcov/simple/script.sh rename to tests/genhtml/simple/script.sh index 2ea6ffa1..64aa2402 100755 --- a/tests/gendiffcov/simple/script.sh +++ b/tests/genhtml/simple/script.sh @@ -16,7 +16,7 @@ if ! type "${CXX}" >/dev/null 2>&1 ; then echo "Missing tool: $CXX" >&2 exit 2 fi -1 + if ! python3 -c "import xlsxwriter" >/dev/null 2>&1 ; then echo "Missing python module: xlsxwriter" >&2 exit 2 @@ -513,8 +513,8 @@ for opt in "" --dark-mode --flat ; do # but not augustus.finknottle - who should have been truncated OUT='augustus.finknottle' FILES=$outDir/index.html - if [ -d $outDir/simiple/index.html ] ; then - FILES="$FILES $outDir/simiple/index.html" + if [ -d $outDir/simple/index.html ] ; then + FILES="$FILES $outDir/simple/index.html" fi for FILE in $FILES ; do for owner in henry.cox roderick.glossop ; do @@ -540,7 +540,7 @@ for opt in "" --dark-mode --flat ; do for owner in augustus.finknottle ; do grep $owner $FILE if [ 0 == $? ] ; then - echo "ERROR: unexpectedly found $owner in $outDir $FILEannotations" + echo "ERROR: unexpectedly found $owner in $outDir $FILE annotations" status=1 if [ 0 == $KEEP_GOING ] ; then exit 1 @@ -677,20 +677,20 @@ for opt in "" "--show-details" "--hier"; do fi # expect to see non-zero deleted branch count for tla in DUB DCB ; do - grep -E branch:.+$(tla):1 $outFile + grep -E branch:.+${tla}:[1-9] $outFile if [ 0 != $? ] ; then echo "ERROR: did not find expected $tla branches" - status = 1 - if [ 0 != $KEEP_GOING ] ; then + status=1 + if [ 0 == $KEEP_GOING ] ; then exit 1 fi fi if [ "$ENABLE_MCDC" == '1' ] ; then - grep -E mcdc:.+$(tla):1 $outFile + grep -E mcdc:.+${tla}:1 $outFile if [ 0 != $? ] ; then echo "ERROR: did not find expected $tla branches" - status = 1 - if [ 0 != $KEEP_GOING ] ; then + status=1 + if [ 0 == $KEEP_GOING ] ; then exit 1 fi fi @@ -814,7 +814,7 @@ done # with no sourceview -echo genhtml $DIFFCOV_OPTS --no-sourceview -branch-coverage --baseline-file ./baseline_nobranch.info --diff-file diff.txt --annotate-script `pwd`/annotate.sh --show-owners --ignore-errors source -o ./differential_nosource ./current.info $IGNORE $POPUP +echo genhtml $DIFFCOV_OPTS --no-sourceview --branch-coverage --baseline-file ./baseline_nobranch.info --diff-file diff.txt --annotate-script `pwd`/annotate.sh --show-owners --ignore-errors source -o ./differential_nosource ./current.info $IGNORE $POPUP $COVER ${GENHTML_TOOL} $DIFFCOV_OPTS --no-sourceview --branch-coverage --baseline-file ./baseline_nobranch.info --diff-file diff.txt --annotate-script `pwd`/annotate.sh --show-owners --ignore-errors source -o ./differential_nosource ./current.info $GENHTML_PORT $IGNORE $POPUP if [ 0 != $? ] ; then echo "ERROR: genhtml differential_nosource failed" @@ -1269,7 +1269,7 @@ done for tla in GNC UNC ; do grep "next $tla in" ./navigation/simple/test.cpp.gcov.html if [ 0 == $? ] ; then - echo "ERROR: found unexpected tla $TLA in result" + echo "ERROR: found unexpected tla $tla in result" status=1 if [ 0 == $KEEP_GOING ] ; then exit 1 @@ -1280,7 +1280,7 @@ done for tla in HIT MIS ; do grep "next $tla in" ./navigation/simple/test.cpp.gcov.html if [ 0 != $? ] ; then - echo "ERROR: did not find expected tla $TLA in result" + echo "ERROR: did not find expected tla $tla in result" status=1 if [ 0 == $KEEP_GOING ] ; then exit 1 @@ -1675,7 +1675,7 @@ fi grep -E "WARNING: .inconsistent.+: inconsistent diff data vs current source code: diff refers to 'current' line range" diff_range.log if [ 0 != $? ] ; then echo "did not file expected range warning" - status = 1 + status=1 if [ 0 == $KEEP_GOING ] ; then exit 1 fi diff --git a/tests/gendiffcov/simple/simple.cpp b/tests/genhtml/simple/simple.cpp similarity index 100% rename from tests/gendiffcov/simple/simple.cpp rename to tests/genhtml/simple/simple.cpp diff --git a/tests/gendiffcov/simple/simple2.cpp b/tests/genhtml/simple/simple2.cpp similarity index 100% rename from tests/gendiffcov/simple/simple2.cpp rename to tests/genhtml/simple/simple2.cpp diff --git a/tests/gendiffcov/simple/simple2.cpp.annotated b/tests/genhtml/simple/simple2.cpp.annotated similarity index 100% rename from tests/gendiffcov/simple/simple2.cpp.annotated rename to tests/genhtml/simple/simple2.cpp.annotated diff --git a/tests/gendiffcov/simple/unreach.cpp b/tests/genhtml/simple/unreach.cpp similarity index 100% rename from tests/gendiffcov/simple/unreach.cpp rename to tests/genhtml/simple/unreach.cpp diff --git a/tests/gendiffcov/synthesize/Makefile b/tests/genhtml/synthesize/Makefile similarity index 100% rename from tests/gendiffcov/synthesize/Makefile rename to tests/genhtml/synthesize/Makefile diff --git a/tests/gendiffcov/synthesize/munge.pl b/tests/genhtml/synthesize/munge.pl similarity index 100% rename from tests/gendiffcov/synthesize/munge.pl rename to tests/genhtml/synthesize/munge.pl diff --git a/tests/gendiffcov/synthesize/munge2.pl b/tests/genhtml/synthesize/munge2.pl similarity index 100% rename from tests/gendiffcov/synthesize/munge2.pl rename to tests/genhtml/synthesize/munge2.pl diff --git a/tests/gendiffcov/synthesize/synthesize.sh b/tests/genhtml/synthesize/synthesize.sh similarity index 99% rename from tests/gendiffcov/synthesize/synthesize.sh rename to tests/genhtml/synthesize/synthesize.sh index 98ae5465..81a3b8dc 100755 --- a/tests/gendiffcov/synthesize/synthesize.sh +++ b/tests/genhtml/synthesize/synthesize.sh @@ -60,7 +60,7 @@ perl munge2.pl current.info > munged2.info echo genhtml $DIFFCOV_OPTS --annotate-script `pwd`/annotate.sh --show-owners all -o annotateErr ./munged.info $COVER $GENHTML_TOOL $DIFFCOV_OPTS --annotate-script `pwd`/annotate.sh --show-owners all -o annotateErr ./munged.info 2>&1 | tee err.log -if [ 0 == ${[PIPESTATUS[0]} ] ; then +if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml did not return error" if [ 0 == $KEEP_GOING ] ; then exit 1 @@ -142,7 +142,7 @@ done echo genhtml $DIFFCOV_OPTS --annotate-script `pwd`/annotate.sh --show-owners all -o annotateErr2 ./munged2.info $COVER $GENHTML_TOOL $DIFFCOV_OPTS --annotate-script `pwd`/annotate.sh --show-owners all -o annotateErr2 ./munged2.info 2>&1 | tee err2.log -if [ 0 == ${[PIPESTATUS[0]} ] ; then +if [ 0 == ${PIPESTATUS[0]} ] ; then echo "ERROR: genhtml did not return error" if [ 0 == $KEEP_GOING ] ; then exit 1 diff --git a/tests/lcov/demangle/demangle.sh b/tests/lcov/demangle/demangle.sh index 236b90e8..2b010738 100755 --- a/tests/lcov/demangle/demangle.sh +++ b/tests/lcov/demangle/demangle.sh @@ -64,7 +64,7 @@ for k in FNA ; do grep $k: demangle.info | grep :: COUNT=`grep $k: demangle.info | grep -c ::` if [ $COUNT != '4' ] ; then - echo "expected 4 $k function entries in demangele.info - found $COUNT" + echo "expected 4 $k function entries in demangle.info - found $COUNT" exit 1 fi done @@ -72,7 +72,7 @@ done # see if we can "simplify" the function names.. for callback in './simplify.pl' "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Animal/subst1/g;s/Cat::Cat/subst2/g;s/subst2/subst3/g" "${SIMPLIFY_SCRIPT},--file,simplify.cmd" ; do - $COVER $GENHTML_TOOL --branch $PARLLEL $PROFILE -o simplify demangle.info --flat --simplify $callback + $COVER $GENHTML_TOOL --branch $PARALLEL $PROFILE -o simplify demangle.info --flat --simplify $callback if [ $? != 0 ] ; then echo "genhtml --simplify '$callback' failed" exit 1 @@ -94,14 +94,14 @@ for callback in './simplify.pl' "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Anima fi grep subst2 simplify/demangle/demangle.cpp.func.html if [ $? == 0 ] ; then - echo "iteratative substitute failed after $callback " + echo "iterative substitute failed after $callback " exit 1 fi done # test unused regexp in simplify callback for PAR in '' '--parallel' ; do - $COVER $GENHTML_TOOL --branch $PARLLEL $PROFILE -o simplify demangle.info --flat --simplify "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Animal/subst1/g;s/Cat::Cat/subst2/g;s/subst2/subst3/g;s/foo/bar/g" $PAR 2>&1 | tee simplifyErr.log + $COVER $GENHTML_TOOL --branch $PARALLEL $PROFILE -o simplify demangle.info --flat --simplify "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Animal/subst1/g;s/Cat::Cat/subst2/g;s/subst2/subst3/g;s/foo/bar/g" $PAR 2>&1 | tee simplifyErr.log if [ ${PIPESTATUS[0]} == 0 ] ; then echo "genhtml --simplify unused regexp didn't fail" exit 1 @@ -112,7 +112,7 @@ for PAR in '' '--parallel' ; do exit 1 fi - $COVER $GENHTML_TOOL --branch $PARLLEL $PROFILE -o simplify demangle.info --flat --simplify "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Animal/subst1/g;s/Cat::Cat/subst2/g;s/subst2/subst3/g;s/foo/bar/g" $PAR --ignore unused 2>&1 | tee simplifyWarn.log + $COVER $GENHTML_TOOL --branch $PARALLEL $PROFILE -o simplify demangle.info --flat --simplify "${SIMPLIFY_SCRIPT},--sep,;,--re,s/Animal::Animal/subst1/g;s/Cat::Cat/subst2/g;s/subst2/subst3/g;s/foo/bar/g" $PAR --ignore unused 2>&1 | tee simplifyWarn.log if [ ${PIPESTATUS[0]} != 0 ] ; then echo "genhtml --simplify unused regexp warn didn't pass" exit 1 @@ -139,10 +139,10 @@ fi for k in FNA ; do # how many functions reported? grep $k: vanilla.info - COUNT=`grep -v __ demangle.info | grep -c $k: vanilla.info` + COUNT=`grep -v __ demangle.info | grep -c $k:` # gcc may generate multiple entries for the inline functions.. if [ $COUNT -lt 5 ] ; then - echo "expected 5 $k function entries in $vanilla.info - found $COUNT" + echo "expected 5 $k function entries in vanilla.info - found $COUNT" exit 1 fi diff --git a/tests/lcov/errs/errs.sh b/tests/lcov/errs/errs.sh index 7093abfa..78a1edb5 100755 --- a/tests/lcov/errs/errs.sh +++ b/tests/lcov/errs/errs.sh @@ -58,7 +58,7 @@ for f in badFncLine badFncEndLine fncMismatch badBranchLine badLine ; do fi # and print the data out again.. echo lcov $LCOV_OPTS -o $f.out -a $f.info --ignore format,inconsistent - $COVER $LCOV_TOOL $LCOV_OPTS -o $f.out -a $f.info --ignore format,inconsistent --msg-log $f{3}.log + $COVER $LCOV_TOOL $LCOV_OPTS -o $f.out -a $f.info --ignore format,inconsistent --msg-log ${f}3.log if [ 0 != $? ] ; then echo "failed to ignore message ${f}3.log" status=1 @@ -167,6 +167,7 @@ fi grep 'no files matching' emptyDir.log if [ 0 != $? ] ; then echo "did not find expected empty dir message" + status=1 fi echo lcov $LCOV_OPTS -a emptyDir -a exceptionBranch1.info -o emptyDir.info --ignore empty $COVER $LCOV_TOOL $LCOV_OPTS -a emptyDir -a exceptionBranch1.info -o emptyDir.info --ignore empty 2>&1 | tee emptyDir2.log @@ -192,6 +193,7 @@ fi grep 'error in "find' noRead.log if [ 0 != $? ] ; then echo "did not find expected unreadable dir message" + status=1 fi echo lcov $LCOV_OPTS -a emptyDir -a exceptionBranch1.info -o emptyDir.info --ignore utility,empty $COVER $LCOV_TOOL $LCOV_OPTS -a emptyDir -a exceptionBranch1.info -o emptyDir.info --ignore utility,empty 2>&1 | tee noRead2.log diff --git a/tests/lcov/exception/exception.sh b/tests/lcov/exception/exception.sh index db307ae0..a04af67e 100755 --- a/tests/lcov/exception/exception.sh +++ b/tests/lcov/exception/exception.sh @@ -149,8 +149,8 @@ if [ $EXCEPTIONS != '0' ] ; then fi fi FILTER_BRANCHES=`grep BRDA: override.info | grep -v U | wc -l` - if [ $OVERRIDE_BRANCHES != $BRANCHES ] ; then - echo "did not honor exception overrides. Expected $BRANCHES found $OVERRIDE_BRANCHES" + if [ $FILTER_BRANCHES != $BRANCHES ] ; then + echo "did not honor exception overrides. Expected $BRANCHES found $FILTER_BRANCHES" if [ $KEEP_GOING == 0 ] ; then exit 1 fi @@ -168,7 +168,8 @@ if [ 0 != $? ] ; then exit 1 fi fi -VANILLA_LINES=`grep -c '^DA:' vanialla.info` +VANILLA_LINES=`grep -c '^DA:' vanilla.info` +VANILLA_FILES=`grep -c 'SF:' vanilla.info` $COVER $CAPTURE $LCOV_OPTS -o no_external.info --no-external if [ 0 != $? ] ; then @@ -179,10 +180,19 @@ if [ 0 != $? ] ; then fi NO_EXTERNAL_LINES=`grep -c '^DA:' no_external.info` -if [ "$NO_EXTERNAL_LINES" -ge "$VANILLA_LINES" ] ; then - echo "Error: no_external had no effect" - if [ $KEEP_GOING == 0 ] ; then - exit 1 +if [ $VANILLA_FILES == 1 ] ; then + if ["$NO_EXTERNAL_LINES" != "$VANILLA_LINES" ] ; then + echo "Error: unexpected line count when there are no external files (gcc/5.2.0, say)" + if [ $KEEP_GOING == 0 ] ; then + exit 1 + fi + fi +else + if [ "$NO_EXTERNAL_LINES" -ge "$VANILLA_LINES" ] ; then + echo "Error: no_external had no effect $NO_EXTERNAL_LINES -> $VANILLA_LINES" + if [ $KEEP_GOING == 0 ] ; then + exit 1 + fi fi fi diff --git a/tests/lcov/extract/extract.sh b/tests/lcov/extract/extract.sh index b43b90eb..de84f2a7 100755 --- a/tests/lcov/extract/extract.sh +++ b/tests/lcov/extract/extract.sh @@ -82,7 +82,7 @@ if [ 1 != "$NO_INITIAL_CAPTURE" ] ; then fi fi else - if [ "$VER[0]" -lt 5 ; then + if [ "${VER[0]}" -lt 5 ] ; then $COVER $CAPTURE . $LCOV_OPTS --initial -o initial2.info $IGNORE_EMPTY --profile 2>&1 | tee initial2.log if [ 0 == ${PIPESTATUS[0]} ] ; then echo "Error: unexpected error code from lcov --initial" @@ -140,7 +140,7 @@ fi # test an empty/trivial history callback # exclude code that some gcc versions suck in, from /usr/include/... -$COVER $CAPTURE . $LCOV_OPTS -o external.info $FILTER $IGNORE --profile --histor ./history.sh $EMPTY_BRANCH +$COVER $CAPTURE . $LCOV_OPTS -o external.info $FILTER $IGNORE --profile --history ./history.sh $EMPTY_BRANCH if [ 0 != $? ] ; then echo "Error: unexpected error code from lcov --capture" if [ $KEEP_GOING == 0 ] ; then @@ -1043,7 +1043,7 @@ if [ 0 != $? ] ; then exit 1 fi fi -grep -E 'SF:.*notfound.cpp' removeMissingb.info +grep -E 'SF:.*notfound.cpp' removeMissing.info if [ 0 == $? ] ; then echo "expected to remove missing file" if [ $KEEP_GOING == 0 ] ; then @@ -1082,7 +1082,7 @@ if [ 0 != $? ] ; then fi $COVER $LCOV_TOOL $LCOV_OPTS -o removeMissing_cb3.info -a missing_file.info --filter missing --resolve-script brokenCallback.pm,die --ignore callback $DERIVE_END $IGNORE_NO_FUNC 2>&1 | tee removeMissing.log -if [ ${PIPESTATUS[0]} != $? ] ; then +if [ ${PIPESTATUS[0]} != 0 ] ; then echo "filter missing callback failed" if [ $KEEP_GOING == 0 ] ; then exit 1 @@ -1116,7 +1116,7 @@ if [ 0 == $? ] ; then fi grep ERROR: err1.msg if [ 0 != $? ] ; then - echo "Error: expected error message not foune" + echo "Error: expected error message not found" if [ $KEEP_GOING == 0 ] ; then exit 1 fi @@ -1131,7 +1131,7 @@ if [ 0 == $? ] ; then fi grep ERROR: err2.msg if [ 0 != $? ] ; then - echo "Error: expected error message 2 not foune" + echo "Error: expected error message 2 not found" if [ $KEEP_GOING == 0 ] ; then exit 1 fi @@ -1146,7 +1146,7 @@ if [ 0 == $? ] ; then fi grep ERROR: err.3.msg if [ 0 != $? ] ; then - echo "Error: expected error message 3 not foune" + echo "Error: expected error message 3 not found" if [ $KEEP_GOING == 0 ] ; then exit 1 fi diff --git a/tests/lcov/extract/fakeResolve.sh b/tests/lcov/extract/fakeResolve.sh index 31337785..4f8b5550 100755 --- a/tests/lcov/extract/fakeResolve.sh +++ b/tests/lcov/extract/fakeResolve.sh @@ -1,2 +1,2 @@ #!/bin/sh -echo $1 +printf '%s\n' "$1" diff --git a/tests/lcov/format/format.sh b/tests/lcov/format/format.sh index 960aa429..6d04ca68 100755 --- a/tests/lcov/format/format.sh +++ b/tests/lcov/format/format.sh @@ -123,7 +123,7 @@ if [ 0 == ${PIPESTATUS[0]} ] ; then exit 1 fi fi -grep "ERROR: (excessive) Unexpected excessive hit count" excessive.log +grep "ERROR: (excessive) Unexpected excessive hit count" keepGoing.log if [ 0 != $? ] ; then echo "Error: expected excessive hit count message but didn't find it" if [ $KEEP_GOING == 0 ] ; then diff --git a/tests/lcov/summary/full.sh b/tests/lcov/summary/full.sh index a0579483..20923155 100755 --- a/tests/lcov/summary/full.sh +++ b/tests/lcov/summary/full.sh @@ -52,7 +52,7 @@ if [[ ! -s "${STDOUT}" ]] ; then fi # There must not be any output on stderr -if [[ -s "${FILTERED}" && $COVER == '' ]] ; then +if [[ -s "${STDERR}" && $COVER == '' ]] ; then echo "Error: Unexpected output on standard error" exit 1 fi diff --git a/tests/perl2lcov/perltest1.sh b/tests/perl2lcov/perltest1.sh index fed03221..e77edd52 100755 --- a/tests/perl2lcov/perltest1.sh +++ b/tests/perl2lcov/perltest1.sh @@ -27,7 +27,7 @@ fi # error check: try to run perl2lcov before running 'cover': $COVER ${EXEC_COVER} $PERL2LCOV_TOOL --output err.info --testname test1 ./cover_one 2>&1 | tee err.log -if [ 0 == ${PIPESTATUS[0} ] ; then +if [ 0 == ${PIPESTATUS[0]} ] ; then echo "expected to fail - but passed" exit 1 fi @@ -103,9 +103,10 @@ if [ 0 != $? ] ; then fi # how many lines now? BREGION_DA=`grep -c -E '^DA:' br_region.info` -BREGION_BR=`grep -c -E '^BRDA:' br_egion.info` -if [ $REGION_BR != $BREGION_BR ] ; then - echo "wrong branch region branch count $BR -> $BREGION_BR" +BREGION_BR=`grep -c -E '^BRDA:' br_region.info` +if [ $REGION_BR != $BR ] ; then + # 'region' filter shouldn't have taken out any branches + echo "wrong branch region branch count $REGION_BR -> $BR" exit 1 fi if [ $DA != $BREGION_DA ] ; then @@ -147,7 +148,7 @@ if [ 0 != $? ] ; then exit 1 fi fi -if [ `test ! -z x.info` ] ; then +if [ -s x.info ] ; then echo 'expected empty file - but not empty' if [ 0 == $KEEP_GOING ] ; then exit 1 diff --git a/tests/py2lcov/py2lcov.sh b/tests/py2lcov/py2lcov.sh index 7b8aa434..2259fd9a 100755 --- a/tests/py2lcov/py2lcov.sh +++ b/tests/py2lcov/py2lcov.sh @@ -191,7 +191,7 @@ if [ 0 != $? ] ; then fi fi -COUNT=`grep -c FNL: no_function.info` +COUNT=`grep -c FNL: no_functions.info` if [ 0 != $COUNT ] ; then echo "--no-function flag had no effect" if [ 0 == $KEEP_GOING ] ; then