Enhance 'function' filter to be persistent (stored in .info file).

This causes a change to the .info file format.
The change is forward compatible but not backward compatible:  newer lcov vesions can read data generated by older versions but old versions likely cannot read data generated by the new version.

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

Author: henry2cox

bin/genhtml

@@ -4483,8 +4483,6 @@ sub _countFunctionTlaData
     my %foundFunctionTlas;
     my ($src_age, $developer, $srcLine);
 
-    my $merged =
-        defined($lcovutil::cov_filter[$lcovutil::FILTER_FUNCTION_ALIAS]);
     my $h         = $func->hit();
     my $mergedTla = $h->[1];
     # LCOV_EXCL_START
@@ -4514,7 +4512,7 @@ sub _countFunctionTlaData
         }
     }
 
-    if ($merged) {
+    if ($main::merge_function_aliases) {
         _accountFunction($fileSummary, $mergedTla, $src_age);
     } else {
         my $aliases = $func->aliases();
@@ -5165,15 +5163,14 @@ sub new
     # $covtype:  'line' or 'branch'
     my ($class, $testcaseCounts, $fileDetails, $covtype) = @_;
 
-    my $merged =
-        defined($lcovutil::cov_filter[$lcovutil::FILTER_FUNCTION_ALIAS]);
     my %tlaData;
     if ($covtype != SummaryInfo::FUNCTION_DATA) {
         $tlaData{found} = $testcaseCounts->found();
         $tlaData{hit}   = $testcaseCounts->hit();
     } else {
-        $tlaData{found} = $testcaseCounts->numFunc($merged);
-        $tlaData{hit}   = $testcaseCounts->numHit($merged);
+        $tlaData{found} =
+            $testcaseCounts->numFunc($main::merge_function_aliases);
+        $tlaData{hit} = $testcaseCounts->numHit($main::merge_function_aliases);
     }
     if ($main::show_tla &&
         defined($fileDetails)) {
@@ -5219,7 +5216,7 @@ sub new
                 my $lineData     = $fileDetails->line($line);
                 my $differential = $lineData->functionElem();
                 my @data;
-                if ($merged) {
+                if ($main::merge_function_aliases) {
                     push(@data, $differential->hit());
                 } else {
                     my $aliases = $differential->aliases();
@@ -6174,6 +6171,7 @@ our $frames;            # If set, use frames for source code view
 our $keep_descriptions; # If set, do not remove unused test case descriptions
 our $suppress_function_aliases;    # if set, don't show list of collapsed
                                    # function aliases
+our $merge_function_aliases;
 our $no_sourceview;     # If set, do not create a source code view for each file
 our $legend;            # If set, include legend in output
 our $tab_size = 8;      # Number of spaces to use in place of tab
@@ -6192,7 +6190,7 @@ our @fileview_prefixes = ("");
 our @funcview_sortlist;
 our @rate_name    = ("Lo", "Med", "Hi");
 our @rate_png     = ("ruby.png", "amber.png", "emerald.png");
-our $rc_desc_html = 0;        # lcovrc: genhtml_desc_html
+our $rc_desc_html = 0;      # lcovrc: genhtml_desc_html
 our $deprecated_highlight;    # ignored former option
 
 our $cwd = cwd();             # Current working directory
@@ -6248,6 +6246,8 @@ my %genhtml_rc_opts = (
                "genhtml_sort"                => \$sort,
                "genhtml_charset"             => \$charset,
                "genhtml_desc_html"           => \$rc_desc_html,
+               'merge_function_aliases'      => \$merge_function_aliases,
+               'suppress_function_aliases'   => \$suppress_function_aliases,
                "genhtml_missed"              => \$opt_missed,
                "genhtml_dark_mode"           => \$dark_mode,
                "genhtml_hierarchical"        => \$hierarchical,
@@ -6318,13 +6318,18 @@ my %genhtml_options = ("output-directory|o=s" => \$output_directory,
                        "dark-mode"         => \$dark_mode,
                        "show-navigation"   => \$show_tla,
                        "show-proportion"   => \$show_functionProportions,
+                       "merge-aliases"     => \$merge_function_aliases,
                        "suppress-aliases"  => \$suppress_function_aliases,);
 # Parse command line options
 if (!lcovutil::parseOptions(\%genhtml_rc_opts, \%genhtml_options)) {
     print(STDERR "Use $tool_name --help to get usage information\n");
     exit(1);
 }
 
+$merge_function_aliases = 1
+    if ($suppress_function_aliases ||
+        defined($lcovutil::cov_filter[$lcovutil::FILTER_FUNCTION_ALIAS]));
+
 lcovutil::ignorable_error($lcovutil::ERROR_DEPRECATED,
                           "option '--highlight' has been removed.")
     if ($deprecated_highlight);
@@ -12131,9 +12136,8 @@ sub write_function_table(*$$$$$$$$$$)
             </tr>
 END_OF_HTML
 
-    my $merged =
-        defined($lcovutil::cov_filter[$lcovutil::FILTER_FUNCTION_ALIAS]);
-    foreach my $func (funcview_get_sorted($funcData, $type, $merged)) {
+    foreach my $func (
+         funcview_get_sorted($funcData, $type, $main::merge_function_aliases)) {
 
         my $funcEntry = $differentialMap->{$func};
         my ($count, $tla) = @{$funcEntry->hit()};

bin/geninfo

@@ -1001,17 +1001,8 @@ package main;
 #   TN:<test name>
 #
 # For each source file name referenced in the data file, there is a section
-# containing source code and coverage data:
-#
-#   SF:<absolute path to the source file>
-#   FN:<line number of function start>,<function name> for each function
-#   DA:<line number>,<execution count> for each instrumented line
-#   LH:<number of lines with an execution count> greater than 0
-#   LF:<number of instrumented lines>
-#
-# Sections are separated by:
-#
-#   end_of_record
+# containing source code and coverage data.  See geninfo(1) man page for
+# more details.
 #
 # In addition to the main source code file there are sections for each
 # #included file containing executable code. Note that the absolute path

bin/xml2lcovutil.py

@@ -450,11 +450,14 @@ def buildFunction(functions, objStack, currentObj, lastLine):
                     break
 
             # print the LCOV function data
+            idx = 0
             for f in functions:
                 totals['function'][0] += 1
+                f['idx'] = idx
+                idx += 1
                 if f['hit']:
                     totals['function'][1] += 1
-                self._outf.write("FN:%(start)d,%(end)d,%(name)s\nFNDA:%(hit)d,%(name)s\n" % f)
+                self._outf.write("FNL:%(idx)d,%(start)d,%(end)d\nFNA:%(idx)d,%(hit)d,%(name)s\n" % f)
             # print the LCOV line data.
             for lineNo in sorted(lineData.keys()):
                 checksum = ''

lcovrc

@@ -201,6 +201,9 @@ genhtml_desc_html=0
 # Show missed counts instead of hit counts
 #genhtml_missed=1
 
+# group function aliases in report - see '--merge' section in man(1) genhtml
+#merge_function_aliasess = 1
+
 # If set, suppress list of aliases in function detail table
 #suppress_function_aliases = 1
 

lib/lcovutil.pm

@@ -7161,6 +7161,7 @@ sub _read_info
     my $functionMap;
     my %excludedFunction;
     my $skipCurrentFile = 0;
+    my %fnIdxMap;
     while (<$infoHdl>) {
         chomp($_);
         my $line = $_;
@@ -7191,6 +7192,7 @@ sub _read_info
             # Retrieve data for new entry
             %nextBranchId     = ();
             %excludedFunction = ();
+            %fnIdxMap         = ();
 
             if ($verify_checksum) {
                 # unconditionally 'close' the current file - in case we don't
@@ -7364,6 +7366,32 @@ sub _read_info
                 last;
             };
 
+            # new format...
+            /^FNL:(\d+),(\d+)(,(\d+))?$/ && do {
+                last if (!$lcovutil::func_coverage);
+                my $fnIndex  = $1;
+                my $lineNo   = $2;
+                my $end_line = $4;
+                die("unexpected duplicate index $fnIndex")
+                    if exists($fnIdxMap{$fnIndex});
+                $fnIdxMap{$fnIndex} = [$lineNo, $end_line];
+                last;
+            };
+
+            /^FNA:(\d+),([^,]+),(.+)$/ && do {
+                last if (!$lcovutil::func_coverage);
+                my $fnIndex = $1;
+                my $hit     = $2;
+                my $alias   = $3;
+                die("unknown index $fnIndex")
+                    unless exists($fnIdxMap{$fnIndex});
+                my ($lineNo, $end_line) = @{$fnIdxMap{$fnIndex}};
+                my $fn =
+                    $functionMap->define_function($alias, $lineNo, $end_line);
+                $fn->addAlias($alias, $hit);
+                last;
+            };
+
             /^BRDA:(\d+),(e?)(\d+),(.+)$/ && do {
                 last if (!$lcovutil::br_coverage);
 
@@ -7594,15 +7622,14 @@ sub write_info($$$)
                                  cmp $functionMap->findKey($b)->line() or
                                  $a cmp $b } $functionMap->keylist());
 
+                my $fnIndex = -1;
+                my $f_found = 0;
+                my $f_hit   = 0;
                 foreach my $key (@functionOrder) {
-                    my $data = $functionMap->findKey($key);
-                    my $line = $data->line();
-
+                    my $data    = $functionMap->findKey($key);
                     my $aliases = $data->aliases();
-                    my $endLine =
-                        defined($data->end_line()) ?
-                        ',' . $data->end_line() :
-                        '';
+                    my $line    = $data->line();
+
                     if ($line <= 0) {
                         my $alias = (sort keys %$aliases)[0];
                         lcovutil::ignorable_error(
@@ -7611,22 +7638,21 @@ sub write_info($$$)
                         );
                         next;
                     }
-                    foreach my $alias (sort keys %$aliases) {
-                        print(INFO_HANDLE "FN:$line$endLine,$alias\n");
-                    }
-                }
-                my $f_found = 0;
-                my $f_hit   = 0;
-                foreach my $key (@functionOrder) {
-                    my $data = $functionMap->findKey($key);
-                    my $line = $data->line();
-                    next unless $line > 0;
-                    my $aliases = $data->aliases();
+                    ++$fnIndex;
+                    my $endLine =
+                        defined($data->end_line()) ?
+                        ',' . $data->end_line() :
+                        '';
+                    # print function leader
+                    print(INFO_HANDLE "FNL:$fnIndex,$line$endLine\n");
+                    ++$f_found;
+                    my $counted = 0;
                     foreach my $alias (sort keys %$aliases) {
                         my $hit = $aliases->{$alias};
-                        ++$f_found;
-                        ++$f_hit if $hit > 0;
-                        print(INFO_HANDLE "FNDA:$hit,$alias\n");
+                        ++$f_hit if $hit > 0 && !$counted;
+                        $counted ||= $hit > 0;
+                        # print the alias
+                        print(INFO_HANDLE "FNA:$fnIndex,$hit,$alias\n");
                     }
                 }
                 print(INFO_HANDLE "FNF:$f_found\n");

man/genhtml.1

@@ -97,6 +97,8 @@ genhtml \- Generate HTML view from LCOV coverage data files
 .IR num ]
 .RB [ \-\-missed ]
 .br
+.RB [ \-\-merge\-aliases ]
+.br
 .RB [ \-\-suppress\-aliases ]
 .br
 .RB [ \-\-forget\-test\-names ]
@@ -2187,7 +2189,7 @@ whose body is empty/do not contain any statements.  Commonly, these include comp
 
 Note that the
 .I trivial
-filter requires function end line information - and so requires that you use a compiler veraion which is new enough to support begin/end line reports
+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:
@@ -2923,6 +2925,28 @@ 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.
@@ -2935,14 +2959,14 @@ 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 when
-.B \-\-filter
-function is applied.
+Note that this option has an effect only if
+.B "\-\-filter function"
+has been applied to the coverage DB.
 
-This option can also be configured permanently using the configuration file
-option
-.IR suppress_function_aliases .
-.RE
+This parameter an be configured via the configuration file
+.IR merge_function_aliases
+option.  See
+.B man(5) lcovrc.
 
 
 .B \-\-forget\-test\-names

man/geninfo.1

@@ -1332,8 +1332,32 @@ See the
 .BI "\-\-version\-script " callback_script
 documentation and the sample usage in the lcov regression test examples.
 
-Following is a list of line numbers for each function name found in the
-source file:
+Function converage 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:<index>,<line number of function start>[,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:<index>,<execution count>,<name>
+.RE
+
+
+The now-obsolete function data format is:
+
+.RS
 
 .RS
 FN:<line number of function start>,[<line number of function end>,]<function name>
@@ -1352,6 +1376,7 @@ Next, there is a list of execution counts for each instrumented function:
 .RS
 FNDA:<execution count>,<function name>
 .RE
+.RE
 
 This list is followed by two lines containing the number of functions found
 and hit:
@@ -1362,6 +1387,8 @@ FNF:<number of functions found>
 FNH:<number of function hit>
 .RE
 
+Note that, as of LCOV 2.2, these numbers count function groups - not the individual aliases.
+
 Branch coverage information is stored which one line per branch:
 
 .RS