Update README

Clarification + fix typos

Signed-off-by:  Henry Cox <[email protected]>

Signed-off-by: Henry Cox <[email protected]>

Author: henry2cox

README

@@ -1,22 +1,24 @@
 -------------------------------------------------
 - README file for the LTP GCOV extension (LCOV) -
-- Last changes: 2024-12-16
+- Last changes: 2024-12-25
 -------------------------------------------------
 
 Description
 -----------
-  LCOV is an extension of GCOV, a GNU tool which provides information about
-  what parts of a program are actually executed (i.e. "covered") while running
-  a particular test case. The extension consists of a set of Perl scripts
-  which build on the textual GCOV output to implement the following enhanced
+  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 additionally indicated using bar
-      graphs and specific colors.
+    * 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
+      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.
@@ -25,7 +27,7 @@ Description
   but works as well for coverage measurements on standard user space
   applications.
 
-  LCOV supports differential coverage, as well   as date- and owner-binning.
+  LCOV supports differential coverage, as well as date- and owner-binning.
   See:
       https://arxiv.org/abs/2008.07947
    or
@@ -35,7 +37,7 @@ Description
   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 have been added.  See
+  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.
 
@@ -205,6 +207,11 @@ Point the web browser of your choice to the resulting index.html file.
         $ 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
@@ -213,11 +220,18 @@ Point the web browser of your choice to the resulting index.html file.
 
          $ lcov --directory path/to/my/testcase --capture --output-file app.info
 
+       (LLVM users using the 'prodata 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
-         - your compile- and link command line must include flag
-           '-fcondition-coverage'
+         - 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 'prodata 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 lcov and geninfo man pages.
@@ -374,8 +388,8 @@ LCOV features and capabilities fall into 7 major categories:
 
      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 pption can be used to specify a
+     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
@@ -392,18 +406,19 @@ LCOV features and capabilities fall into 7 major categories:
 
         i) interface with the revision control system
            Sample scripts:
-             - Perforce:  see 'p4diff' and 'p4annotate'
-             - Git: see 'gitdiff' and 'gitblame'
+             - Perforce:  see 'p4diff', 'p4annotate.pm', 'p4annotate'
+             - Git: see 'gitdiff', 'gitblame.pm', 'gitblame'
         ii) verify that source code versions are compatible, and
-            Sample scripts: see 'get_signature', 'getp4version'
-            and 'gitversion'
+            Sample scripts: see 'get_signature', 'P4version.pm', 'getp4version',
+            'gitversion', 'gitversion.pm', and 'batchGitVersion.pm'
         iii) enforce a desired code coverage criteria
-             Sample script: 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.
+           Sample script:  select.pm
          vi) keep track of environment and other settings - to aid
             infrastructure debugging in more complicated use cases.
 
@@ -479,7 +494,7 @@ LCOV features and capabilities fall into 7 major categories:
           translates XML coverage data to lcov format.
           The XML data may come from Cobertura or similar tools.
 
-          See "xml2lcov --help" fir brief instructions on how to use
+          See "xml2lcov --help" for brief instructions on how to use
           the translator.
           See the Coburtura documentation for directions on how to
           generate XML data.
@@ -496,8 +511,8 @@ file.  See the lcovrc man page for details.
 -------------------------
 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 using the issue
-tracker on the LCOV code repository site at:
+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