Added a python script to rename SDL2 headers to SDL3 headers

build-scripts/rename_headers.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+#
+# This script renames SDL headers in the specfied paths
+
+import argparse
+import pathlib
+import re
+
+
+def main():
+    replacements = [
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?SDL_gamecontroller.h(?:[\">])"), r"<SDL3/SDL_gamepad.h>" ),
+        ( re.compile(r"(?:[\"<])(?:SDL2/)?(SDL[_a-z]*\.h)(?:[\">])"), r"<SDL3/\1>" )
+    ]
+    for entry in args.args:
+        path = pathlib.Path(entry)
+        if not path.exists():
+            print("%s doesn't exist, skipping" % entry)
+            continue
+
+        replace_headers_in_path(path, replacements)
+
+
+def replace_headers_in_file(file, replacements):
+    try:
+        with file.open("r", encoding="UTF-8", newline="") as rfp:
+            original = rfp.read()
+            contents = original
+            for regex, replacement in replacements:
+                contents = regex.sub(replacement, contents)
+            if contents != original:
+                with file.open("w", encoding="UTF-8", newline="") as wfp:
+                    wfp.write(contents)
+    except UnicodeDecodeError:
+        print("%s is not text, skipping" % file)
+    except Exception as err:
+        print("%s" % err)
+
+
+def replace_headers_in_dir(path, replacements):
+    for entry in path.glob("*"):
+        if entry.is_dir():
+            replace_headers_in_dir(entry, replacements)
+        else:
+            print("Processing %s" % entry)
+            replace_headers_in_file(entry, replacements)
+
+
+def replace_headers_in_path(path, replacements):
+        if path.is_dir():
+            replace_headers_in_dir(path, replacements)
+        else:
+            replace_headers_in_file(path, replacements)
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
+    parser.add_argument("args", nargs="*")
+    args = parser.parse_args()
+
+    try:
+        main()
+    except Exception as e:
+        print(e)
+        exit(-1)
+
+    exit(0)
+

docs/README-migration.md

@@ -9,7 +9,10 @@ Many functions and symbols have been renamed. We have provided a handy Python sc
 rename_symbols.py --all-symbols source_code_path
 ```
 
-SDL headers should now be included as `#include <SDL3/SDL.h>`. Typically that's the only header you'll need in your application unless you are using OpenGL or Vulkan functionality.
+SDL headers should now be included as `#include <SDL3/SDL.h>`. Typically that's the only header you'll need in your application unless you are using OpenGL or Vulkan functionality. We have provided a handy Python script [rename_headers.py](https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_headers.py) to rename SDL2 headers to their SDL3 counterparts:
+```sh
+rename_headers.py source_code_path
+```
 
 The file with your main() function should also include <SDL3/SDL_main.h>, see below in the SDL_main.h section.