Debian Codegraph @

bin/perl2lcov

raw
1 #!/usr/bin/env perl
2
3 # Copyright (c) MediaTek USA Inc., 2023-2024
4 #
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or (at
8 # your option) any later version.
9 #
10 # This program is distributed in the hope that it will be useful, but
11 # WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 # General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, see
17 # <http://www.gnu.org/licenses/>.
18 #
19 #
20 # perl2lcov [--output mydata.info] [--testname name] [options] cover_db+
21 #
22 # This script traverses perl coverage information in one or more coverage
23 # data directories (generated by the perl Devel::Cover module) and
24 # translates it into LCOV .info format.
25 #
26 # In addition to common options supported by other tools in the LCOV
27 # suite (e.g., --comment, --version-script, --ignore-error, --substitute,
28 # --exclude, etc.), the tool options are:
29 #
30 # --output filename:
31 # The lcov data will be written to the specified file - or to
32 # the file called 'perlcov.info' in the current run directory
33 # if this option is not used.
34 #
35 # --testname name:
36 # Coverage info will be associated with the testcase name provided.
37 # It is not necessary to provide a name.
38 #
39 # See the Devel::Cover documentation for directions on how to generate
40 # perl coverage data.
41
42 use Devel::Cover::DB;
43 use Devel::Cover::Truth_Table;
44 use strict;
45 use warnings;
46 use Getopt::Long;
47 use FindBin;
48
49 use lib "$FindBin::RealBin/../lib";
50 use lcovutil qw($tool_name);
51
52 sub print_usage
53 {
54 local *HANDLE = $_[0];
55
56 print(HANDLE <<END_OF_USAGE);
57 Usage: $tool_name [OPTIONS] TRACEFILE_PATTERN(S)
58
59 Translate Perl coverage directory generated by Devel::Cover to LCOV .info
60 file format.
61
62 In addition to common options supported by other tools in the LCOV
63 suite (e.g., --comment, --version-script, --ignore-error, --substitute,
64 --exclude, etc.), the tool options are:
65
66 --output filename:
67 The lcov data will be written to the specified file - or to
68 the file called 'perlcov.info' in the current run directory
69 if this option is not used.
70
71 --testname name:
72 Coverage info will be associated with the testcase name provided.
73 It is not necessary to provide a name.
74
75 See the Devel::Cover documentation for directions on how to generate
76 perl coverage data.
77
78 For example:
79
80 # write Perl line, branch, condition, and subroutine coverage data to
81 # 'myPerlDB' in the current directory
82 \$ perl -MDevel::Cover=-db,.\/myPerlDB,-coverage,statement,branch,condition,subroutine,-silent,1 myScript.pl
83 # OR: write all the coverage types that Perl knows about to 'myPerlDB2' -
84 # note that perl2lcov will ignore types it does not understand/does
85 # not use (pod, time, and path)
86 \$ perl -MDevel::Cover=-db,.\/myPerlDB2,-silent,1 myScript.pl
87 # run 'cover' from the Devel::Cover installation - to extract runtime
88 # data into a usable form. This will also generate an HTML report
89 # in 'myCoverDB'
90 \$ cover myCoverDB -silent 1
91 # run perl2lcov translator to produce LCOV format data:
92 \$ perl2lcov -o perldata.info [--testname myTestName] myCoverDB
93 # and generate a genhtml-format coverage report:
94 \$ genhtml -o html_report perldata.info ...
95
96 Note that the data generateed by Devel::Cover is not always internally
97 consistent. For example:
98
99 - some which are never called, do not appear in the coverage data.
100
101 - sometimes, a line will appear to be executed (non-zero hit count) but
102 none of its contained branch expressions have been evaluated.
103 (If the line was executed, then at least one branch condition must have
104 been evaluated.
105
106 This can cause the various tools in the lcov package to generate errors of
107 type 'inconsistent'.
108 In that case, you can:
109
110 - skip consistency checks entirely: see the 'skip_consistency_checks' section
111 in man lovrc(5)
112
113 - ignore the error: see the '--ignore-error' section in man genhtml(1)
114
115 - exclude the offending code: see the '--exclude', '--filter', and
116 '--omit-lines' sections in man genhtml(1).
117
118 END_OF_USAGE
119 }
120
121 sub findPackage
122 {
123 my ($extents, $line) = @_;
124 return undef unless @$extents;
125
126 my $min = 0;
127 my $max = $#$extents;
128 my $best;
129 while ($min <= $max) {
130 my $mid = int(($min + $max) / 2);
131 my $v = $extents->[$mid];
132 if ($line < $v->[0]) {
133 $max = $mid - 1;
134 } elsif ($line > $v->[0]) {
135 $best = $v;
136 $min = $mid + 1;
137 } else {
138 # line number matched...which ought not to happen because
139 # Deval::Cover reports subroutine start as first executable
140 # line in the function.
141 # That won't be the line containing "package ..." - unless the
142 # user wrote the whole thing on one line. Not clever. Deserves
143 # to lose, if something in here breaks.
144 return $v;
145 }
146 }
147 return $best;
148 }
149
150 $lcovutil::br_coverage = 1;
151 $lcovutil::func_coverage = 1;
152 $lcovutil::derive_function_end_line = 1;
153 $lcovutil::derive_function_end_line_all_files = 1;
154 lcovutil::save_cmd_line(\@ARGV, "$FindBin::RealBin");
155 lcovutil::set_extensions('perl', '.*');
156
157 my $testname = '';
158 my $output_file = 'perlcov.info';
159 our %options = ('testname=s' => \$testname,
160 'output|o=s' => \$output_file,);
161 if (!lcovutil::parseOptions({}, \%options)) {
162 print(STDERR "Use $lcovutil::tool_name --help to get usage information.\n");
163 exit(1);
164 }
165
166 my $info = TraceFile->new();
167
168 foreach my $db (@ARGV) {
169 # parse the other files first - to grab the data we want -
170 # Not quite sure how to map 'cond' to LCOV branch coverage.
171
172 # save a readable message before remapping the $db
173 my $msg =
174 "$db appears to be empty; perhaps you need to run 'cover $db' before executing $0.";
175 my $db = Devel::Cover::DB->new(db => $db);
176 my $cover = $db->cover;
177 my @items = $cover->items;
178 if (!@items) {
179 lcovutil::ignorable_error($lcovutil::ERROR_EMPTY, $msg);
180 next;
181 }
182 foreach my $file ($cover->items) {
183 my $filename = lcovutil::subst_file_name($file);
184 lcovutil::info("process $filename" .
185 ($filename ne $file ? " (substituted from $file)" : '') . "\n");
186 if (TraceFile::skipCurrentFile($filename)) {
187 lcovutil::info(" (excluded)\n");
188 next;
189 }
190 my $f = $cover->file($file);
191 my $fileData =
192 $info->data($file); # really, want to use stored file name
193 my $functionMap = $fileData->testfnc($testname);
194 my $lineMap = $fileData->test($testname);
195 my $branchMap = $fileData->testbr($testname);
196
197 # use statement coverage to mark un-evaluated branches
198 my ($stmts, $branches, $conditions, $subroutines);
199 my @packageExtents;
200 # Devel::Cover doesn't instrument all the functions in every file -
201 # so need a workaround to find better extents for some of them
202 my @functionExtents;
203
204 foreach my $criteria ($f->items) {
205 # some types we don't use
206 next if (grep(/^$criteria$/, ('pod', 'time', 'path')));
207 my $c = $f->criterion($criteria);
208 if ($criteria eq 'branch') {
209 $branches = $c;
210 } elsif ($criteria eq 'condition') {
211 $conditions = $c;
212 } elsif ($criteria eq 'subroutine') {
213 $subroutines = $c;
214 if (-f $file) {
215 open(GREP, '-|', 'grep', '--line-number', '-E',
216 '^\s*(package|sub) ', $file) or
217 die("unable to grep $file: $!");
218 while (<GREP>) {
219 if (/^(\d+):\s*package\s+(\S+)\s*;/) {
220 push(@packageExtents, [$1, $2 . '::']);
221 } elsif (/^(\d+):\s*sub\s+([^\s(]+)/) {
222 push(@functionExtents, [$1, $2]);
223 } else {
224 die("unexpected grep output '$_'");
225 }
226 }
227 close(GREP);
228 }
229 } elsif ($criteria eq 'statement') {
230 $stmts = $c;
231 } else {
232 lcovutil::ignorable_error($lcovutil::ERROR_UNKNOWN_CATEGORY,
233 "unexpected data type '$criteria'");
234 }
235 }
236 if (!defined($stmts)) {
237 # this seems to happen sometimes if we re-run 'cover' multiple
238 # times on the same DB - e.g., during testing.
239 lcovutil::ignorable_error($lcovutil::ERROR_UNSUPPORTED,
240 "unable to process $file without statement data");
241 next;
242 }
243 if ($lcovutil::verify_checksum &&
244 !-f $file) {
245 lcovutil::ignorable_error($lcovutil::ERROR_SOURCE,
246 "cannot read '$f': unable to compute --checksum");
247 }
248 my $version = lcovutil::extractFileVersion($file) if -f $file;
249 $fileData->version($version) if defined($version) && $version ne '';
250
251 # run through data to verify that there are no branch, function, or
252 # conditional coverpoints where there is no line data
253 foreach my $c (['branch', $branches],
254 ['condition', $conditions],
255 ['subroutine', $subroutines]
256 ) {
257 next unless defined($c->[1]);
258 foreach my $line ($c->[1]->items) {
259 lcovutil::ignorable_error($lcovutil::ERROR_INCONSISTENT_DATA,
260 'found ' . $c->[0] .
261 " coverpoint on $line but no lineCov there"
262 ) unless defined($stmts->location($line));
263 }
264 }
265
266 foreach my $line ($stmts->items) {
267 my $l = $stmts->location($line);
268 my $lineCount = $l->[0]->[0];
269 $lineMap->append($line, $lineCount);
270
271 if ($subroutines) {
272 my $s = $subroutines->location($line);
273 if (defined($s)) {
274 my ($count, $name) = @{$s->[0]};
275 if ($name !~ /(BEGIN|__ANON__)/) {
276 my $p = findPackage(\@packageExtents, $line);
277 if (defined($p)) {
278 $name = $p->[1] . $name;
279 }
280 $functionMap->define_function($name, $line);
281 $functionMap->add_count($name, $count);
282 }
283 }
284 }
285 if (defined($conditions)) {
286 my $cond = $conditions->location($line);
287 if (defined($cond)) {
288 my @br = $conditions->truth_table($line);
289 my $blockID = 0;
290 my @subst;
291 # the intent of this transform is for the branchExpr
292 # to show which parts of the condition have evaluated
293 # to true or false.
294 # However, this doesn't quite work because the truth
295 # table computed by Devel::Cover is sometimes ordered
296 # with the dependent clause after the independent
297 # one - and sometimes the opposite.
298 # For the moment: punt when we don't grok
299 foreach my $block (@br) {
300 my $counts = $block->[0];
301 my $expr = $block->[1];
302 my $simplified = $expr;
303 for (my $i = 0; $i <= $#subst; ++$i) {
304 my ($from, $to) = @{$subst[$i]};
305 $simplified =~ s/\Q$from\E/$to/;
306 }
307 my @expr;
308 while ($simplified =~
309 /(.+?)\s+(and|or|xor|&&|\|\|)\s+(.+)/) {
310 $simplified = $3;
311 $1 =~ s/^\s+|\s+$//g;
312 push(@expr, $1);
313 }
314 push(@expr, $simplified);
315 #@expr = split(/\s+(and|or|xor|&&|\|\|)\s+/, $simplified);
316 my $branchID = 0;
317 foreach my $entry (@$counts) {
318 my $taken =
319 $lineCount == 0 ? '-' : $entry->{covered};
320 my $inputs = $entry->{inputs};
321 my $branchExpr = '';
322 if (scalar(@$inputs) == scalar(@expr)) {
323 # this is the case we expect..
324 my $sep = '';
325 for (my $i = 0; $i <= $#$inputs; ++$i) {
326 my $v = $inputs->[$i];
327 next if ($v eq 'X');
328 $branchExpr .= $sep;
329 $branchExpr .= " ! " if $v eq '0';
330 $branchExpr .= $expr[$i];
331 $sep = ', ';
332 }
333 for (my $i = 0; $i <= $#subst; ++$i) {
334 my ($to, $from) = @{$subst[$i]};
335 $branchExpr =~ s/$from/($to)/;
336 }
337 $branchExpr =~ s/^\s+|\s+$//g;
338 } else {
339 # punt. Just report the original Devel::Cover
340 # expressions. Hope the user can sort it out
341 $branchExpr = $expr;
342 }
343 my $br =
344 BranchBlock->new($branchID++, $taken,
345 $branchExpr, 0);
346 $branchMap->append($line, $blockID, $br, $file);
347 }
348 push(@subst, [$expr, '__' . scalar(@subst) . '__']);
349 ++$blockID;
350 }
351 # condition data is more compreshensive than branch
352 # if both exist on the line.
353 next;
354 }
355 }
356 if (defined($branches)) {
357 my $br = $branches->location($line);
358 if (defined($br)) {
359 my ($true, $false) = @{$br->[0]->[0]};
360 my $expr = $br->[0]->[1]->{'text'};
361 my $id = 0;
362 for my $c ([$true, $expr], [$false, '! ' . $expr]) {
363 # this is not an exception...
364 my $b =
365 BranchBlock->new($id++,
366 $lineCount == 0 ? '-' : $c->[0],
367 $c->[1], 0);
368 # blockID is always zero
369 $branchMap->append($line, 0, $b, $file);
370 }
371 }
372 }
373 }
374 $fileData->sum()->union($lineMap);
375 $fileData->sumbr()->union($branchMap);
376 $fileData->func()->union($functionMap);
377
378 # have to do this manually due to some Perl quirks -
379 # in particular, there may be code outside of the subroutine we are
380 # walking...and we want to correct the end line
381 TraceFile::_deriveFunctionEndLines($fileData);
382 my $lineData = $fileData->sum();
383 my $funcData = $fileData->testfnc();
384
385 foreach my $func ($fileData->func()->valuelist()) {
386 # where is the nearest 'package' after my start line?
387 my $first = $func->line();
388 my $end = $func->end_line();
389 next unless defined($end);
390 # find package or function enclosing my end line..
391 my $last = $end;
392 foreach my $ext (\@packageExtents, \@functionExtents) {
393 while (1) {
394 my $p = findPackage($ext, $last);
395 if (defined($p) && $p->[0] > $first) {
396 $last = $p->[0] - 1;
397 lcovutil::info(1,
398 $func->name() .
399 ": found update end line $last in " .
400 $p->[1] . "\n");
401 # iterate in case there is another package above the first one
402 } else {
403 last;
404 }
405 }
406 }
407 next unless $last < $end;
408
409 # what is the last executable line before the 'package' or 'sub' decl?
410 while ($last > $first) {
411 if (defined($lineData->value($last))) {
412 last;
413 }
414 --$last;
415 }
416 lcovutil::info(1,
417 "resetting " . $func->name() .
418 " end line to $last (from $end)\n");
419 $func->set_end_line($last);
420
421 foreach my $tn ($funcData->keylist()) {
422 my $d = $funcData->value($tn);
423 my $f = $d->findKey($first);
424 $f->set_end_line($last);
425 }
426
427 } #foreach function
428
429 } # foreach file
430 } #foreach cover db
431
432 $info->applyFilters();
433 $info->add_comments(@lcovutil::comments);
434 $info->write_info_file($output_file, $lcovutil::verify_checksum);
435
436 $info->checkCoverageCriteria();
437 CoverageCriteria::summarize();
438 my $exit_code = 0 != $CoverageCriteria::coverageCriteriaStatus;
439
440 lcovutil::warn_file_patterns();
441 lcovutil::summarize_cov_filters();
442 lcovutil::summarize_messages(1); # silent if no messages
443
444 exit $exit_code;