symbol-scan.pl 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245
  1. #!/usr/bin/env perl
  2. #***************************************************************************
  3. # _ _ ____ _
  4. # Project ___| | | | _ \| |
  5. # / __| | | | |_) | |
  6. # | (__| |_| | _ <| |___
  7. # \___|\___/|_| \_\_____|
  8. #
  9. # Copyright (C) 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 https://curl.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. # SPDX-License-Identifier: curl
  23. #
  24. ###########################################################################
  25. #
  26. # This script grew out of help from Przemyslaw Iskra and Balint Szilakszi
  27. # a late evening in the #curl IRC channel.
  28. #
  29. use strict;
  30. use warnings;
  31. use vars qw($Cpreprocessor);
  32. #
  33. # configurehelp perl module is generated by configure script
  34. #
  35. my $rc = eval {
  36. require configurehelp;
  37. configurehelp->import(qw(
  38. $Cpreprocessor
  39. ));
  40. 1;
  41. };
  42. # Set default values if configure has not generated a configurehelp.pm file.
  43. # This is the case with cmake.
  44. if (!$rc) {
  45. $Cpreprocessor = 'cpp';
  46. }
  47. # we may get the dir root pointed out
  48. my $root=$ARGV[0] || ".";
  49. # need an include directory when building out-of-tree
  50. my $i = ($ARGV[1]) ? "-I$ARGV[1] " : '';
  51. my $verbose=0;
  52. my $summary=0;
  53. my $misses=0;
  54. my @manrefs;
  55. my @syms;
  56. my %doc;
  57. my %rem;
  58. # scanenum runs the preprocessor on curl.h so it will process all enums
  59. # included by it, which *should* be all headers
  60. sub scanenum {
  61. my ($file) = @_;
  62. open my $h_in, "-|", "$Cpreprocessor $i$file" || die "Cannot preprocess $file";
  63. while ( <$h_in> ) {
  64. if ( /enum\s+(\S+\s+)?{/ .. /}/ ) {
  65. s/^\s+//;
  66. next unless /^CURL/;
  67. chomp;
  68. s/[,\s].*//;
  69. push @syms, $_;
  70. }
  71. }
  72. close $h_in || die "Error preprocessing $file";
  73. }
  74. sub scanheader {
  75. my ($f)=@_;
  76. open my $h, "<", "$f";
  77. while(<$h>) {
  78. if (/^#define ((LIB|)CURL[A-Za-z0-9_]*)/) {
  79. push @syms, $1;
  80. }
  81. }
  82. close $h;
  83. }
  84. sub scanallheaders {
  85. my $d = "$root/include/curl";
  86. opendir(my $dh, $d) ||
  87. die "Can't opendir: $!";
  88. my @headers = grep { /.h\z/ } readdir($dh);
  89. closedir $dh;
  90. foreach my $h (@headers) {
  91. scanenum("$d/$h");
  92. scanheader("$d/$h");
  93. }
  94. }
  95. sub checkmanpage {
  96. my ($m) = @_;
  97. open(my $mh, "<", "$m");
  98. my $line = 1;
  99. while(<$mh>) {
  100. # strip off formatting
  101. $_ =~ s/\\f[BPRI]//;
  102. # detect global-looking 'CURL[BLABLA]_*' symbols
  103. while(s/\W(CURL(AUTH|E|H|MOPT|OPT|SHOPT|UE|M|SSH|SSLBACKEND|HEADER|FORM|FTP|PIPE|MIMEOPT|GSSAPI|ALTSVC|PROTO|PROXY|UPART|USESSL|_READFUNC|_WRITEFUNC|_CSELECT|_FORMADD|_IPRESOLVE|_REDIR|_RTSPREQ|_TIMECOND|_VERSION)_[a-zA-Z0-9_]+)//) {
  104. my $s = $1;
  105. # skip two "special" ones
  106. if($s !~ /^(CURLE_OBSOLETE|CURLOPT_TEMPLATE)/) {
  107. push @manrefs, "$1:$m:$line";
  108. }
  109. }
  110. $line++;
  111. }
  112. close($mh);
  113. }
  114. sub scanman3dir {
  115. my ($d) = @_;
  116. opendir(my $dh, $d) ||
  117. die "Can't opendir: $!";
  118. my @mans = grep { /.3\z/ } readdir($dh);
  119. closedir $dh;
  120. for my $m (@mans) {
  121. checkmanpage("$d/$m");
  122. }
  123. }
  124. scanallheaders();
  125. scanman3dir("$root/docs/libcurl");
  126. scanman3dir("$root/docs/libcurl/opts");
  127. open my $s, "<", "$root/docs/libcurl/symbols-in-versions";
  128. while(<$s>) {
  129. if(/(^[^ \n]+) +(.*)/) {
  130. my ($sym, $rest)=($1, $2);
  131. if($doc{$sym}) {
  132. print "Detected duplicate symbol: $sym\n";
  133. $misses++;
  134. next;
  135. }
  136. $doc{$sym}=$sym;
  137. my @a=split(/ +/, $rest);
  138. if($a[2]) {
  139. # this symbol is documented to have been present the last time
  140. # in this release
  141. $rem{$sym}=$a[2];
  142. }
  143. }
  144. }
  145. close $s;
  146. my $ignored=0;
  147. for my $e (sort @syms) {
  148. # OBSOLETE - names that are just placeholders for a position where we
  149. # previously had a name, that is now removed. The OBSOLETE names should
  150. # never be used for anything.
  151. #
  152. # CURL_EXTERN - is a define used for libcurl functions that are external,
  153. # public. No app or other code should ever use it.
  154. #
  155. # CURLINC_ - defines for header dual-include prevention, ignore those.
  156. #
  157. # CURL_TEMP_ - are defined and *undefined* again within the file
  158. #
  159. # *_LAST and *_LASTENTRY are just prefix for the placeholders used for the
  160. # last entry in many enum series.
  161. #
  162. if($e =~ /(OBSOLETE|^CURL_EXTERN|^CURLINC_|_LAST\z|_LASTENTRY\z|^CURL_TEMP_)/) {
  163. $ignored++;
  164. next;
  165. }
  166. if($doc{$e}) {
  167. if($verbose) {
  168. print $e."\n";
  169. }
  170. $doc{$e}="used";
  171. next;
  172. }
  173. else {
  174. print $e."\n";
  175. $misses++;
  176. }
  177. }
  178. #
  179. # now scan through all symbols that were present in the symbols-in-versions
  180. # but not in the headers
  181. #
  182. # If the symbols were marked 'removed' in symbols-in-versions we don't output
  183. # anything about it since that is perfectly fine.
  184. #
  185. my $anyremoved;
  186. for my $e (sort keys %doc) {
  187. if(($doc{$e} ne "used") && !$rem{$e}) {
  188. if(!$anyremoved++) {
  189. print "Missing symbols mentioned in symbols-in-versions\n";
  190. print "Add them to a header, or mark them as removed.\n";
  191. }
  192. print "$e\n";
  193. $misses++;
  194. }
  195. }
  196. my %warned;
  197. for my $r (@manrefs) {
  198. if($r =~ /^([^:]+):(.*)/) {
  199. my ($sym, $file)=($1, $2);
  200. if(!$doc{$sym} && !$warned{$sym, $file}) {
  201. print "$file: $sym is not a public symbol\n";
  202. $warned{$sym, $file} = 1;
  203. }
  204. }
  205. }
  206. if($summary) {
  207. print "Summary:\n";
  208. printf "%d symbols in headers (out of which %d are ignored)\n", scalar(@syms),
  209. $ignored;
  210. printf "%d symbols in headers are interesting\n",
  211. scalar(@syms)- $ignored;
  212. 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);
  213. printf "%d symbols in symbols-in-versions should match the ones in headers\n", scalar(keys %doc) - scalar(keys %rem);
  214. }
  215. if($misses) {
  216. exit 0; # there are stuff to attend to!
  217. }
  218. else {
  219. print "OK\n";
  220. }