Ammerhai/Mikemon
2
0
Fork 0
Code Issues 8 Pull Requests Packages Projects 2 Releases 1 Wiki Activity

update SDL3 from 3.2.20 to 3.4.2

Browse Source
This commit is contained in:
Sven Balzer
2026-04-01 18:25:03 +02:00
parent 1daf4d79f1
commit 05b19704f8
1626 changed files with 124218 additions and 191491 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libs/SDL3/build-scripts/wikiheaders.pl
+131 -57
View File
@@ -1,7 +1,7 @@
#!/usr/bin/perl -w
# Simple DirectMedia Layer
# Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
# Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
#
# This software is provided 'as-is', without any express or implied
# warranty. In no event will the authors be held liable for any damages
@@ -32,10 +32,16 @@ my $wikisubdir = '';
my $incsubdir = 'include';
my $readmesubdir = undef;
my $apiprefixregex = undef;
my $apipropertyregex = undef;
my $versionfname = 'include/SDL_version.h';
my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z';
my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z';
my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z';
my $wikidocsectionsym = 'SDL_WIKI_DOCUMENTATION_SECTION';
my $forceinlinesym = 'SDL_FORCE_INLINE';
my $deprecatedsym = 'SDL_DEPRECATED';
my $declspecsym = '(?:SDLMAIN_|SDL_)?DECLSPEC';
my $callconvsym = 'SDLCALL';
my $mainincludefname = 'SDL.h';
my $selectheaderregex = '\ASDL.*?\.h\Z';
my $projecturl = 'https://libsdl.org/';
@@ -43,7 +49,6 @@ my $wikiurl = 'https://wiki.libsdl.org';
my $bugreporturl = 'https://github.com/libsdl-org/sdlwiki/issues/new';
my $srcpath = undef;
my $wikipath = undef;
my $wikireadmesubdir = 'README';
my $warn_about_missing = 0;
my $copy_direction = 0;
my $optionsfname = undef;
@@ -58,6 +63,11 @@ my $quickreftitle = undef;
my $quickrefurl = undef;
my $quickrefdesc = undef;
my $quickrefmacroregex = undef;
my $envvarenabled = 0;
my $envvartitle = 'Environment Variables';
my $envvardesc = undef;
my $envvarsymregex = undef;
my $envvarsymreplace = undef;
my $changeformat = undef;
my $manpath = undef;
my $gitrev = undef;
@@ -111,6 +121,7 @@ if (defined $optionsfname) {
$srcpath = $val, next if $key eq 'srcpath';
$wikipath = $val, next if $key eq 'wikipath';
$apiprefixregex = $val, next if $key eq 'apiprefixregex';
$apipropertyregex = $val, next if $key eq 'apipropertyregex';
$projectfullname = $val, next if $key eq 'projectfullname';
$projectshortname = $val, next if $key eq 'projectshortname';
$wikisubdir = $val, next if $key eq 'wikisubdir';
@@ -136,6 +147,17 @@ if (defined $optionsfname) {
$quickrefurl = $val, next if $key eq 'quickrefurl';
$quickrefdesc = $val, next if $key eq 'quickrefdesc';
$quickrefmacroregex = $val, next if $key eq 'quickrefmacroregex';
$envvarenabled = int($val), next if $key eq 'envvarenabled';
$envvartitle = $val, next if $key eq 'envvartitle';
$envvardesc = $val, next if $key eq 'envvardesc';
$envvarsymregex = $val, next if $key eq 'envvarsymregex';
$envvarsymreplace = $val, next if $key eq 'envvarsymreplace';
$wikidocsectionsym = $val, next if $key eq 'wikidocsectionsym';
$forceinlinesym = $val, next if $key eq 'forceinlinesym';
$deprecatedsym = $val, next if $key eq 'deprecatedsym';
$declspecsym = $val, next if $key eq 'declspecsym';
$callconvsym = $val, next if $key eq 'callconvsym';
}
}
close(OPTIONS);
@@ -342,7 +364,7 @@ sub wikify_chunk {
# Convert obvious API things to wikilinks.
if (defined $apiprefixregex) {
$str =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[$2\]\($2\)/gms;
$str =~ s/(\A|[^\/a-zA-Z0-9_\[])($apiprefixregex[a-zA-Z0-9_]+)/$1\[$2\]\($2\)/gms;
}
$str = $codedstr . $str;
@@ -425,6 +447,7 @@ sub dewikify_chunk {
}
} elsif ($dewikify_mode eq 'manpage') {
# make sure these can't become part of roff syntax.
$str =~ s/\\/\\(rs/gms;
$str =~ s/\./\\[char46]/gms;
$str =~ s/"/\\(dq/gms;
$str =~ s/'/\\(aq/gms;
@@ -738,6 +761,7 @@ sub print_undocumented_section {
}
}
# !!! FIXME: generalize this for other libraries to use.
sub strip_fn_declaration_metadata {
my $decl = shift;
$decl =~ s/SDL_(PRINTF|SCANF)_FORMAT_STRING\s*//; # don't want this metadata as part of the documentation.
@@ -826,21 +850,23 @@ sub print_big_ascii_string {
die("Don't have a big ascii entry for '$ch'!\n") if not defined $rowsref;
my $row = @$rowsref[$rownum];
my $outstr = '';
if ($lowascii) {
my @x = split //, $row;
foreach (@x) {
my $v = ($_ eq "\x{2588}") ? 'X' : ' ';
print $fh $v;
$outstr .= ($_ eq "\x{2588}") ? 'X' : ' ';
}
} else {
print $fh $row;
$outstr = $row;
}
$charidx++;
if ($charidx < $charcount) {
print $fh " ";
if ($charidx == $charcount) {
$outstr =~ s/\s*\Z//; # dump extra spaces at the end of the line.
} else {
$outstr .= ' '; # space between glyphs.
}
print $fh $outstr;
}
print $fh "\n";
}
@@ -1031,10 +1057,58 @@ sub generate_quickref {
}
sub generate_envvar_wiki_page {
my $briefsref = shift;
my $path = shift;
return if not $envvarenabled or not defined $envvarsymregex or not defined $envvarsymreplace;
my $replace = "\"$envvarsymreplace\"";
my $tmppath = "$path.tmp";
open(my $fh, '>', $tmppath) or die("Can't open '$tmppath': $!\n");
print $fh "<!-- DO NOT EDIT THIS PAGE ON THE WIKI. IT WILL BE OVERWRITTEN BY WIKIHEADERS AND CHANGES WILL BE LOST! -->\n\n";
print $fh "# $envvartitle\n\n";
if (defined $envvardesc) {
my $desc = "$envvardesc";
$desc =~ s/\\n/\n/g; # replace "\n" strings with actual newlines.
print $fh "$desc\n\n";
}
print $fh "## Environment Variable List\n\n";
foreach (sort keys %headersyms) {
my $sym = $_;
next if $headersymstype{$sym} != 2; # not a #define? skip it.
my $hint = "$_";
next if not $hint =~ s/$envvarsymregex/$replace/ee;
my $brief = $$briefsref{$sym};
if (not defined $brief) {
$brief = '';
} else {
$brief = "$brief";
chomp($brief);
my $thiswikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff.
$brief = ": " . dewikify($thiswikitype, $brief);
}
print $fh "- [$hint]($sym)$brief\n";
}
print $fh "\n";
close($fh);
rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n");
}
my $incpath = "$srcpath";
$incpath .= "/$incsubdir" if $incsubdir ne '';
my $wikireadmepath = "$wikipath/$wikireadmesubdir";
my $readmepath = undef;
if (defined $readmesubdir) {
$readmepath = "$srcpath/$readmesubdir";
@@ -1091,7 +1165,7 @@ while (my $d = readdir(DH)) {
} elsif ($ignoring_lines) {
push @contents, $_;
next;
} elsif (/\A\s*\#\s*ifndef\s+SDL_WIKI_DOCUMENTATION_SECTION\s*\Z/) {
} elsif (/\A\s*\#\s*ifndef\s+$wikidocsectionsym\s*\Z/) {
$ignoring_lines = 1;
push @contents, $_;
next;
@@ -1100,13 +1174,13 @@ while (my $d = readdir(DH)) {
#print("CATEGORY FOR '$dent' CHANGED TO " . (defined($current_wiki_category) ? "'$current_wiki_category'" : '(undef)') . "\n");
push @contents, $_;
next;
} elsif (/\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) { # a function declaration without a doxygen comment?
} elsif (/\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym/) { # a function declaration without a doxygen comment?
$symtype = 1; # function declaration
@templines = ();
$decl = $_;
$str = '';
$has_doxygen = 0;
} elsif (/\A\s*SDL_FORCE_INLINE/) { # a (forced-inline) function declaration without a doxygen comment?
} elsif (/\A\s*$forceinlinesym/) { # a (forced-inline) function declaration without a doxygen comment?
$symtype = 1; # function declaration
@templines = ();
$decl = $_;
@@ -1173,9 +1247,9 @@ while (my $d = readdir(DH)) {
$lineno++ if defined $decl;
$decl = '' if not defined $decl;
chomp($decl);
if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) {
if ($decl =~ /\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym/) {
$symtype = 1; # function declaration
} elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) {
} elsif ($decl =~ /\A\s*$forceinlinesym/) {
$symtype = 1; # (forced-inline) function declaration
} elsif ($decl =~ /\A\s*\#\s*define\s+/) {
$symtype = 2; # macro
@@ -1212,7 +1286,7 @@ while (my $d = readdir(DH)) {
}
$headercategorydocs{$current_wiki_category} = $sym;
} elsif ($symtype == 1) { # a function
my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/);
my $is_forced_inline = ($decl =~ /\A\s*$forceinlinesym/);
if ($is_forced_inline) {
if (not $decl =~ /\)\s*(\{.*|)\s*\Z/) {
@@ -1249,14 +1323,14 @@ while (my $d = readdir(DH)) {
my $paramsstr = undef;
if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) {
$sym = $8;
$rettype = "$3$4$5$6";
$paramsstr = $9;
} elsif ($is_forced_inline && $decl =~ /\A\s*SDL_FORCE_INLINE\s+(SDL_DEPRECATED\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) {
if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*$callconvsym\s+(.*?)\s*\((.*?)\);/) {
$sym = $6;
$rettype = "$2$3$4$5";
$rettype = "$1$2$3$4$5";
$paramsstr = $7;
} elsif ($is_forced_inline && $decl =~ /\A\s*$forceinlinesym\s+(?:$deprecatedsym\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) {
$sym = $5;
$rettype = "$1$2$3$4";
$paramsstr = $6;
} else {
#print "Found doxygen but no function sig:\n$str\n\n";
foreach (@templines) {
@@ -1322,7 +1396,7 @@ while (my $d = readdir(DH)) {
$decl = $_;
$temp = $decl;
$temp =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /;
$temp =~ s/\Aextern\s+(?:$deprecatedsym\s+|)$declspecsym\w*\s+(.*?)\s+(\*?)$callconvsym\s+/$1$2 /;
$shrink_length = length($decl) - length($temp);
$decl = $temp;
} else {
@@ -1366,7 +1440,7 @@ while (my $d = readdir(DH)) {
# update strings now that we know everything pending is to be applied to this declaration. Add pending blank lines and the new text.
# At Sam's request, don't list property defines with functions. (See #9440)
my $is_property = /\A\s*\#\s*define\s+SDL_PROP_/;
my $is_property = (defined $apipropertyregex) ? /$apipropertyregex/ : 0;
if (!$is_property) {
if ($blank_lines > 0) {
while ($blank_lines > 0) {
@@ -1387,7 +1461,7 @@ while (my $d = readdir(DH)) {
}
$decl .= $additional_decl;
} elsif ($symtype == 2) { # a macro
if ($decl =~ /\A\s*\#\s*define\s+(.*?)(\(.*?\)|)\s+/) {
if ($decl =~ /\A\s*\#\s*define\s+(.*?)(\(.*?\)|)(\s+|\Z)/) {
$sym = $1;
} else {
#print "Found doxygen but no macro:\n$str\n\n";
@@ -2083,18 +2157,15 @@ if ($copy_direction == 1) { # --copy-to-headers
}
if (defined $readmepath) {
if ( -d $wikireadmepath ) {
mkdir($readmepath); # just in case
opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n");
while (readdir(DH)) {
my $dent = $_;
if ($dent =~ /\A(.*?)\.md\Z/) { # we only bridge Markdown files here.
next if $1 eq 'FrontPage';
filecopy("$wikireadmepath/$dent", "$readmepath/README-$dent", "\n");
}
mkdir($readmepath); # just in case
opendir(DH, $wikipath) or die("Can't opendir '$wikipath': $!\n");
while (readdir(DH)) {
my $dent = $_;
if ($dent =~ /\A(README|INTRO)\-.*?\.md\Z/) { # we only bridge Markdown files here that start with "README-" or "INTRO-".
filecopy("$wikipath/$dent", "$readmepath/$dent", "\n");
}
closedir(DH);
}
closedir(DH);
}
} elsif ($copy_direction == -1) { # --copy-to-wiki
@@ -2200,10 +2271,10 @@ if ($copy_direction == 1) { # --copy-to-headers
$desc =~ s/[\s\n]+\Z//ms;
if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a capital letter: '$desc'. Fixing.\n";
$desc = lcfirst($desc);
if (0) {
if (($desc =~ /\A[a-z]/) && (not $desc =~ /$apiprefixregex/)) {
print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a lowercase letter: '$desc'. Fixing.\n";
$desc = ucfirst($desc);
}
}
@@ -2247,8 +2318,8 @@ if ($copy_direction == 1) { # --copy-to-headers
}
$desc =~ s/[\s\n]+\Z//ms;
if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
if (0) {
if (($desc =~ /\A[A-Z]/) && (not $desc =~ /$apiprefixregex/)) {
print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n";
$desc = lcfirst($desc);
}
@@ -2392,7 +2463,7 @@ if ($copy_direction == 1) { # --copy-to-headers
} else {
die("Unexpected symbol type $symtype!");
}
my $str = "This $symtypename is available since SDL 3.0.0.";
my $str = "This $symtypename is available since $projectshortname 3.0.0.";
$sections{'Version'} = wordwrap(wikify($wikitype, $str)) . "\n";
}
}
@@ -2699,31 +2770,27 @@ __EOF__
# Write out READMEs...
if (defined $readmepath) {
if ( -d $readmepath ) {
mkdir($wikireadmepath); # just in case
mkdir($wikipath); # just in case
opendir(DH, $readmepath) or die("Can't opendir '$readmepath': $!\n");
while (my $d = readdir(DH)) {
my $dent = $d;
if ($dent =~ /\AREADME\-(.*?\.md)\Z/) { # we only bridge Markdown files here.
my $wikifname = $1;
next if $wikifname eq 'FrontPage.md';
filecopy("$readmepath/$dent", "$wikireadmepath/$wikifname", "\n");
if ($dent =~ /\A(README|INTRO)\-.*?\.md\Z/) { # we only bridge Markdown files here that start with "README-" or "INTRO".
filecopy("$readmepath/$dent", "$wikipath/$dent", "\n");
}
}
closedir(DH);
my @pages = ();
opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n");
opendir(DH, $wikipath) or die("Can't opendir '$wikipath': $!\n");
while (my $d = readdir(DH)) {
my $dent = $d;
if ($dent =~ /\A(.*?)\.(mediawiki|md)\Z/) {
my $wikiname = $1;
next if $wikiname eq 'FrontPage';
push @pages, $wikiname;
if ($dent =~ /\A((README|INTRO)\-.*?)\.md\Z/) {
push @pages, $1;
}
}
closedir(DH);
open(FH, '>', "$wikireadmepath/FrontPage.md") or die("Can't open '$wikireadmepath/FrontPage.md': $!\n");
open(FH, '>', "$wikipath/READMEs.md") or die("Can't open '$wikipath/READMEs.md': $!\n");
print FH "# All READMEs available here\n\n";
foreach (sort @pages) {
my $wikiname = $_;
@@ -2738,6 +2805,11 @@ __EOF__
generate_quickref(\%briefs, "$wikipath/QuickReference.md", 0);
generate_quickref(\%briefs, "$wikipath/QuickReferenceNoUnicode.md", 1);
}
if ($envvarenabled and defined $envvarsymregex and defined $envvarsymreplace) {
generate_envvar_wiki_page(\%briefs, "$wikipath/EnvironmentVariables.md");
}
} elsif ($copy_direction == -2) { # --copy-to-manpages
# This only takes from the wiki data, since it has sections we omit from the headers, like code examples.
@@ -2856,7 +2928,7 @@ __EOF__
$str .= ".\\\" Please report issues in this manpage's content at:\n";
$str .= ".\\\" $bugreporturl\n";
$str .= ".\\\" Please report issues in the generation of this manpage from the wiki at:\n";
$str .= ".\\\" https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20$sym\n";
$str .= ".\\\" https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20$sym\n"; # !!! FIXME: if this becomes a problem for other projects, we'll generalize this.
$str .= ".\\\" $projectshortname can be found at $projecturl\n";
# Define a .URL macro. The "www.tmac" thing decides if we're using GNU roff (which has a .URL macro already), and if so, overrides the macro we just created.
@@ -2981,10 +3053,12 @@ __EOF__
}
if (defined $returns) {
# Check for md link in return type: ([SDL_Renderer](SDL_Renderer) *)
# This would've prevented the next regex from working properly (it'd leave " *)")
$returns =~ s/\A\(\[.*?\]\((.*?)\)/\($1/ms;
# Chop datatype in parentheses off the front.
if(!($returns =~ s/\A\([^\[]*\[[^\]]*\]\([^\)]*\)[^\)]*\) //ms)) {
$returns =~ s/\A\([^\)]*\) //ms;
}
$returns =~ s/\A\(.*?\) //;
$returns = dewikify($wikitype, $returns);
$str .= ".SH RETURN VALUE\n";
$str .= "$returns\n";