Document the new SDL3 Android archive artifact

build-scripts/build-release.py

@@ -609,6 +609,10 @@ class Releaser:
         aar_path =  self.dist_path / f"{self.project}-{self.version}.aar"
         added_global_files = False
         with zipfile.ZipFile(aar_path, "w", compression=zipfile.ZIP_DEFLATED) as zip_object:
+            install_txt = (self.root / "build-scripts/pkg-support/android/INSTALL.md.in").read_text()
+            install_txt = install_txt.replace("@PROJECT_VERSION@", self.version)
+            install_txt = install_txt.replace("@PROJECT_NAME@", self.project)
+            zip_object.writestr("INSTALL.md", install_txt)
             project_description = {
                 "name": self.project,
                 "version": self.version,

build-scripts/create-android-project.py

@@ -114,7 +114,11 @@ def gradle_add_package_name(path: Path, package_name: str) -> None:
 
 def main() -> int:
     description = "Create a simple Android gradle project from input sources."
-    epilog = "You need to manually copy a prebuilt SDL3 Android archive into the project tree when using the aar variant."
+    epilog = textwrap.dedent("""\
+        You need to manually copy a prebuilt SDL3 Android archive into the project tree when using the aar variant.
+        
+        Any changes you have done to the sources in the Android project will be lost
+    """)
     parser = ArgumentParser(description=description, epilog=epilog, allow_abbrev=False)
     parser.add_argument("package_name", metavar="PACKAGENAME", help="Android package name (e.g. com.yourcompany.yourapp)")
     parser.add_argument("sources", metavar="SOURCE", nargs="*", help="Source code of your application. The files are copied to the output directory.")

build-scripts/pkg-support/android/INSTALL.md.in

@@ -0,0 +1,58 @@
+
+This Android archive allows use of @PROJECT_NAME@ in your Android project, without needing to copy any SDL source.
+For integration with CMake/ndk-build, it uses [prefab](https://google.github.io/prefab/).
+
+Copy this archive (@PROJECT_NAME@-@PROJECT_VERSION@.aar) to a `app/libs` directory of your project.
+
+In `app/gradle.build` of your Android project, add:
+```
+android {
+    /* ... */
+    buildFeatures {
+        prefab true
+    }
+}
+dependencies {
+    implementation files('libs/@PROJECT_NAME@-@PROJECT_VERSION@.aar')
+    /* ... */
+}
+```
+
+If you're using CMake, add the following to your CMakeLists.txt:
+```
+find_package(@PROJECT_NAME@ REQUIRED CONFIG)
+target_link_libraries(yourgame PRIVATE @PROJECT_NAME@::@PROJECT_NAME@)
+```
+
+If you're using ndk-build, add the following somewhere after `LOCAL_MODULE := yourgame` to your `Android.mk` or `Application.mk`:
+```
+# https://google.github.io/prefab/build-systems.html
+
+# Add the prefab modules to the import path.
+$(call import-add-path,/out)
+
+# Import @PROJECT_NAME@ so we can depend on it.
+$(call import-module,prefab/@PROJECT_NAME@)
+```
+
+---
+
+For advanced users:
+
+If you want to build a 3rd party library outside Gradle,
+running the following command will extract the Android archive into a more common directory structure.
+```
+python @PROJECT_NAME@-@PROJECT_VERSION@.aar -o android_prefix
+```
+Add `--help` for a list of all available options.
+
+
+Look at the example programs in ./test (of the source archive), and check out online documentation:
+    https://wiki.libsdl.org/SDL3/FrontPage
+
+Join the SDL discourse server if you want to join the community:
+    https://discourse.libsdl.org/
+
+
+That's it!
+Sam Lantinga <slouken@libsdl.org>