master
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#
27# Check that the deprecated statuses of functions and enum values in header
28# files, man pages and symbols-in-versions are in sync.
30use strict;
31use warnings;
33use File::Basename;
35my $root = $ARGV[0] || ".";
36my $bldroot = $ARGV[1] || ".";
38my $incdir = "$root/include/curl";
39my $docdir = "$bldroot/docs";
40my $libdocdir = "$docdir/libcurl";
42my $errcode = 0;
44# Symbol-indexed hashes.
45# Values are:
46# X Not deprecated
47# ? Deprecated in unknown version
48# x.yy.z Deprecated in version x.yy.z
49my %syminver; # Symbols-in-versions deprecations.
50my %hdr; # Public header files deprecations.
51my %funcman; # Function man pages deprecations.
52my %optman; # Option man pages deprecations.
54# Scan header file for public function and enum values. Flag them with
55# the version they are deprecated in, if some.
56sub scan_header {
57 my ($f) = @_;
58 my $line = "";
59 my $incomment = 0;
60 my $inenum = 0;
62 open(my $h, "<", $f);
63 while(<$h>) {
64 s/^\s*(.*?)\s*$/$1/; # Trim.
65 # Remove multi-line comment trail.
66 if($incomment) {
67 if($_ !~ /.*?\*\/\s*(.*)$/) {
68 next;
69 }
70 $_ = $1;
71 $incomment = 0;
72 }
73 if($line ne "") {
74 # Unfold line.
75 $_ = "$line $1";
76 $line = "";
77 }
78 # Remove comments.
79 while($_ =~ /^(.*?)\/\*.*?\*\/(.*)$/) {
80 $_ = "$1 $2";
81 }
82 if($_ =~ /^(.*)\/\*/) {
83 $_ = "$1 ";
84 $incomment = 1;
85 }
86 s/^\s*(.*?)\s*$/$1/; # Trim again.
87 # Ignore preprocessor directives and blank lines.
88 if($_ =~ /^(?:#|$)/) {
89 next;
90 }
91 # Handle lines that may be continued as if they were folded.
92 if($_ !~ /[;,{}]$/) {
93 # Folded line.
94 $line = $_;
95 next;
96 }
97 if($_ =~ /CURLOPTDEPRECATED\(/) {
98 # Handle deprecated CURLOPT_* option.
99 if($_ !~ /CURLOPTDEPRECATED\(\s*(\S+)\s*,(?:.*?,){2}\s*(.*?)\s*,.*"\)/) {
100 # Folded line.
101 $line = $_;
102 next;
103 }
104 $hdr{$1} = $2;
105 }
106 elsif($_ =~ /CURLOPT\(/) {
107 # Handle non-deprecated CURLOPT_* option.
108 if($_ !~ /CURLOPT\(\s*(\S+)\s*(?:,.*?){2}\)/) {
109 # Folded line.
110 $line = $_;
111 next;
112 }
113 $hdr{$1} = "X";
114 }
115 else {
116 my $version = "X";
118 # Get other kind of deprecation from this line.
119 if($_ =~ /CURL_DEPRECATED\(/) {
120 if($_ !~ /^(.*)CURL_DEPRECATED\(\s*(\S+?)\s*,.*?"\)(.*)$/) {
121 # Folded line.
122 $line = $_;
123 next;
124 }
125 $version = $2;
126 $_ = "$1 $3";
127 }
128 if($_ =~ /^CURL_EXTERN\s+.*\s+(\S+?)\s*\(/) {
129 # Flag public function.
130 $hdr{$1} = $version;
131 }
132 elsif($inenum && $_ =~ /(\w+)\s*[,=}]/) {
133 # Flag enum value.
134 $hdr{$1} = $version;
135 }
136 }
137 # Remember if we are in an enum definition.
138 $inenum |= ($_ =~ /\benum\b/);
139 if($_ =~ /}/) {
140 $inenum = 0;
141 }
142 }
143 close $h;
144}
146# Scan function man page for options.
147# Each option has to be declared as ".IP <option>" where <option> starts with
148# the prefix. Flag each option with its deprecation version, if some.
149sub scan_man_for_opts {
150 my ($f, $prefix) = @_;
151 my $opt = "";
152 my $line = "";
154 open(my $m, "<", $f);
155 while(<$m>) {
156 if($_ =~ /^\./) {
157 # roff directive found: end current option paragraph.
158 my $o = $opt;
159 $opt = "";
160 if($_ =~ /^\.IP\s+((?:$prefix)_\w+)/) {
161 # A new option has been found.
162 $opt = $1;
163 }
164 $_ = $line; # Get full paragraph.
165 $line = "";
166 s/\\f.//g; # Remove font formatting.
167 s/\s+/ /g; # One line with single space only.
168 if($o) {
169 $funcman{$o} = "X";
170 # Check if paragraph is mentioning deprecation.
171 while($_ =~ /(?:deprecated|obsoleted?)\b\s*(?:in\b|since\b)?\s*(?:version\b|curl\b|libcurl\b)?\s*(\d[0-9.]*\d)?\b\s*(.*)$/i) {
172 $funcman{$o} = $1 || "?";
173 $_ = $2;
174 }
175 }
176 }
177 else {
178 # Text line: accumulate.
179 $line .= $_;
180 }
181 }
182 close $m;
183}
185# Scan man page for deprecation in DESCRIPTION and/or AVAILABILITY sections.
186sub scan_man_page {
187 my ($path, $sym, $table) = @_;
188 my $version = "X";
190 if(open(my $fh, "<", $path)) {
191 my $section = "";
192 my $line = "";
194 while(<$fh>) {
195 if($_ =~ /\.so\s+man3\/(.*\.3\b)/) {
196 # Handle man page inclusion.
197 scan_man_page(dirname($path) . "/$1", $sym, $table);
198 $version = exists($$table{$sym})? $$table{$sym}: $version;
199 }
200 elsif($_ =~ /^\./) {
201 # Line is a roff directive.
202 if($_ =~ /^\.SH\b\s*(\w*)/) {
203 # Section starts. End previous one.
204 my $sh = $section;
206 $section = $1;
207 $_ = $line; # Previous section text.
208 $line = "";
209 s/\\f.//g;
210 s/\s+/ /g;
211 s/\\f.//g; # Remove font formatting.
212 s/\s+/ /g; # One line with single space only.
213 if($sh =~ /DESCRIPTION|DEPRECATED/) {
214 while($_ =~ /(?:deprecated|obsoleted?)\b\s*(?:in\b|since\b)?\s*(?:version\b|curl\b|libcurl\b)?\s*(\d[0-9.]*\d)?\b\s*(.*)$/i) {
215 # Flag deprecation status.
216 if($version ne "X" && $version ne "?") {
217 if($1 && $1 ne $version) {
218 print "error: $sym man page lists unmatching deprecation versions $version and $1\n";
219 $errcode++;
220 }
221 }
222 else {
223 $version = $1 || "?";
224 }
225 $_ = $2;
226 }
227 }
228 }
229 }
230 else {
231 # Text line: accumulate.
232 $line .= $_;
233 }
234 }
235 close $fh;
236 $$table{$sym} = $version;
237 }
238}
240# Read symbols-in-versions.
241open(my $fh, "<", "$root/docs/libcurl/symbols-in-versions") or
242 die "$root/docs/libcurl/symbols-in-versions";
243while(<$fh>) {
244 if($_ =~ /^((?:CURL|LIBCURL)\S+)\s+\S+\s*(\S*)\s*(\S*)$/) {
245 if($3 eq "") {
246 $syminver{$1} = "X";
247 if($2 ne "" && $2 ne ".") {
248 $syminver{$1} = $2;
249 }
250 }
251 }
252}
253close($fh);
255if(!glob("$libdocdir/*.3")) {
256 print "curl built without the libcurl manual. Skipping test 1222.\n";
257 exit 0;
258}
260# Get header filenames,
261opendir(my $dh, $incdir) or die "Cannot opendir $incdir";
262my @hfiles = grep { /\.h$/ } readdir($dh);
263closedir $dh;
265# Get functions and enum symbols from header files.
266for(@hfiles) {
267 scan_header("$incdir/$_");
268}
270# Get function statuses from man pages.
271foreach my $sym (keys %hdr) {
272 if($sym =~ /^(?:curl|curlx)_\w/) {
273 scan_man_page("$libdocdir/$sym.3", $sym, \%funcman);
274 }
275}
277# Get options from function man pages.
278scan_man_for_opts("$libdocdir/curl_easy_setopt.3", "CURLOPT");
279scan_man_for_opts("$libdocdir/curl_easy_getinfo.3", "CURLINFO");
281# Get deprecation status from option man pages.
282foreach my $sym (keys %syminver) {
283 if($sym =~ /^(?:CURLOPT|CURLINFO)_\w+$/) {
284 scan_man_page("$libdocdir/opts/$sym.3", $sym, \%optman);
285 }
286}
288# Print results.
289my %keys = (%syminver, %funcman, %optman, %hdr);
290my $leader = <<HEADER
291Legend:
292<empty> Not listed
293X Not deprecated
294? Deprecated in unknown version
295x.yy.z Deprecated in version x.yy.z
297Symbol symbols-in func man opt man .h
298 -versions
299HEADER
300 ;
301foreach my $sym (sort {$a cmp $b} keys %keys) {
302 if($sym =~ /^(?:CURLOPT|CURLINFO|curl|curlx)_\w/) {
303 my $s = exists($syminver{$sym})? $syminver{$sym}: " ";
304 my $f = exists($funcman{$sym})? $funcman{$sym}: " ";
305 my $o = exists($optman{$sym})? $optman{$sym}: " ";
306 my $h = exists($hdr{$sym})? $hdr{$sym}: " ";
307 my $r = " ";
309 # There are deprecated symbols in symbols-in-versions that are aliases
310 # and thus not listed anywhere else. Ignore them.
311 "$f$o$h" =~ /[X ]{3}/ && next;
313 # Check for inconsistencies between deprecations from the different sources.
314 foreach my $k ($s, $f, $o, $h) {
315 $r = $r eq " "? $k: $r;
316 if($k ne " " && $r ne $k) {
317 if($r eq "?") {
318 $r = $k ne "X"? $k: "!";
319 }
320 elsif($r eq "X" || $k ne "?") {
321 $r = "!";
322 }
323 }
324 }
326 if($r eq "!") {
327 print $leader;
328 $leader = "";
329 printf("%-38s %-11s %-9s %-9s %s\n", $sym, $s, $f, $o, $h);
330 $errcode++;
331 }
332 }
333}
335exit $errcode;
Diagnostics4 git calls · 25 ms
CallStatusSizeTime025 ms
discover200152 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=152 git.server.agent=gitty/1.0 git.server.object_format=sha1 git.server.caps=agent ls-refs fetch object-format git.server.fetch=shallow filter sideband-all git.protocol.version=2 git.pkt.frames=8 git.pkt.data=6 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=152 git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=149 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=149 git.pkt.payload.max=78 git.ls_refs.count=2 git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=20 git.response.bytes=293470 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=10 git.pkt.data=8 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=293470 git.pkt.payload.max=65516 git.sideband.band1.bytes=293354 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=87 git.pack.bytes=293354 git.pack.ofs_delta=0 git.pack.ref_delta=1 git.pack.chain.max=1 git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0 git.pack.full=86Open pack map
fetch2003.5 KiB · hit20 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=3586 git.response.cache=HIT git.response.duration_ms=20 git.fetch.wants=0d6a5ffc2cd6f2529e74b39bf61e5033d5861ef3 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=3586 git.pkt.payload.max=3565 git.sideband.band1.bytes=3564 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
- Ref
- refs/heads/master
- Commit
- 31c911efe5652725e930f4d2e60c9060e5f6646d
- cf-ray
- a5e2d4ed6da4689d
- Request
- 3a1ebb62…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format