Add '--context-script ..' callback.

Enable user to keep track of environment and other settings - to aid in
infrastructure debugging and tracking.
See man genhtml(1) for details (but note the callback is implemented by
lcov, geninfo, genhtml).
Collected data is written into '--profile' JSON output file, under key
'context'.

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

Author: henry2cox

README

@@ -387,6 +387,8 @@ New features and capabilities fall into 7 major categories:
         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.
+        vi) keep track of environment and otehr settings - to aid
+            infrastructure debugging in more complicated use cases.
 
      The callback may be any desired script or executable - but there
      may be performance advantages if it is written as a Perl module.
@@ -399,7 +401,7 @@ New features and capabilities fall into 7 major categories:
 
      Related options:
        --annotate-script, --criteria-script, --version-script
-       --resolve-script --select-script
+       --resolve-script, --select-script, --context-script
 
   f) Performance
 

bin/lcov

@@ -934,6 +934,7 @@ sub lcov_geninfo(@)
                          ['--demangle-cpp', \@lcovutil::cpp_demangle],
                          ['--include', \@lcovutil::include_file_patterns],
                          ['--exclude', \@lcovutil::exclude_file_patterns],
+                         ['--context-script', \@lcovutil::contextCallback],
                          ['--criteria-script',
                           \@CoverageCriteria::coverageCriteriaScript
                          ],

lib/lcovutil.pm

@@ -211,6 +211,10 @@ our @build_directory;
 
 our @configured_callbacks;
 
+# optional callback to keep track of whatever user decides is important
+our @contextCallback;
+our $contextCallback;
+
 # filename substitutions
 our @file_subst_patterns;
 # resolve callback
@@ -1096,6 +1100,7 @@ my %rc_common = (
              'substitute'             => \@rc_subst_patterns,
              'omit_lines'             => \@rc_omit_patterns,
              'erase_functions'        => \@rc_erase_patterns,
+             'context_script'         => \@rc_contextCallback,
              "version_script"         => \@rc_version_script,
              'resolve_script'         => \@rc_resolveCallback,
              'criteria_callback_data' =>
@@ -1184,6 +1189,7 @@ our %argCommon = ("tempdir=s"         => \$tempdirname,
                   'build-directory=s' => \@lcovutil::build_directory,
 
                   'resolve-script=s'  => \@lcovutil::resolveCallback,
+                  'context-script=s'  => \@lcovutil::contextCallback,
                   "filter=s"          => \@opt_filter,
                   "demangle-cpp:s"    => \@lcovutil::cpp_demangle,
                   "ignore-errors=s"   => \@opt_ignore_errors,
@@ -1428,7 +1434,8 @@ sub parseOptions
                      \@rc_source_directories
                     ],
                     [\@lcovutil::build_directory, \@rc_build_dir],
-                    [\@lcovutil::resolveCallback, \@rc_resolveCallback]
+                    [\@lcovutil::resolveCallback, \@rc_resolveCallback],
+                    [\@lcovutil::contextCallback, \@rc_contextCallback],
     ) {
         @{$rc->[0]} = @{$rc->[1]} unless (@{$rc->[0]});
     }
@@ -1459,6 +1466,7 @@ sub parseOptions
                     [\$CoverageCriteria::criteriaCallback,
                      \@CoverageCriteria::coverageCriteriaScript
                     ],
+                    [\$contextCallback, \@lcovutil::contextCallback],
     ) {
         lcovutil::configure_callback($cb->[0], @{$cb->[1]})
             if (@{$cb->[1]});
@@ -1481,6 +1489,9 @@ sub parseOptions
                 unless grep(/^$x$/, @$valid);
         }
     }
+    # context only gets grabbed/stored with '--profile'
+    $lcovutil::profile = ''
+        if ($contextCallback && !defined($lcovutil::profile));
 
     if (!$lcov_capture) {
         if ($lcovutil::compute_file_version &&
@@ -2894,6 +2905,29 @@ sub pipe
     return PipeHelper->new($reason, @$self, @_);
 }
 
+sub context
+{
+    my $self = shift;
+    lcovutil::info(1, 'context ' . join(' ', @$self) . "\n");
+    my $iter = $self->pipe('context');
+    return unless defined($iter);
+    my %context;
+    while (my $line = $iter->next()) {
+        chomp($line);
+        $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;
+        } else {
+            $context{key} = $value;
+        }
+    }
+    my $status = $iter->close(1);    # check error return
+
+    return \%context;
+}
+
 sub extract_version
 {
     my ($self, $filename) = @_;

man/genhtml.1

@@ -118,6 +118,9 @@ genhtml \- Generate HTML view from LCOV coverage data files
 .RB [ \-\-annotate\-script
 .IR script ]
 .br
+.RB [ \-\-context\-script
+.IR script ]
+.br
 .RB [ \-\-criteria\-script
 .IR script ]
 .br
@@ -400,6 +403,8 @@ following options:
 .RS
 .B \-\-annotate\-script
 .br
+.B \-\-context\-script
+.br
 .B \-\-criteria\-script
 .br
 .B \-\-resolve\-script
@@ -503,6 +508,39 @@ 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 hask 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 concatentated, 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

man/geninfo.1

@@ -105,6 +105,9 @@ geninfo \- Generate tracefiles from GCOV coverage data files
 .br
 .RB [ \-\-forget\-test\-names ]
 .br
+.RB [ \-\-context\-script
+.IR script_file  ]
+.br
 .RB [ \-\-criteria\-script
 .IR script_file  ]
 .br
@@ -1089,6 +1092,21 @@ 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

man/lcov.1

@@ -68,6 +68,9 @@ Capture coverage data tracefile (from compiler-generated data):
 .RB [ \-\-compat
 .IR  mode =on|off|auto]
 .br
+.RB [ \-\-context\-script
+.IR script_file ]
+.br
 .RB [ \-\-criteria\-script
 .IR script_file ]
 .br
@@ -1071,6 +1074,21 @@ When specified,
 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

man/lcovrc.5

@@ -2451,6 +2451,21 @@ 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

scripts/context.pm

@@ -0,0 +1,89 @@
+#!/usr/bin/env perl
+
+#   Copyright (c) MediaTek USA Inc., 2024
+#
+#   This program is free software;  you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation; either version 2 of the License, or (at
+#   your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY;  without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#   General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program;  if not, see
+#   <http://www.gnu.org/licenses/>.
+#
+# context
+#
+#   This script is used as a lcov/geninfo/genhtml "--context-script context" callback.
+#   It is called at the end of tool execution to collect and store data which
+#   might be useful for infrastructure debugging and/or tracking.
+#
+#   The result is a hash of key/value pairs - see man genhtml(1) for more
+#    details.
+#
+#   You may want to collect and entirely different set of data.
+#   You can also add operations to the constructor to do something earlier in
+#   processing - e.g., to write data to some other files(s), etc.
+
+package context;
+
+use strict;
+use Getopt::Long qw(GetOptionsFromArray);
+use lcovutil;
+
+our @ISA       = qw(Exporter);
+our @EXPORT_OK = qw(new);
+
+sub new
+{
+    my $class      = shift;
+    my $script     = shift;
+    my $standalone = $script eq $0;
+    my @options    = @_;
+    my $comment;
+
+    if (!GetOptionsFromArray(\@_, ('comment' => \$comment)) ||
+        (!$standalone && @_)) {
+        print(STDERR "Error: unexpected option:\n  " .
+              join(' ', @options) . "\nusage: [--comment]\n");
+        exit(1) if $standalone;
+        return undef;
+    }
+    my $self = [$script];
+
+    $self = bless $self, $class;
+    if ($comment) {
+        # 'genhtml' and certain 'lcov' modes do not write a '.info' file
+        # so the comments won't go anywhere
+        my $data = $self->context();
+        foreach my $key (sort keys %$data) {
+            push(@lcovutil::comments, $key . ': ' . $data->{$key});
+        }
+    }
+
+    return $self;
+}
+
+sub context
+{
+    my $self = shift;
+
+    my %data;
+    $data{user}         = `whoami`;
+    $data{perl_version} = $^V->{original};
+    $data{perl}         = `which perl`;
+    $data{PERL5LIB}     = $ENV{PERL5LIB}
+        if exists($ENV{PERL5LIB});
+
+    foreach my $k (keys %data) {
+        chomp($data{$k});
+    }
+
+    return \%data;
+}
+
+1;