tests/symbol-scan.pl

   1 #!/usr/bin/env perl
   2 #***************************************************************************
   3 #                                  _   _ ____  _
   4 #  Project                     ___| | | |  _ \| |
   5 #                             / __| | | | |_) | |
   6 #                            | (__| |_| |  _ <| |___
   7 #                             \___|\___/|_| \_\_____|
   8 #
   9 # Copyright (C) 2010, Daniel Stenberg, <daniel@haxx.se>, et al.
  10 #
  11 # This software is licensed as described in the file COPYING, which
  12 # you should have received as part of this distribution. The terms
  13 # are also available at http://curl.haxx.se/docs/copyright.html.
  14 #
  15 # You may opt to use, copy, modify, merge, publish, distribute and/or sell
  16 # copies of the Software, and permit persons to whom the Software is
  17 # furnished to do so, under the terms of the COPYING file.
  18 #
  19 # This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  20 # KIND, either express or implied.
  21 #
  22 ###########################################################################
  23 #
  24 # This script grew out of help from Przemyslaw Iskra and Balint Szilakszi
  25 # a late evening in the #curl IRC channel on freenode.
  26 #
  27
  28 use strict;
  29 use warnings;
  30
  31 #
  32 # configurehelp perl module is generated by configure script
  33 #
  34 use configurehelp qw(
  35     $Cpreprocessor
  36     );
  37
  38 # we may get the dir root pointed out
  39 my $root=$ARGV[0] || ".";
  40
  41 # need an include directory when building out-of-tree
  42 my $i = ($ARGV[1]) ? "-I$ARGV[1] " : '';
  43
  44 my $h = "$root/include/curl/curl.h";
  45 my $mh = "$root/include/curl/multi.h";
  46
  47 my $verbose=0;
  48 my $summary=0;
  49 my $misses=0;
  50
  51 my @syms;
  52 my %doc;
  53 my %rem;
  54
  55 open H_IN, "-|", "$Cpreprocessor $i$h" || die "Cannot preprocess curl.h";
  56 while ( <H_IN> ) {
  57     if ( /enum\s+(\S+\s+)?{/ .. /}/ ) {
  58         s/^\s+//;
  59         next unless /^CURL/;
  60         chomp;
  61         s/[,\s].*//;
  62         push @syms, $_;
  63     }
  64 }
  65 close H_IN || die "Error preprocessing curl.h";
  66
  67 sub scanheader {
  68     my ($f)=@_;
  69     open H, "<$f";
  70     while(<H>) {
  71         if (/^#define (CURL[A-Za-z0-9_]*)/) {
  72             push @syms, $1;
  73         }
  74     }
  75     close H;
  76 }
  77
  78 scanheader($h);
  79 scanheader($mh);
  80
  81 open S, "<$root/docs/libcurl/symbols-in-versions";
  82 while(<S>) {
  83     if(/(^CURL[^ \n]*) *(.*)/) {
  84         my ($sym, $rest)=($1, $2);
  85         $doc{$sym}=$sym;
  86         my @a=split(/ +/, $rest);
  87         if($a[2]) {
  88             # this symbol is documented to have been present the last time
  89             # in this release
  90             $rem{$sym}=$a[2];
  91         }
  92     }
  93 }
  94 close S;
  95
  96 my $ignored=0;
  97 for my $e (sort @syms) {
  98     # OBSOLETE - names that are just placeholders for a position where we
  99     # previously had a name, that is now removed. The OBSOLETE names should
 100     # never be used for anything.
 101     #
 102     # CURL_EXTERN - is a define used for libcurl functions that are external,
 103     # public. No app or other code should ever use it.
 104     #
 105     # *_LAST and *_LASTENTRY are just prefix for the placeholders used for the
 106     # last entry in many enum series.
 107     #
 108
 109     if($e =~ /(OBSOLETE|^CURL_EXTERN|_LAST\z|_LASTENTRY\z)/) {
 110         $ignored++;
 111         next;
 112     }
 113     if($doc{$e}) {
 114         if($verbose) {
 115             print $e."\n";
 116         }
 117         $doc{$e}="used";
 118         next;
 119     }
 120     else {
 121         print $e."\n";
 122         $misses++;
 123     }
 124 }
 125
 126 #
 127 # now scan through all symbols that were present in the symbols-in-versions
 128 # but not in the headers
 129 #
 130 # If the symbols were marked 'removed' in symbols-in-versions we don't output
 131 # anything about it since that is perfectly fine.
 132 #
 133
 134 my $anyremoved;
 135
 136 for my $e (sort keys %doc) {
 137     if(($doc{$e} ne "used") && !$rem{$e}) {
 138
 139         if(!$anyremoved++) {
 140             print "Missing symbols mentioned in symbols-in-versions\n";
 141             print "Add them to a header, or mark them as removed.\n";
 142         }
 143
 144         print "$e\n";
 145         $misses++;
 146     }
 147 }
 148
 149 if($summary) {
 150     print "Summary:\n";
 151     printf "%d symbols in headers (out of which %d are ignored)\n", scalar(@syms),
 152     $ignored;
 153     printf "%d symbols in headers are interesting\n",
 154     scalar(@syms)- $ignored;
 155     printf "%d symbols are listed in symbols-in-versions\n (out of which %d are listed as removed)\n", scalar(keys %doc), scalar(keys %rem);
 156     printf "%d symbols in symbols-in-versions should match the ones in headers\n", scalar(keys %doc) - scalar(keys %rem);
 157
 158 }
 159
 160 if($misses) {
 161     exit 2; # there are stuff to attend to!
 162 }