mirror of https://github.com/libsdl-org/SDL
Added infrastructure for renaming API functions
You can rename APIs using rename.py and all the code and documentation will be updated, and entries will be added to WhatsNew.txt and docs/README-migration.md. e.g. rename.py SDL_foo.h function SDL_CreateFoo SDL_FooCreate SDL_oldnames.h is included in the SDL header, and if you define SDL_ENABLE_OLD_NAMES, will redefine the old API functions to call the new ones, and if not, will define them as a symbol letting you what the new API function is.
This commit is contained in:
Sam Lantinga
parent
08c45eb37e
commit
b5a92406eb
|
|
@ -0,0 +1,234 @@
|
|||
#!/usr/bin/env python3
|
||||
|
||||
# WHAT IS THIS?
|
||||
# This script renames symbols in the API, updating SDL_oldnames.h and
|
||||
# adding documentation for the change.
|
||||
|
||||
import argparse
|
||||
import os
|
||||
import pathlib
|
||||
import pprint
|
||||
import re
|
||||
|
||||
|
||||
SDL_ROOT = pathlib.Path(__file__).resolve().parents[1]
|
||||
|
||||
SDL_INCLUDE_DIR = SDL_ROOT / "include/SDL3"
|
||||
|
||||
|
||||
def main():
|
||||
# Check whether we can still modify the ABI
|
||||
version_header = pathlib.Path( SDL_INCLUDE_DIR / "SDL_version.h" ).read_text()
|
||||
if not re.search("SDL_MINOR_VERSION\s+[01]\s", version_header):
|
||||
raise Exception("ABI is frozen, symbols cannot be renamed")
|
||||
|
||||
pattern = re.compile(r"\b%s\b" % args.oldname)
|
||||
|
||||
# Find the symbol in the headers
|
||||
if pathlib.Path(args.header).is_file():
|
||||
header = pathlib.Path(args.header)
|
||||
else:
|
||||
header = pathlib.Path(SDL_INCLUDE_DIR / args.header)
|
||||
|
||||
if not header.exists():
|
||||
raise Exception("Couldn't find header %s" % header)
|
||||
|
||||
if not pattern.search(header.read_text()):
|
||||
raise Exception("Couldn't find %s in %s" % (args.oldname, header))
|
||||
|
||||
# Replace the symbol in source code and documentation
|
||||
for dir in ['src', 'test', 'include', 'docs']:
|
||||
replace_symbol_recursive(SDL_ROOT / dir, pattern, args.newname)
|
||||
|
||||
add_symbol_to_oldnames(header.name, args.oldname, args.newname)
|
||||
add_symbol_to_migration(header.name, args.type, args.oldname, args.newname)
|
||||
add_symbol_to_whatsnew(args.type, args.oldname, args.newname)
|
||||
|
||||
|
||||
def replace_symbol_recursive(path, pattern, replacement):
|
||||
for entry in path.glob("*"):
|
||||
if entry.is_dir():
|
||||
replace_symbol_recursive(entry, pattern, replacement)
|
||||
elif not entry.name.endswith((".bmp", ".cur", ".dat", ".icns", ".png", ".strings", ".swp", ".wav")) and \
|
||||
entry.name != "utf8.txt":
|
||||
print("Processing %s" % entry)
|
||||
with entry.open('r', encoding='UTF-8', newline='') as rfp:
|
||||
contents = pattern.sub(replacement, rfp.read())
|
||||
with entry.open('w', encoding='UTF-8', newline='') as wfp:
|
||||
wfp.write(contents)
|
||||
|
||||
|
||||
def add_line(lines, i, section):
|
||||
lines.insert(i, section)
|
||||
i += 1
|
||||
return i
|
||||
|
||||
|
||||
def add_content(lines, i, content, add_trailing_line):
|
||||
if lines[i - 1] == "":
|
||||
lines[i - 1] = content
|
||||
else:
|
||||
i = add_line(lines, i, content)
|
||||
|
||||
if add_trailing_line:
|
||||
i = add_line(lines, i, "")
|
||||
return i
|
||||
|
||||
|
||||
def add_symbol_to_oldnames(header, oldname, newname):
|
||||
file = (SDL_INCLUDE_DIR / "SDL_oldnames.h")
|
||||
lines = file.read_text().splitlines()
|
||||
mode = 0
|
||||
i = 0
|
||||
while i < len(lines):
|
||||
line = lines[i]
|
||||
if line == "#ifdef SDL_ENABLE_OLD_NAMES":
|
||||
if mode == 0:
|
||||
mode = 1
|
||||
section = ("/* ##%s */" % header)
|
||||
section_added = False
|
||||
content = ("#define %s %s" % (oldname, newname))
|
||||
content_added = False
|
||||
else:
|
||||
raise Exception("add_symbol_to_oldnames(): expected mode 0")
|
||||
elif line == "#else /* !SDL_ENABLE_OLD_NAMES */":
|
||||
if mode == 1:
|
||||
if not section_added:
|
||||
i = add_line(lines, i, section)
|
||||
|
||||
if not content_added:
|
||||
i = add_content(lines, i, content, True)
|
||||
|
||||
mode = 2
|
||||
section = ("/* ##%s */" % header)
|
||||
section_added = False
|
||||
content = ("#define %s %s_renamed_%s" % (oldname, oldname, newname))
|
||||
content_added = False
|
||||
else:
|
||||
raise Exception("add_symbol_to_oldnames(): expected mode 1")
|
||||
elif line == "#endif /* SDL_ENABLE_OLD_NAMES */":
|
||||
if mode == 2:
|
||||
if not section_added:
|
||||
i = add_line(lines, i, section)
|
||||
|
||||
if not content_added:
|
||||
i = add_content(lines, i, content, True)
|
||||
|
||||
mode = 3
|
||||
else:
|
||||
raise Exception("add_symbol_to_oldnames(): expected mode 2")
|
||||
elif line != "" and (mode == 1 or mode == 2):
|
||||
if line.startswith("/* ##"):
|
||||
if section_added:
|
||||
if not content_added:
|
||||
i = add_content(lines, i, content, True)
|
||||
content_added = True
|
||||
elif line == section:
|
||||
section_added = True
|
||||
elif section < line:
|
||||
i = add_line(lines, i, section)
|
||||
section_added = True
|
||||
i = add_content(lines, i, content, True)
|
||||
content_added = True
|
||||
elif line != "" and section_added and not content_added:
|
||||
if content == line:
|
||||
content_added = True
|
||||
elif content < line:
|
||||
i = add_content(lines, i, content, False)
|
||||
content_added = True
|
||||
i += 1
|
||||
|
||||
file.write_text("\n".join(lines) + "\n")
|
||||
|
||||
|
||||
def add_symbol_to_migration(header, symbol_type, oldname, newname):
|
||||
file = (SDL_ROOT / "docs/README-migration.md")
|
||||
lines = file.read_text().splitlines()
|
||||
section = ("## %s" % header)
|
||||
section_added = False
|
||||
note = ("The following %ss have been renamed:" % symbol_type)
|
||||
note_added = False
|
||||
content = ("* %s -> %s" % (oldname, newname))
|
||||
content_added = False
|
||||
mode = 0
|
||||
i = 0
|
||||
while i < len(lines):
|
||||
line = lines[i]
|
||||
if line.startswith("##") and line.endswith(".h"):
|
||||
if line == section:
|
||||
section_added = True
|
||||
elif section < line:
|
||||
break
|
||||
|
||||
elif section_added and not note_added:
|
||||
if note == line:
|
||||
note_added = True
|
||||
elif note_added and not content_added:
|
||||
if content == line:
|
||||
content_added = True
|
||||
elif line == "" or content < line:
|
||||
i = add_line(lines, i, content)
|
||||
content_added = True
|
||||
i += 1
|
||||
|
||||
if not section_added:
|
||||
i = add_line(lines, i, section)
|
||||
i = add_line(lines, i, "")
|
||||
|
||||
if not note_added:
|
||||
i = add_line(lines, i, note)
|
||||
|
||||
if not content_added:
|
||||
i = add_content(lines, i, content, True)
|
||||
|
||||
file.write_text("\n".join(lines) + "\n")
|
||||
|
||||
|
||||
def add_symbol_to_whatsnew(symbol_type, oldname, newname):
|
||||
file = (SDL_ROOT / "WhatsNew.txt")
|
||||
lines = file.read_text().splitlines()
|
||||
note = ("* The following %ss have been renamed:" % symbol_type)
|
||||
note_added = False
|
||||
content = (" * %s -> %s" % (oldname, newname))
|
||||
content_added = False
|
||||
mode = 0
|
||||
i = 0
|
||||
while i < len(lines):
|
||||
line = lines[i]
|
||||
if not note_added:
|
||||
if note == line:
|
||||
note_added = True
|
||||
elif not content_added:
|
||||
if content == line:
|
||||
content_added = True
|
||||
elif not line.startswith(" *") or content < line:
|
||||
i = add_line(lines, i, content)
|
||||
content_added = True
|
||||
i += 1
|
||||
|
||||
if not note_added:
|
||||
i = add_line(lines, i, note)
|
||||
|
||||
if not content_added:
|
||||
i = add_line(lines, i, content)
|
||||
|
||||
file.write_text("\r\n".join(lines) + "\r\n")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument('header');
|
||||
parser.add_argument('type', choices=['function', 'enum']);
|
||||
parser.add_argument('oldname');
|
||||
parser.add_argument('newname');
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
main()
|
||||
except Exception as e:
|
||||
print(e)
|
||||
exit(-1)
|
||||
|
||||
exit(0)
|
||||
|
||||
|
|
@ -46,6 +46,7 @@
|
|||
#include <SDL3/SDL_haptic.h>
|
||||
#include <SDL3/SDL_hidapi.h>
|
||||
#include <SDL3/SDL_hints.h>
|
||||
#include <SDL3/SDL_init.h>
|
||||
#include <SDL3/SDL_joystick.h>
|
||||
#include <SDL3/SDL_keyboard.h>
|
||||
#include <SDL3/SDL_keycode.h>
|
||||
|
|
@ -75,7 +76,7 @@
|
|||
#include <SDL3/SDL_touch.h>
|
||||
#include <SDL3/SDL_version.h>
|
||||
#include <SDL3/SDL_video.h>
|
||||
#include <SDL3/SDL_init.h>
|
||||
#include <SDL3/SDL_oldnames.h>
|
||||
|
||||
#endif /* SDL_h_ */
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
/*
|
||||
Simple DirectMedia Layer
|
||||
Copyright (C) 1997-2022 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
|
||||
arising from the use of this software.
|
||||
|
||||
Permission is granted to anyone to use this software for any purpose,
|
||||
including commercial applications, and to alter it and redistribute it
|
||||
freely, subject to the following restrictions:
|
||||
|
||||
1. The origin of this software must not be misrepresented; you must not
|
||||
claim that you wrote the original software. If you use this software
|
||||
in a product, an acknowledgment in the product documentation would be
|
||||
appreciated but is not required.
|
||||
2. Altered source versions must be plainly marked as such, and must not be
|
||||
misrepresented as being the original software.
|
||||
3. This notice may not be removed or altered from any source distribution.
|
||||
*/
|
||||
|
||||
/**
|
||||
* \file SDL_oldnames.h
|
||||
*
|
||||
* Definitions to ease transition from SDL2 code
|
||||
*/
|
||||
|
||||
#ifndef SDL_oldnames_h_
|
||||
#define SDL_oldnames_h_
|
||||
|
||||
/* The new function names are recommended, but if you want to have the
|
||||
* old names available while you are in the process of migrating code
|
||||
* to SDL3, you can define `SDL_ENABLE_OLD_NAMES` in your project.
|
||||
*/
|
||||
#ifdef SDL_ENABLE_OLD_NAMES
|
||||
|
||||
#else /* !SDL_ENABLE_OLD_NAMES */
|
||||
|
||||
#endif /* SDL_ENABLE_OLD_NAMES */
|
||||
|
||||
#endif /* SDL_oldnames_h_ */
|
||||
|
||||
/* vi: set ts=4 sw=4 expandtab: */
|
||||
Loading…
Reference in New Issue