Merge branch 'linux-test-project:master' into master

Author: Vladyyy

CONTRIBUTING

@@ -82,7 +82,7 @@ may also work, but some older versions are known not to.
 
 Please execute
     make checkstyle MODE=full UPDATE=true
-on your code and verify correctness of the reformating (if any) before
+on your code and verify correctness of the reformatting (if any) before
 submitting a pull request.
 
 Testing:
@@ -124,7 +124,7 @@ makes you think of a small project that you want to tackle:  excellent.)
 Pull requests which add tests for existing features or which enhance
 existing tests are actively encouraged.
 The lcov maintainers are painfully aware that the code coverage of the
-lcov test suite on the lcov code base is embarassingly low.
+lcov test suite on the lcov code base is embarrassingly low.
 
 Note that existing tests and/or test drivers may themselves need to be
 modified in order to work correctly on other platforms and with other
@@ -162,4 +162,4 @@ With your Signed-off-by, you certify the rules stated in section
 
 [1] https://github.com/linux-test-project/lcov
 [2] https://gcc.gnu.org
-[3] https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy
+[3] https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy

Makefile

@@ -24,7 +24,8 @@
 #                          --parallel n  - use --parallel flag
 #                          --home path   - path to lcov script
 #                          --llvm        - use LLVM rather than gcc
-#                         --keep-going  - don't stop on error
+#                         --keep-going   - don't stop on error
+#                         --verbose      - echo commands to test.log
 #                   Note that not all tests have been updated to use
 #                   all flags
 
@@ -62,12 +63,12 @@ TMP_DIR := $(shell mktemp -d)
 FILES   := $(wildcard bin/*) $(wildcard man/*) README Makefile \
 	   $(wildcard rpm/*) lcovrc
 
-EXES = lcov genhtml geninfo genpng gendesc
+EXES = lcov genhtml geninfo genpng gendesc perl2lcov py2lcov
 # there may be both public and non-public user scripts - so lets not show
 #   any of their names
 SCRIPTS = $(shell ls scripts | grep -v -E '([\#\~]|\.orig|\.bak|\.BAK)' )
 LIBS = lcovutil.pm
-# similarly, lets not talk about man pages	
+# similarly, lets not talk about man pages
 MANPAGES = $(foreach m, $(shell cd man ; ls *.1), man1/$(m)) \
 	$(foreach m, $(shell cd man ; ls *.5), man5/$(m))
 
@@ -98,7 +99,7 @@ info:
 	@echo "  check     : perform self-tests"
 	@echo "  checkstyle: check source files for coding style issues"
 	@echo "  release   : finalize release and create git tag for specified VERSION"
-	@echo "  test      : same as 'make check"
+	@echo "  test      : same as 'make check'"
 
 clean:
 	$(call echocmd,"  CLEAN   lcov")
@@ -235,15 +236,17 @@ rpms: lcov-$(VERSION).tar.gz
 
 ifeq ($(COVERAGE), 1)
 # write to .../tests/cover_db
-export COVER_DB := ./cover_db
+export COVER_DB := $(shell echo `pwd`/tests/cover_db)
+export PYCOV_DB := $(shell echo `pwd`/tests/pycov.dat)
+export HTML_RPT := ./lcov_coverage
 endif
 export TESTCASE_ARGS
 
 test: check
 
 check:
-	if [ "x$(COVERAGE)" != 'x' ] && [ ! -d tests/$(COVER_DB) ]; then \
-	  mkdir tests/$(COVER_DB) ; \
+	if [ "x$(COVERAGE)" != 'x' ] && [ ! -d $(COVER_DB) ]; then \
+	  mkdir $(COVER_DB) ; \
 	fi
 	@$(MAKE) -s -C tests check LCOV_HOME=`pwd`
 	@if [ "x$(COVERAGE)" != 'x' ] ; then \
@@ -278,7 +281,7 @@ endif
 
 release:
 	@if [ "$(origin VERSION)" != "command line" ] ; then echo "Please specify new version number, e.g. VERSION=1.16" >&2 ; exit 1 ; fi
-	@if [ -n "$$(git status --porcelain 2>&1)" ] ; then echo "The repository contains uncommited changes" >&2 ; exit 1 ; fi
+	@if [ -n "$$(git status --porcelain 2>&1)" ] ; then echo "The repository contains uncommitted changes" >&2 ; exit 1 ; fi
 	@if [ -n "$$(git tag -l v$(VERSION))" ] ; then echo "A tag for the specified version already exists (v$(VERSION))" >&2 ; exit 1 ; fi
 	@echo "Preparing release tag for version $(VERSION)"
 	git checkout master

README

@@ -54,6 +54,8 @@ Further README contents
   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/py2lcov        - Tool to translate Python Coverage.py to lcov format
   bin/geninfo        - Internal tool (creates LCOV data files)
   bin/genpng         - Internal tool (creates png overviews of source files)
   man                - Directory containing man pages for included tools
@@ -179,45 +181,88 @@ 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
 ---------------------------------------------------------------------
-Requirements: compile the program in question using GCC with the options
-'-fprofile-arcs -ftest-coverage' or '--coverage'. During linking, make sure
-to specify '-lgcov' or '--coverage'.
 
-Assuming the compile directory is called "appdir", do the following:
+ a) Capture current coverage state to a file:
 
-  a) Resetting counters
+   i) C/C++ code:
 
-     lcov --directory appdir --zerocounters
+      Compile your program using the '--coverage' GCC or LLVM
+      option. During linking, make sure to specify '--coverage':
 
-  b) Capturing the current coverage state to a file
+        $ gcc -o myTest --coverage simple.c
+          OR
+        $ gcc -c file1.c file2.c ... --coverage
+        $ gcc -o myOtherTest --coverage file1.o file2.o ....
 
-     lcov --directory appdir --capture --output-file app.info
+       Run your testcase at least once:
 
-     Note that this step only works after the application has
-     been started and stopped at least once. Otherwise lcov will
-     abort with an error mentioning that there are no data/.gcda files.
+        $ path/to/my/testcase/myTest
 
-     The GCC runtime emits coverage 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.
+       Capture the current coverage state to a file:
 
-  c) Getting HTML output
+         $ lcov --directory path/to/my/testcase --capture --output-file app.info
 
-     genhtml app.info
+       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.
 
-  d) Generating a differential coverage report
+       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.
 
-     See the example in .../example (run "make test_differential")
-     as well as the examples in .../tests/gendiffcov.
+       For further information on the gcc profiling mechanism, please
+       consult the gcov man page.
 
-Point the web browser of your choice to the resulting index.html file.
+      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]
 
-Please note that independently of where the application is installed or
-from which directory it is run, the --directory statement needs to
-point to the directory in which the application was compiled.
+     - translate Perl coverage data to LCOV format:
 
-For further information on the gcc profiling mechanism, please also
-consult the gcov man page.
+         $ perl2lcov --output perlcov.info perlcov_db [perl2lcov options]
+
+     See 'perl2lcov --help' and the Devel::Cover 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. New features:
@@ -238,8 +283,8 @@ New features and capabilities fall into 7 major categories:
      and the genhtml man page for details.
 
      Related options:
-        --baseline-file, --diff-file, --annotate-script, --date-bins,
-        --new-file-as-baseline, --elide-path-mismtach
+        --baseline-file, --diff-file, --annotate-script, --select-script
+        --date-bins, --new-file-as-baseline, --elide-path-mismatch
 
   b) Error handling
 
@@ -289,7 +334,7 @@ New features and capabilities fall into 7 major categories:
 
      Other options are used to focus on or to exclude certain sections
      of code, as well as to do regexp replacement of file names - possibly
-     using case-insensitve comparison.
+     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.)
@@ -323,6 +368,9 @@ New features and capabilities fall into 7 major categories:
              Sample script: 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.
 
      The callback may be any desired script or executable - but there
      may be performance advantages if it is written as a Perl module.
@@ -335,7 +383,7 @@ New features and capabilities fall into 7 major categories:
 
      Related options:
        --annotate-script, --criteria-script, --version-script
-       --resolve-script
+       --resolve-script --select-script
 
   f) Performance
 
@@ -344,7 +392,7 @@ New features and capabilities fall into 7 major categories:
      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 contraints, as well as options to enable simple
+     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.
@@ -360,11 +408,27 @@ New features and capabilities fall into 7 major categories:
 
   g) Language support
 
-     Added 'py2lcov' script, which translates python Coverage.py XML data
-     to lcov format.
+     Added 'py2lcov' and 'perl2lcov' scripts.
+
+       - 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 the Coverage.py documentation at https://coverage.readthedocs.io,
-     as well as ".../py2lcov --help"
+          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.
 
      Other languages can be integrated using a similar approach.