Updating documentation for the 3.2.0 release

* Simplified and updated the mingw release archive * Simplified and updated the msvc release archive * Updated the Xcode release archive * Updated the Android release archive
2025-10-26 12:27:44 +00:00 · 2025-01-15 20:38:16 -08:00
parent 2c7b7d1d33
commit 5f4696ce63
18 changed files with 249 additions and 158 deletions
--- a/build-scripts/build-release.py
+++ b/build-scripts/build-release.py
@@ -891,6 +891,8 @@ class Releaser:
        platform_versions = []
        for platform_dir in platform_dirs:
            logger.debug("Found Android Platform SDK: %s", platform_dir)
+            if not (platform_dir / "android.jar").is_file():
+                continue
            if m:= re_platform.match(platform_dir.name):
                platform_versions.append(int(m.group(1)))
        platform_versions.sort()
@@ -1248,6 +1250,10 @@ class Releaser:
        platform_context = self.get_context(extra_context=arch_platform.extra_context())

        build_type = "Release"
+        extra_context = {
+            "ARCH": arch_platform.arch,
+            "PLATFORM": arch_platform.platform,
+        }

        built_paths = set(install_path / configure_text(f, context=platform_context) for file_mapping in (self.release_info["msvc"]["cmake"]["files-lib"], self.release_info["msvc"]["cmake"]["files-devel"]) for files_list in file_mapping.values() for f in files_list)
        logger.info("CMake builds these files, to be included in the package: %s", built_paths)
@@ -1298,7 +1304,7 @@ class Releaser:
        logger.info("Collecting files...")
        archive_file_tree = ArchiveFileTree()
        archive_file_tree.add_file_mapping(arc_dir="", file_mapping=self.release_info["msvc"]["cmake"]["files-lib"], file_mapping_root=install_path, context=platform_context, time=self.arc_time)
-        archive_file_tree.add_file_mapping(arc_dir="", file_mapping=self.release_info["msvc"]["files-lib"], file_mapping_root=self.root, context=self.get_context(), time=self.arc_time)
+        archive_file_tree.add_file_mapping(arc_dir="", file_mapping=self.release_info["msvc"]["files-lib"], file_mapping_root=self.root, context=self.get_context(extra_context=extra_context), time=self.arc_time)

        logger.info("Creating %s", zip_path)
        with Archiver(zip_path=zip_path) as archiver:
@@ -1489,8 +1495,11 @@ def main(argv=None) -> int:
        if args.android_api is None:
            with section_printer.group("Detect Android APIS"):
                args.android_api = releaser._detect_android_api(android_home=args.android_home)
-        if args.android_api is None or not (Path(args.android_home) / f"platforms/android-{args.android_api}").is_dir():
+        if args.android_api is None:
            parser.error("Invalid --android-api, and/or could not be detected")
+        android_api_path = Path(args.android_home) / f"platforms/android-{args.android_api}"
+        if not android_api_path.is_dir():
+            parser.error(f"Android API directory does not exist ({android_api_path})")
        with section_printer.group("Android arguments"):
            print(f"android_home     = {args.android_home}")
            print(f"android_ndk_home = {args.android_ndk_home}")
--- a/build-scripts/pkg-support/android/INSTALL.md.in
+++ b/build-scripts/pkg-support/android/INSTALL.md.in
@@ -1,17 +1,7 @@

-The Simple DirectMedia Layer (SDL for short) is a cross-platform library
-designed to make it easy to write multi-media software, such as games
-and emulators.
+# Using this package

-The Simple DirectMedia Layer library source code is available from:
-https://www.libsdl.org/
-
-This library is distributed under the terms of the zlib license:
-http://www.zlib.net/zlib_license.html
-
-# @<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar
-
-This Android archive allows use of @<@PROJECT_NAME@>@ in your Android project, without needing to copy any SDL source.
+This package contains SDL built for the Android platform.

 ## Gradle integration

@@ -65,13 +55,37 @@ python @<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar -o android_prefix
 ```
 Add `--help` for a list of all available options.

+# Documentation

-Look at the example programs in ./examples (of the source archive), and check out online documentation:
-    https://wiki.libsdl.org/SDL3/FrontPage
+An API reference, tutorials, and additional documentation is available at:

-Join the SDL discourse server if you want to join the community:
-    https://discourse.libsdl.org/
+https://wiki.libsdl.org/SDL3

+# Example code
+
+There are simple example programs available at:
+
+https://examples.libsdl.org/SDL3
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php

-That's it!
-Sam Lantinga <slouken@libsdl.org>
--- a/build-scripts/pkg-support/mingw/INSTALL.md
+++ b/build-scripts/pkg-support/mingw/INSTALL.md
@@ -0,0 +1,53 @@
+
+# Using this package
+
+This package contains SDL built for the mingw-w64 toolchain.
+
+The files for 32-bit architecture are in i686-w64-mingw32
+The files for 64-bit architecture are in x86_64-w64-mingw32
+
+You can install them to another location, just type `make` for help.
+
+To use this package, point your include path at _arch_/include and your library path at _arch_/lib, link with the SDL3 library and copy _arch_/bin/SDL3.dll next to your executable.
+
+e.g.
+```sh
+gcc -o hello.exe hello.c -Ix86_64-w64-mingw32/include -Lx86_64-w64-mingw32/lib -lSDL3
+cp x86_64-w64-mingw32/bin/SDL3.dll .
+./hello.exe
+```
+
+# Documentation
+
+An API reference, tutorials, and additional documentation is available at:
+
+https://wiki.libsdl.org/SDL3
+
+# Example code
+
+There are simple example programs available at:
+
+https://examples.libsdl.org/SDL3
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
--- a/build-scripts/pkg-support/mingw/INSTALL.txt
+++ b/build-scripts/pkg-support/mingw/INSTALL.txt
@@ -1,25 +0,0 @@
-
-The 32-bit files are in i686-w64-mingw32
-The 64-bit files are in x86_64-w64-mingw32
-
-To install SDL for 32-bit x86 executables (i686):
-    make install-i686
-
-To install SDL for 64-bit x86 executables (x86_64):
-    make install-x86_64
-
-To install both:
-    make install-all
-
-Use DESTDIR to change the target location
-    mkdir $HOME/mingw32-prefix
-    make install-i686 DESTDIR=$HOME/mingw32-prefix
-
-Look at the example programs in ./examples, 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>
--- a/build-scripts/pkg-support/msvc/INSTALL.md
+++ b/build-scripts/pkg-support/msvc/INSTALL.md
@@ -0,0 +1,45 @@
+
+# Using this package
+
+This package contains SDL built for Visual Studio.
+
+To use this package, edit your project properties:
+- Add the include directory to "VC++ Directories" -> "Include Directories"
+- Add the lib/_arch_ directory to "VC++ Directories" -> "Library Directories"
+- Add SDL3.lib to Linker -> Input -> "Additional Dependencies"
+- Copy lib/_arch_/SDL3.dll to your project directory.
+
+# Documentation
+
+An API reference, tutorials, and additional documentation is available at:
+
+https://wiki.libsdl.org/SDL3
+
+# Example code
+
+There are simple example programs available at:
+
+https://examples.libsdl.org/SDL3
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
--- a/build-scripts/pkg-support/msvc/arm64/INSTALL.md.in
+++ b/build-scripts/pkg-support/msvc/arm64/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for arm64 Windows.
+
+To use this package, simply replace an existing 64-bit ARM @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
--- a/build-scripts/pkg-support/msvc/x64/INSTALL.md.in
+++ b/build-scripts/pkg-support/msvc/x64/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for x64 Windows.
+
+To use this package, simply replace an existing 64-bit @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
--- a/build-scripts/pkg-support/msvc/x86/INSTALL.md.in
+++ b/build-scripts/pkg-support/msvc/x86/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for x86 Windows.
+
+To use this package, simply replace an existing 32-bit @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+-  @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
--- a/build-scripts/release-info.json
+++ b/build-scripts/release-info.json
@@ -45,21 +45,14 @@
    },
    "files": {
      "": [
-        "build-scripts/pkg-support/mingw/INSTALL.txt",
+        "build-scripts/pkg-support/mingw/INSTALL.md",
        "build-scripts/pkg-support/mingw/Makefile",
-        "BUGS.txt",
-        "CREDITS.md",
-        "README-SDL.txt",
-        "WhatsNew.txt",
        "LICENSE.txt",
        "README.md"
      ],
      "cmake": [
        "build-scripts/pkg-support/mingw/cmake/SDL3Config.cmake",
        "build-scripts/pkg-support/mingw/cmake/SDL3ConfigVersion.cmake"
-      ],
-      "docs": [
-        "docs/*"
      ]
    }
  },
@@ -117,25 +110,22 @@
    },
    "files-lib": {
      "": [
-        "README-SDL.txt"
+        "build-scripts/pkg-support/msvc/@<@ARCH@>@/INSTALL.md.in:INSTALL.md",
+        "LICENSE.txt",
+        "README.md"
      ]
    },
    "files-devel": {
      "": [
-        "README-SDL.txt",
-        "BUGS.txt",
+        "build-scripts/pkg-support/msvc/INSTALL.md",
        "LICENSE.txt",
-        "README.md",
-        "WhatsNew.txt"
+        "README.md"
      ],
      "cmake": [
        "build-scripts/pkg-support/msvc/cmake/SDL3Config.cmake.in:SDL3Config.cmake",
        "build-scripts/pkg-support/msvc/cmake/SDL3ConfigVersion.cmake.in:SDL3ConfigVersion.cmake",
        "cmake/sdlcpu.cmake"
      ],
-      "docs": [
-        "docs/*"
-      ],
      "include/SDL3": [
        "include/SDL3/*.h"
      ]
@@ -211,8 +201,9 @@
    },
    "files": {
      "": [
+        "build-scripts/pkg-support/android/INSTALL.md.in:INSTALL.md",
        "LICENSE.txt",
-        "build-scripts/pkg-support/android/README.md.in:README.md"
+        "README.md"
      ]
    }
  }