From 6aaedb813fa11ba0679c3051bc2eb28646b9506c Mon Sep 17 00:00:00 2001 From: 3gg <3gg@shellblade.net> Date: Sat, 30 Aug 2025 16:53:58 -0700 Subject: Update to SDL3 --- src/contrib/SDL-3.2.20/docs/INTRO-androidstudio.md | 17 + src/contrib/SDL-3.2.20/docs/INTRO-cmake.md | 57 + src/contrib/SDL-3.2.20/docs/INTRO-emscripten.md | 50 + src/contrib/SDL-3.2.20/docs/INTRO-mingw.md | 95 + src/contrib/SDL-3.2.20/docs/INTRO-visualstudio.md | 16 + src/contrib/SDL-3.2.20/docs/INTRO-xcode.md | 16 + src/contrib/SDL-3.2.20/docs/README-android.md | 653 ++++++ src/contrib/SDL-3.2.20/docs/README-bsd.md | 6 + src/contrib/SDL-3.2.20/docs/README-cmake.md | 364 ++++ src/contrib/SDL-3.2.20/docs/README-contributing.md | 107 + .../SDL-3.2.20/docs/README-documentation-rules.md | 410 ++++ src/contrib/SDL-3.2.20/docs/README-dynapi.md | 138 ++ src/contrib/SDL-3.2.20/docs/README-emscripten.md | 350 +++ src/contrib/SDL-3.2.20/docs/README-gdk.md | 174 ++ src/contrib/SDL-3.2.20/docs/README-haiku.md | 4 + src/contrib/SDL-3.2.20/docs/README-highdpi.md | 40 + src/contrib/SDL-3.2.20/docs/README-ios.md | 260 +++ src/contrib/SDL-3.2.20/docs/README-kmsbsd.md | 27 + src/contrib/SDL-3.2.20/docs/README-linux.md | 98 + src/contrib/SDL-3.2.20/docs/README-macos.md | 251 +++ .../SDL-3.2.20/docs/README-main-functions.md | 236 ++ src/contrib/SDL-3.2.20/docs/README-migration.md | 2295 ++++++++++++++++++++ src/contrib/SDL-3.2.20/docs/README-n3ds.md | 28 + src/contrib/SDL-3.2.20/docs/README-ngage.md | 5 + src/contrib/SDL-3.2.20/docs/README-platforms.md | 40 + src/contrib/SDL-3.2.20/docs/README-porting.md | 65 + src/contrib/SDL-3.2.20/docs/README-ps2.md | 47 + src/contrib/SDL-3.2.20/docs/README-ps4.md | 3 + src/contrib/SDL-3.2.20/docs/README-ps5.md | 3 + src/contrib/SDL-3.2.20/docs/README-psp.md | 36 + src/contrib/SDL-3.2.20/docs/README-riscos.md | 35 + src/contrib/SDL-3.2.20/docs/README-steamos.md | 10 + src/contrib/SDL-3.2.20/docs/README-strings.md | 7 + src/contrib/SDL-3.2.20/docs/README-switch.md | 3 + src/contrib/SDL-3.2.20/docs/README-touch.md | 81 + src/contrib/SDL-3.2.20/docs/README-versions.md | 48 + src/contrib/SDL-3.2.20/docs/README-vita.md | 33 + src/contrib/SDL-3.2.20/docs/README-wayland.md | 242 +++ src/contrib/SDL-3.2.20/docs/README-windows.md | 128 ++ src/contrib/SDL-3.2.20/docs/README.md | 45 + src/contrib/SDL-3.2.20/docs/doxyfile | 1564 +++++++++++++ src/contrib/SDL-3.2.20/docs/hello.c | 68 + src/contrib/SDL-3.2.20/docs/release_checklist.md | 52 + 43 files changed, 8207 insertions(+) create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-androidstudio.md create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-cmake.md create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-emscripten.md create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-mingw.md create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-visualstudio.md create mode 100644 src/contrib/SDL-3.2.20/docs/INTRO-xcode.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-android.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-bsd.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-cmake.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-contributing.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-documentation-rules.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-dynapi.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-emscripten.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-gdk.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-haiku.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-highdpi.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-ios.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-kmsbsd.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-linux.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-macos.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-main-functions.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-migration.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-n3ds.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-ngage.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-platforms.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-porting.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-ps2.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-ps4.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-ps5.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-psp.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-riscos.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-steamos.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-strings.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-switch.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-touch.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-versions.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-vita.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-wayland.md create mode 100644 src/contrib/SDL-3.2.20/docs/README-windows.md create mode 100644 src/contrib/SDL-3.2.20/docs/README.md create mode 100644 src/contrib/SDL-3.2.20/docs/doxyfile create mode 100644 src/contrib/SDL-3.2.20/docs/hello.c create mode 100644 src/contrib/SDL-3.2.20/docs/release_checklist.md (limited to 'src/contrib/SDL-3.2.20/docs') diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-androidstudio.md b/src/contrib/SDL-3.2.20/docs/INTRO-androidstudio.md new file mode 100644 index 0000000..f4d8ecc --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-androidstudio.md @@ -0,0 +1,17 @@ + +# Introduction to SDL with Android Studio + +We'll start by creating a simple project to build and run [hello.c](hello.c) + +- Use our handy script to create a template project: +```sh +./build-scripts/create-android-project.py org.libsdl.hello docs/hello.c +``` +- Run Android Studio and open the newly created build/org.libsdl.hello directory +- Build and run! + +A more complete example is available at: + +https://github.com/Ravbug/sdl3-sample + +Additional information and troubleshooting is available in [README-android.md](README-android.md) diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-cmake.md b/src/contrib/SDL-3.2.20/docs/INTRO-cmake.md new file mode 100644 index 0000000..05990e4 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-cmake.md @@ -0,0 +1,57 @@ + +# Introduction to SDL with CMake + +The easiest way to use SDL is to include it as a subproject in your project. + +We'll start by creating a simple project to build and run [hello.c](hello.c) + +# Get a copy of the SDL source: +```sh +git clone https://github.com/libsdl-org/SDL.git vendored/SDL +``` + +# Create the file CMakeLists.txt +```cmake +cmake_minimum_required(VERSION 3.16) +project(hello) + +# set the output directory for built objects. +# This makes sure that the dynamic library goes into the build directory automatically. +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$") + +# This assumes the SDL source is available in vendored/SDL +add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL) + +# Create your game executable target as usual +add_executable(hello WIN32 hello.c) + +# Link to the actual SDL3 library. +target_link_libraries(hello PRIVATE SDL3::SDL3) +``` + +# Configure and Build: +```sh +cmake -S . -B build +cmake --build build +``` + +# Run: +The executable should be in the `build` directory: + +```sh +cd build +./hello +``` + +If there wasn't an executable there despite the above Build section running successfully, it's likely because you're following this guide using the Visual Studio toolchain, it should instead be in the `build/Debug` directory: +```sh +cd build/Debug +./hello +``` + +A more complete example is available at: + +https://github.com/Ravbug/sdl3-sample + +Additional information and troubleshooting is available in [README-cmake.md](README-cmake.md) diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-emscripten.md b/src/contrib/SDL-3.2.20/docs/INTRO-emscripten.md new file mode 100644 index 0000000..a0541c8 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-emscripten.md @@ -0,0 +1,50 @@ + +# Introduction to SDL with Emscripten + +The easiest way to use SDL is to include it as a subproject in your project. + +We'll start by creating a simple project to build and run [hello.c](hello.c) + +First, you should have the Emscripten SDK installed from: + +https://emscripten.org/docs/getting_started/downloads.html + +Create the file CMakeLists.txt +```cmake +cmake_minimum_required(VERSION 3.16) +project(hello) + +# set the output directory for built objects. +# This makes sure that the dynamic library goes into the build directory automatically. +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$") + +# This assumes the SDL source is available in vendored/SDL +add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL) + +# on Web targets, we need CMake to generate a HTML webpage. +if(EMSCRIPTEN) + set(CMAKE_EXECUTABLE_SUFFIX ".html" CACHE INTERNAL "") +endif() + +# Create your game executable target as usual +add_executable(hello WIN32 hello.c) + +# Link to the actual SDL3 library. +target_link_libraries(hello PRIVATE SDL3::SDL3) +``` + +Build: +```sh +emcmake cmake -S . -B build +cd build +emmake make +``` + +You can now run your app by pointing a webserver at your build directory and connecting a web browser to it, opening hello.html + +A more complete example is available at: + +https://github.com/Ravbug/sdl3-sample + +Additional information and troubleshooting is available in [README-emscripten.md](README-emscripten.md) diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-mingw.md b/src/contrib/SDL-3.2.20/docs/INTRO-mingw.md new file mode 100644 index 0000000..d7c535d --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-mingw.md @@ -0,0 +1,95 @@ +# Introduction to SDL with MinGW + +Without getting deep into the history, MinGW is a long running project that aims to bring gcc to Windows. That said, there's many distributions, versions, and forks floating around. We recommend installing [MSYS2](https://www.msys2.org/), as it's the easiest way to get a modern toolchain with a package manager to help with dependency management. This would allow you to follow the MSYS2 section below. + +Otherwise you'll want to follow the "Other Distributions" section below. + +We'll start by creating a simple project to build and run [hello.c](hello.c). + +# MSYS2 + +Open the `MSYS2 UCRT64` prompt and then ensure you've installed the following packages. This will get you working toolchain, CMake, Ninja, and of course SDL3. + +```sh +pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-sdl3 +``` + +## Create the file CMakeLists.txt +```cmake +cmake_minimum_required(VERSION 3.26) +project(hello C CXX) + +find_package(SDL3 REQUIRED) + +add_executable(hello) + +target_sources(hello +PRIVATE + hello.c +) + +target_link_libraries(hello SDL3::SDL3) +``` + +## Configure and Build: +```sh +cmake -S . -B build +cmake --build build +``` + +## Run: + +The executable is in the `build` directory: +```sh +cd build +./hello +``` + +# Other Distributions + +Things can get quite complicated with other distributions of MinGW. If you can't follow [the cmake intro](INTRO-cmake.md), perhaps due to issues getting cmake to understand your toolchain, this section should work. + +## Acquire SDL + +Download the `SDL3-devel--mingw.zip` asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest) Then extract it inside your project folder such that the output of `ls SDL3-` looks like `INSTALL.md LICENSE.txt Makefile README.md cmake i686-w64-mingw32 x86_64-w64-mingw32`. + +## Know your Target Architecture + +It is not uncommon for folks to not realize their distribution is targeting 32bit Windows despite things like the name of the toolchain, or the fact that they're running on a 64bit system. We'll ensure we know up front what we need: + +Create a file named `arch.c` with the following contents: +```c +#include +#include +int main() { + #if defined(__x86_64__) || defined(_M_X64) || defined(i386) || defined(__i386__) || defined(__i386) || defined(_M_IX86) + size_t ptr_size = sizeof(int*); + if (4 == ptr_size) puts("i686-w64-mingw32"); + else if (8 == ptr_size) puts("x86_64-w64-mingw32"); + else puts("Unknown Architecture"); + #else + puts("Unknown Architecture"); + #endif + return 0; +} +``` + +Then run + +```sh +gcc arch.c +./a.exe +``` + +This should print out which library directory we'll need to use when compiling, keep this value in mind, you'll need to use it when compiling in the next section as ``. If you get "Unknown Architecture" please [report a bug](https://github.com/libsdl-org/SDL/issues). + + +## Build and Run + +Now we should have everything needed to compile and run our program. You'll need to ensure to replace `` with the version of the release of SDL3 you downloaded, as well as use the `` we learned in the previous section. + +```sh +gcc hello.c -o hello.exe -I SDL3-//include -L SDL3-//lib -lSDL3 -mwindows +cp SDL3-//bin/SDL3.dll SDL3.dll +./hello.exe +``` diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-visualstudio.md b/src/contrib/SDL-3.2.20/docs/INTRO-visualstudio.md new file mode 100644 index 0000000..4017f79 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-visualstudio.md @@ -0,0 +1,16 @@ + +# Introduction to SDL with Visual Studio + +The easiest way to use SDL is to include it as a subproject in your project. + +We'll start by creating a simple project to build and run [hello.c](hello.c) + +- Get a copy of the SDL source, you can clone the repo, or download the "Source Code" asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest) + - If you've downloaded a release, make sure to extract the contents somewhere you can find it. +- Create a new project in Visual Studio, using the C++ Empty Project template +- Add hello.c to the Source Files +- Right click the solution, select add an existing project, navigate to `VisualC/SDL` from within the source you cloned or downloaded above and add SDL.vcxproj +- Select your main project and go to Project -> Add -> Reference and select SDL3 +- Select your main project and go to Project -> Properties, set the filter at the top to "All Configurations" and "All Platforms", select C/C++ -> General and add the SDL include directory to "Additional Include Directories" +- Build and run! + diff --git a/src/contrib/SDL-3.2.20/docs/INTRO-xcode.md b/src/contrib/SDL-3.2.20/docs/INTRO-xcode.md new file mode 100644 index 0000000..5f0a62a --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/INTRO-xcode.md @@ -0,0 +1,16 @@ + +# Introduction to SDL with Xcode + +The easiest way to use SDL is to include it as a subproject in your project. + +We'll start by creating a simple project to build and run [hello.c](hello.c) + +- Create a new project in Xcode, using the App template and selecting Objective C as the language +- Remove the .h and .m files that were automatically added to the project +- Remove the main storyboard that was automatically added to the project +- On iOS projects, select the project, select the main target, select the Info tab, look for "Custom iOS Target Properties", and remove "Main storyboard base file name" and "Application Scene Manifest" +- Right click the project and select "Add Files to [project]", navigate to the SDL docs directory and add the file hello.c +- Right click the project and select "Add Files to [project]", navigate to the SDL Xcode/SDL directory and add SDL.xcodeproj +- Select the project, select the main target, select the General tab, look for "Frameworks, Libaries, and Embedded Content", and add SDL3.framework +- Build and run! + diff --git a/src/contrib/SDL-3.2.20/docs/README-android.md b/src/contrib/SDL-3.2.20/docs/README-android.md new file mode 100644 index 0000000..e57ca81 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/README-android.md @@ -0,0 +1,653 @@ +Android +================================================================================ + +Matt Styles wrote a tutorial on building SDL for Android with Visual Studio: +http://trederia.blogspot.de/2017/03/building-sdl2-for-android-with-visual.html + +The rest of this README covers the Android gradle style build process. + + +Requirements +================================================================================ + +Android SDK (version 35 or later) +https://developer.android.com/sdk/index.html + +Android NDK r15c or later +https://developer.android.com/tools/sdk/ndk/index.html + +Minimum API level supported by SDL: 21 (Android 5.0) + + +How the port works +================================================================================ + +- Android applications are Java-based, optionally with parts written in C +- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to + the SDL library +- This means that your application C code must be placed inside an Android + Java project, along with some C support code that communicates with Java +- This eventually produces a standard Android .apk package + +The Android Java code implements an "Activity" and can be found in: +android-project/app/src/main/java/org/libsdl/app/SDLActivity.java + +The Java code loads your game code, the SDL shared library, and +dispatches to native functions implemented in the SDL library: +src/core/android/SDL_android.c + + +Building a simple app +================================================================================ + +For simple projects you can use the script located at build-scripts/create-android-project.py + +There's two ways of using it: + + ./create-android-project.py com.yourcompany.yourapp < sources.list + ./create-android-project.py com.yourcompany.yourapp source1.c source2.c ...sourceN.c + +sources.list should be a text file with a source file name in each line +Filenames should be specified relative to the current directory, for example if +you are in the build-scripts directory and want to create the testgles.c test, you'll +run: + + ./create-android-project.py org.libsdl.testgles ../test/testgles.c + +One limitation of this script is that all sources provided will be aggregated into +a single directory, thus all your source files should have a unique name. + +Once the project is complete the script will tell you how to build the project. +If you want to create a signed release APK, you can use the project created by this +utility to generate it. + +Running the script with `--help` will list all available options, and their purposes. + +Finally, a word of caution: re running create-android-project.py wipes any changes you may have +done in the build directory for the app! + + +Building a more complex app +================================================================================ + +For more complex projects, follow these instructions: + +1. Get the source code for SDL and copy the 'android-project' directory located at SDL/android-project to a suitable location in your project. + + The 'android-project' directory can basically be seen as a sort of starting point for the android-port of your project. It contains the glue code between the Android Java 'frontend' and the SDL code 'backend'. It also contains some standard behaviour, like how events should be handled, which you will be able to change. + +2. If you are _not_ already building SDL as a part of your project (e.g. via CMake add_subdirectory() or FetchContent) move or [symlink](https://en.wikipedia.org/wiki/Symbolic_link) the SDL directory into the 'android-project/app/jni' directory. Alternatively you can [use the SDL3 Android Archive (.aar)](#using-the-sdl3-android-archive-aar), see bellow for more details. + + This is needed as SDL has to be compiled by the Android compiler. + +3. Edit 'android-project/app/build.gradle' to include any assets that your app needs by adding 'assets.srcDirs' in 'sourceSets.main'. + + For example: `assets.srcDirs = ['../../assets', '../../shaders']` + +If using CMake: + +4. Edit 'android-project/app/build.gradle' to set 'buildWithCMake' to true and set 'externalNativeBuild' cmake path to your top level CMakeLists.txt. + + For example: `path '../../CMakeLists.txt'` + +5. Change the target containing your main function to be built as a shared library called "main" when compiling for Android. (e.g. add_executable(MyGame main.c) should become add_library(main SHARED main.c) on Android) + +If using Android Makefiles: + +4. Edit 'android-project/app/jni/src/Android.mk' to include your source files. They should be separated by spaces after the 'LOCAL_SRC_FILES := ' declaration. + +To build your app, run `./gradlew installDebug` or `./gradlew installRelease` in the project directory. It will build and install your .apk on any connected Android device. If you want to use Android Studio, simply open your 'android-project' directory and start building. + +Additionally the [SDL_helloworld](https://github.com/libsdl-org/SDL_helloworld) project contains a small example program with a functional Android port that you can use as a reference. + +Here's an explanation of the files in the Android project, so you can customize them: + + android-project/app + build.gradle - build info including the application version and SDK + src/main/AndroidManifest.xml - package manifest. Among others, it contains the class name of the main Activity and the package name of the application. + jni/ - directory holding native code + jni/Application.mk - Application JNI settings, including target platform and STL library + jni/Android.mk - Android makefile that can call recursively the Android.mk files in all subdirectories + jni/CMakeLists.txt - Top-level CMake project that adds SDL as a subproject + jni/SDL/ - (symlink to) directory holding the SDL library files + jni/SDL/Android.mk - Android makefile for creating the SDL shared library + jni/src/ - directory holding your C/C++ source + jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references + jni/src/CMakeLists.txt - CMake file that you may customize to include your source code and any library references + src/main/assets/ - directory holding asset files for your application + src/main/res/ - directory holding resources for your application + src/main/res/mipmap-* - directories holding icons for different phone hardware + src/main/res/values/strings.xml - strings used in your application, including the application name + src/main/java/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation. You should instead subclass this for your application. + + +Using the SDL3 Android Archive (.aar) +================================================================================ + +The Android archive allows use of SDL3 in your Android project, without needing to copy any SDL C or JAVA source into your project. +For integration with CMake/ndk-build, it uses [prefab](https://google.github.io/prefab/). + +Copy the archive to a `app/libs` directory in your project and add the following to `app/gradle.build`: +``` +android { + /* ... */ + buildFeatures { + prefab true + } +} +dependencies { + implementation files('libs/SDL3-X.Y.Z.aar') /* Replace with the filename of the actual SDL3-x.y.z.aar file you downloaded */ + /* ... */ +} +``` + +If you use CMake, add the following to your CMakeLists.txt: +``` +find_package(SDL3 REQUIRED CONFIG) +target_link_libraries(yourgame PRIVATE SDL3::SDL3) +``` + +If you use ndk-build, add the following before `include $(BUILD_SHARED_LIBRARY)` to your `Android.mk`: +``` +LOCAL_SHARED_LIBARARIES := SDL3 SDL3-Headers +``` +And add the following at the bottom: +``` +# 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@) +``` + +The `build-scripts/create-android-project.py` script can create a project using Android aar-chives from scratch: +``` +build-scripts/create-android-project.py --variant aar com.yourcompany.yourapp < sources.list +``` + +Customizing your application name +================================================================================ + +To customize your application name, edit AndroidManifest.xml and build.gradle to replace +"org.libsdl.app" with an identifier for your product package. + +Then create a Java class extending SDLActivity and place it in a directory +under src matching your package, e.g. + + app/src/main/java/com/gamemaker/game/MyGame.java + +Here's an example of a minimal class file: + + --- MyGame.java -------------------------- + package com.gamemaker.game; + + import org.libsdl.app.SDLActivity; + + /** + * A sample wrapper class that just calls SDLActivity + */ + + public class MyGame extends SDLActivity { } + + ------------------------------------------ + +Then replace "SDLActivity" in AndroidManifest.xml with the name of your +class, .e.g. "MyGame" + + +Customizing your application icon +================================================================================ + +Conceptually changing your icon is just replacing the "ic_launcher.png" files in +the drawable directories under the res directory. There are several directories +for different screen sizes. + + +Loading assets +================================================================================ + +Any files you put in the "app/src/main/assets" directory of your project +directory will get bundled into the application package and you can load +them using the standard functions in SDL_iostream.h. + +There are also a few Android specific functions that allow you to get other +useful paths for saving and loading data: +* SDL_GetAndroidInternalStoragePath() +* SDL_GetAndroidExternalStorageState() +* SDL_GetAndroidExternalStoragePath() +* SDL_GetAndroidCachePath() + +See SDL_system.h for more details on these functions. + +The asset packaging system will, by default, compress certain file extensions. +SDL includes two asset file access mechanisms, the preferred one is the so +called "File Descriptor" method, which is faster and doesn't involve the Dalvik +GC, but given this method does not work on compressed assets, there is also the +"Input Stream" method, which is automatically used as a fall back by SDL. You +may want to keep this fact in mind when building your APK, specially when large +files are involved. +For more information on which extensions get compressed by default and how to +disable this behaviour, see for example: + +http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/ + + +Activity lifecycle +================================================================================ + +On Android the application goes through a fixed life cycle and you will get +notifications of state changes via application events. When these events +are delivered you must handle them in an event callback because the OS may +not give you any processing time after the events are delivered. + +e.g. + + bool HandleAppEvents(void *userdata, SDL_Event *event) + { + switch (event->type) + { + case SDL_EVENT_TERMINATING: + /* Terminate the app. + Shut everything down before returning from this function. + */ + return false; + case SDL_EVENT_LOW_MEMORY: + /* You will get this when your app is paused and iOS wants more memory. + Release as much memory as possible. + */ + return false; + case SDL_EVENT_WILL_ENTER_BACKGROUND: + /* Prepare your app to go into the background. Stop loops, etc. + This gets called when the user hits the home button, or gets a call. + + You should not make any OpenGL graphics calls or use the rendering API, + in addition, you should set the render target to NULL, if you're using + it, e.g. call SDL_SetRenderTarget(renderer, NULL). + */ + return false; + case SDL_EVENT_DID_ENTER_BACKGROUND: + /* Your app is NOT active at this point. */ + return false; + case SDL_EVENT_WILL_ENTER_FOREGROUND: + /* This call happens when your app is coming back to the foreground. + Restore all your state here. + */ + return false; + case SDL_EVENT_DID_ENTER_FOREGROUND: + /* Restart your loops here. + Your app is interactive and getting CPU again. + + You have access to the OpenGL context or rendering API at this point. + However, there's a chance (on older hardware, or on systems under heavy load), + where the graphics context can not be restored. You should listen for the + event SDL_EVENT_RENDER_DEVICE_RESET and recreate your OpenGL context and + restore your textures when you get it, or quit the app. + */ + return false; + default: + /* No special processing, add it to the event queue */ + return true; + } + } + + int main(int argc, char *argv[]) + { + SDL_SetEventFilter(HandleAppEvents, NULL); + + ... run your main loop + + return 0; + } + + +Note that if you are using main callbacks instead of a standard C main() function, +your SDL_AppEvent() callback will run as these events arrive and you do not need to +use SDL_SetEventFilter. + +If SDL_HINT_ANDROID_BLOCK_ON_PAUSE hint is set (the default), +the event loop will block itself when the app is paused (ie, when the user +returns to the main Android dashboard). Blocking is better in terms of battery +use, and it allows your app to spring back to life instantaneously after resume +(versus polling for a resume message). + +You can control activity re-creation (eg. onCreate()) behaviour. This allows you +to choose whether to keep or re-initialize java and native static datas, see +SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY in SDL_hints.h. + + +Insets and Safe Areas +================================================================================ + +As of Android 15, SDL windows cover the entire screen, extending under notches +and system bars. The OS expects you to take those into account when displaying +content and SDL provides the function SDL_GetWindowSafeArea() so you know what +area is available for interaction. Outside of the safe area can be potentially +covered by system bars or used by OS gestures. + + +Mouse / Touch events +================================================================================ + +In some case, SDL generates synthetic mouse (resp. touch) events for touch +(resp. mouse) devices. +To enable/disable this behavior, see SDL_hints.h: +- SDL_HINT_TOUCH_MOUSE_EVENTS +- SDL_HINT_MOUSE_TOUCH_EVENTS + + +Misc +================================================================================ + +For some device, it appears to works better setting explicitly GL attributes +before creating a window: + SDL_GL_SetAttribute(SDL_GL_RED_SIZE, 5); + SDL_GL_SetAttribute(SDL_GL_GREEN_SIZE, 6); + SDL_GL_SetAttribute(SDL_GL_BLUE_SIZE, 5); + + +Threads and the Java VM +================================================================================ + +For a quick tour on how Linux native threads interoperate with the Java VM, take +a look here: https://developer.android.com/guide/practices/jni.html + +If you want to use threads in your SDL app, it's strongly recommended that you +do so by creating them using SDL functions. This way, the required attach/detach +handling is managed by SDL automagically. If you have threads created by other +means and they make calls to SDL functions, make sure that you call +Android_JNI_SetupThread() before doing anything else otherwise SDL will attach +your thread automatically anyway (when you make an SDL call), but it'll never +detach it. + + +If you ever want to use JNI in a native thread (created by "SDL_CreateThread()"), +it won't be able to find your java class and method because of the java class loader +which is different for native threads, than for java threads (eg your "main()"). + +the work-around is to find class/method, in you "main()" thread, and to use them +in your native thread. + +see: +https://developer.android.com/training/articles/perf-jni#faq:-why-didnt-findclass-find-my-class + + +Using STL +================================================================================ + +You can use STL in your project by creating an Application.mk file in the jni +folder and adding the following line: + + APP_STL := c++_shared + +For more information go here: + https://developer.android.com/ndk/guides/cpp-support + + +Using the emulator +================================================================================ + +There are some good tips and tricks for getting the most out of the +emulator here: https://developer.android.com/tools/devices/emulator.html + +Especially useful is the info on setting up OpenGL ES 2.0 emulation. + +Notice that this software emulator is incredibly slow and needs a lot of disk space. +Using a real device works better. + + +Troubleshooting +================================================================================ + +You can see if adb can see any devices with the following command: + + adb devices + +You can see the output of log messages on the default device with: + + adb logcat + +You can push files to the device with: + + adb push local_file remote_path_and_file + +You can push files to the SD Card at /sdcard, for example: + + adb push moose.dat /sdcard/moose.dat + +You can see the files on the SD card with a shell command: + + adb shell ls /sdcard/ + +You can start a command shell on the default device with: + + adb shell + +You can remove the library files of your project (and not the SDL lib files) with: + + ndk-build clean + +You can do a build with the following command: + + ndk-build + +You can see the complete command line that ndk-build is using by passing V=1 on the command line: + + ndk-build V=1 + +If your application crashes in native code, you can use ndk-stack to get a symbolic stack trace: + https://developer.android.com/ndk/guides/ndk-stack + +If you want to go through the process manually, you can use addr2line to convert the +addresses in the stack trace to lines in your code. + +For example, if your crash looks like this: + + I/DEBUG ( 31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0 + I/DEBUG ( 31): r0 00000000 r1 00001000 r2 00000003 r3 400085d4 + I/DEBUG ( 31): r4 400085d0 r5 40008000 r6 afd41504 r7 436c6a7c + I/DEBUG ( 31): r8 436c6b30 r9 435c6fb0 10 435c6f9c fp 4168d82c + I/DEBUG ( 31): ip 8346aff0 sp 436c6a60 lr afd1c8ff pc afd1c902 cpsr 60000030 + I/DEBUG ( 31): #00 pc 0001c902 /system/lib/libc.so + I/DEBUG ( 31): #01 pc 0001ccf6 /system/lib/libc.so + I/DEBUG ( 31): #02 pc 000014bc /data/data/org.libsdl.app/lib/libmain.so + I/DEBUG ( 31): #03 pc 00001506 /data/data/org.libsdl.app/lib/libmain.so + +You can see that there's a crash in the C library being called from the main code. +I run addr2line with the debug version of my code: + + arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so + +and then paste in the number after "pc" in the call stack, from the line that I care about: +000014bc + +I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23. + +You can add logging to your code to help show what's happening: + + #include + + __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x); + +If you need to build without optimization turned on, you can create a file called +"Application.mk" in the jni directory, with the following line in it: + + APP_OPTIM := debug + + +Memory debugging +================================================================================ + +The best (and slowest) way to debug memory issues on Android is valgrind. +Valgrind has support for Android out of the box, just grab code using: + + git clone https://sourceware.org/git/valgrind.git + +... and follow the instructions in the file `README.android` to build it. + +One thing I needed to do on macOS was change the path to the toolchain, +and add ranlib to the environment variables: +export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib + +Once valgrind is built, you can create a wrapper script to launch your +application with it, changing org.libsdl.app to your package identifier: + + --- start_valgrind_app ------------------- + #!/system/bin/sh + export TMPDIR=/data/data/org.libsdl.app + exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $* + ------------------------------------------ + +Then push it to the device: + + adb push start_valgrind_app /data/local + +and make it executable: + + adb shell chmod 755 /data/local/start_valgrind_app + +and tell Android to use the script to launch your application: + + adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app" + +If the setprop command says "could not set property", it's likely that +your package name is too long and you should make it shorter by changing +AndroidManifest.xml and the path to your class file in android-project/src + +You can then launch your application normally and waaaaaaaiiittt for it. +You can monitor the startup process with the logcat command above, and +when it's done (or even while it's running) you can grab the valgrind +output file: + + adb pull /sdcard/valgrind.log + +When you're done instrumenting with valgrind, you can disable the wrapper: + + adb shell setprop wrap.org.libsdl.app "" + + +Graphics debugging +================================================================================ + +If you are developing on a compatible Tegra-based tablet, NVidia provides +Tegra Graphics Debugger at their website. Because SDL3 dynamically loads EGL +and GLES libraries, you must follow their instructions for installing the +interposer library on a rooted device. The non-rooted instructions are not +compatible with applications that use SDL3 for video. + +The Tegra Graphics Debugger is available from NVidia here: +https://developer.nvidia.com/tegra-graphics-debugger + + +A note regarding the use of the "dirty rectangles" rendering technique +================================================================================ + +If your app uses a variation of the "dirty rectangles" rendering technique, +where you only update a portion of the screen on each frame, you may notice a +variety of visual glitches on Android, that are not present on other platforms. +This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2 +contexts, in particular the use of the eglSwapBuffers function. As stated in the +documentation for the function "The contents of ancillary buffers are always +undefined after calling eglSwapBuffers". + + +Ending your application +================================================================================ + +Two legitimate ways: + +- return from your main() function. Java side will automatically terminate the +Activity by calling Activity.finish(). + +- Android OS can decide to terminate your application by calling onDestroy() +(see Activity life cycle). Your application will receive an SDL_EVENT_QUIT you +can handle to save things and quit. + +Don't call exit() as it stops the activity badly. + +NB: "Back button" can be handled as a SDL_EVENT_KEY_DOWN/UP events, with Keycode +SDLK_AC_BACK, for any purpose. + + +Known issues +================================================================================ + +- The number of buttons reported for each joystick is hardcoded to be 36, which +is the current maximum number of buttons Android can report. + + +Building the SDL tests +================================================================================ + +SDL's CMake build system can create APK's for the tests. +It can build all tests with a single command without a dependency on gradle or Android Studio. +The APK's are signed with a debug certificate. +The only caveat is that the APK's support a single architecture. + +### Requirements +- SDL source tree +- CMake +- ninja or make +- Android Platform SDK +- Android NDK +- Android Build tools +- Java JDK (version should be compatible with Android) +- keytool (usually provided with the Java JDK), used for generating a debug certificate +- zip + +### CMake configuration + +When configuring the CMake project, you need to use the Android NDK CMake toolchain, and pass the Android home path through `SDL_ANDROID_HOME`. +``` +cmake .. -DCMAKE_TOOLCHAIN_FILE= -DANDROID_ABI= -DSDL_ANDROID_HOME= -DANDROID_PLATFORM=23 -DSDL_TESTS=ON +``` + +Remarks: +- `android.toolchain.cmake` can usually be found at `$ANDROID_HOME/ndk/x.y.z/build/cmake/android.toolchain.cmake` +- `ANDROID_ABI` should be one of `arm64-v8a`, `armeabi-v7a`, `x86` or `x86_64`. +- When CMake is unable to find required paths, use `cmake-gui` to override required `SDL_ANDROID_` CMake cache variables. + +### Building the APK's + +For the `testsprite` executable, the `testsprite-apk` target will build the associated APK: +``` +cmake --build . --target testsprite-apk +``` + +APK's of all tests can be built with the `sdl-test-apks` target: +``` +cmake --build . --target sdl-test-apks +``` + +### Installation/removal of the tests + +`testsprite.apk` APK can be installed on your Android machine using the `install-testsprite` target: +``` +cmake --build . --target install-testsprite +``` + +APK's of all tests can be installed with the `install-sdl-test-apks` target: +``` +cmake --build . --target install-sdl-test-apks +``` + +All SDL tests can be uninstalled with the `uninstall-sdl-test-apks` target: +``` +cmake --build . --target uninstall-sdl-test-apks +``` + +### Starting the tests + +After installation, the tests can be started using the Android Launcher GUI. +Alternatively, they can also be started using CMake targets. + +This command will start the testsprite executable: +``` +cmake --build . --target start-testsprite +``` + +There is also a convenience target which will build, install and start a test: +``` +cmake --build . --target build-install-start-testsprite +``` + +Not all tests provide a GUI. For those, you can use `adb logcat` to read the output. diff --git a/src/contrib/SDL-3.2.20/docs/README-bsd.md b/src/contrib/SDL-3.2.20/docs/README-bsd.md new file mode 100644 index 0000000..d823060 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/README-bsd.md @@ -0,0 +1,6 @@ +# FreeBSD / OpenBSD / NetBSD + +SDL is fully supported on BSD platforms, and is built using [CMake](README-cmake.md). + +If you want to run on the console, you can take a look at [KMSDRM support on BSD](README-kmsbsd.md) + diff --git a/src/contrib/SDL-3.2.20/docs/README-cmake.md b/src/contrib/SDL-3.2.20/docs/README-cmake.md new file mode 100644 index 0000000..f2e4759 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/README-cmake.md @@ -0,0 +1,364 @@ +# CMake + +[www.cmake.org](https://www.cmake.org/) + +The CMake build system is supported with the following environments: + +* Android +* Emscripten +* FreeBSD +* Haiku +* Linux +* macOS, iOS, tvOS, and visionOS with support for XCode +* Microsoft Visual Studio +* MinGW and Msys +* NetBSD +* Nintendo 3DS +* PlayStation 2 +* PlayStation Portable +* PlayStation Vita +* RISC OS + +## Building SDL on Windows + +Assuming you're in the SDL source directory, building and installing to C:/SDL can be done with: +```sh +cmake -S . -B build +cmake --build build --config RelWithDebInfo +cmake --install build --config RelWithDebInfo --prefix C:/SDL +``` + +## Building SDL on UNIX + +SDL will build with very few dependencies, but for full functionality you should install the packages detailed in [README-linux.md](README-linux.md). + +Assuming you're in the SDL source directory, building and installing to /usr/local can be done with: +```sh +cmake -S . -B build +cmake --build build +sudo cmake --install build --prefix /usr/local +``` + +## Building SDL on macOS + +Assuming you're in the SDL source directory, building and installing to ~/SDL can be done with: +```sh +cmake -S . -B build -DSDL_FRAMEWORK=ON -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" +cmake --build build +cmake --install build --prefix ~/SDL +``` + +## Building SDL tests + +You can build the SDL test programs by adding `-DSDL_TESTS=ON` to the first cmake command above: +```sh +cmake -S . -B build -DSDL_TESTS=ON +``` +and then building normally. The test programs will be built and can be run from `build/test/`. + +## Building SDL examples + +You can build the SDL example programs by adding `-DSDL_EXAMPLES=ON` to the first cmake command above: +```sh +cmake -S . -B build -DSDL_EXAMPLES=ON +``` +and then building normally. The example programs will be built and can be run from `build/examples/`. + +## Including SDL in your project + +SDL can be included in your project in 2 major ways: +- using a system SDL library, provided by your (UNIX) distribution or a package manager +- using a vendored SDL library: this is SDL copied or symlinked in a subfolder. + +The following CMake script supports both, depending on the value of `MYGAME_VENDORED`. + +```cmake +cmake_minimum_required(VERSION 3.5) +project(mygame) + +# Create an option to switch between a system sdl library and a vendored SDL library +option(MYGAME_VENDORED "Use vendored libraries" OFF) + +if(MYGAME_VENDORED) + # This assumes you have added SDL as a submodule in vendored/SDL + add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL) +else() + # 1. Look for a SDL3 package, + # 2. look for the SDL3-shared component, and + # 3. fail if the shared component cannot be found. + find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3-shared) +endif() + +# Create your game executable target as usual +add_executable(mygame WIN32 mygame.c) + +# Link to the actual SDL3 library. +target_link_libraries(mygame PRIVATE SDL3::SDL3) +``` + +### A system SDL library + +For CMake to find SDL, it must be installed in [a default location CMake is looking for](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure). + +The following components are available, to be used as an argument of `find_package`. + +| Component name | Description | +|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| SDL3-shared | The SDL3 shared library, available through the `SDL3::SDL3-shared` target | +| SDL3-static | The SDL3 static library, available through the `SDL3::SDL3-static` target | +| SDL3_test | The SDL3_test static library, available through the `SDL3::SDL3_test` target | +| SDL3 | The SDL3 library, available through the `SDL3::SDL3` target. This is an alias of `SDL3::SDL3-shared` or `SDL3::SDL3-static`. This component is always available. | +| Headers | The SDL3 headers, available through the `SDL3::Headers` target. This component is always available. | + +SDL's CMake support guarantees a `SDL3::SDL3` target. +Neither `SDL3::SDL3-shared` nor `SDL3::SDL3-static` are guaranteed to exist. + +### Using a vendored SDL + +This only requires a copy of SDL in a subdirectory + `add_subdirectory`. +Alternatively, use [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html). +Depending on the configuration, the same targets as a system SDL package are available. + +## CMake configuration options + +### Build optimized library + +By default, CMake provides 4 build types: `Debug`, `Release`, `RelWithDebInfo` and `MinSizeRel`. +The main difference(s) between these are the optimization options and the generation of debug info. +To configure SDL as an optimized `Release` library, configure SDL with: +```sh +cmake ~/SDL -DCMAKE_BUILD_TYPE=Release +``` +To build it, run: +```sh +cmake --build . --config Release +``` + +### Shared or static + +By default, only a dynamic (=shared) SDL library is built and installed. +The options `-DSDL_SHARED=` and `-DSDL_STATIC=` accept boolean values to change this. + +Exceptions exist: +- some platforms don't support dynamic libraries, so only `-DSDL_STATIC=ON` makes sense. +- a static Apple framework is not supported + +### Man pages + +Configuring with `-DSDL_INSTALL_DOCS=TRUE` installs man pages. + +We recommend package managers of unix distributions to install SDL3's man pages. +This adds an extra build-time dependency on Perl. + +### Pass custom compile options to the compiler + +- Use [`CMAKE__FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html) to pass extra +flags to the compiler. +- Use [`CMAKE_EXE_LINKER_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_EXE_LINKER_FLAGS.html) to pass extra option to the linker for executables. +- Use [`CMAKE_SHARED_LINKER_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_SHARED_LINKER_FLAGS.html) to pass extra options to the linker for shared libraries. + +#### Examples + +- build a SDL library optimized for (more) modern x64 microprocessor architectures. + + With gcc or clang: + ```sh + cmake ~/sdl -DCMAKE_C_FLAGS="-march=x86-64-v3" -DCMAKE_CXX_FLAGS="-march=x86-64-v3" + ``` + With Visual C: + ```sh + cmake .. -DCMAKE_C_FLAGS="/ARCH:AVX2" -DCMAKE_CXX_FLAGS="/ARCH:AVX2" + ``` + +### Apple + +CMake documentation for cross building for Apple: +[link](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-ios-tvos-visionos-or-watchos) + +#### iOS/tvOS/visionOS + +CMake 3.14+ natively includes support for iOS, tvOS and watchOS. visionOS requires CMake 3.28+. +SDL binaries may be built using Xcode or Make, possibly among other build-systems. + +When using a compatible version of CMake, it should be possible to: + +- build SDL dylibs, both static and dynamic dylibs +- build SDL frameworks, only shared +- build SDL test apps + +#### Frameworks + +Configure with `-DSDL_FRAMEWORK=ON` to build a SDL framework instead of a dylib shared library. +Only shared frameworks are supported, no static ones. + +#### Platforms + +Use `-DCMAKE_SYSTEM_NAME=` to configure the platform. CMake can target only one platform at a time. + +| Apple platform | `CMAKE_SYSTEM_NAME` value | +|-----------------|---------------------------| +| macOS (MacOS X) | `Darwin` | +| iOS | `iOS` | +| tvOS | `tvOS` | +| visionOS | `visionOS` | +| watchOS | `watchOS` | + +#### Universal binaries + +A universal binaries, can be built by configuring CMake with +`-DCMAKE_OSX_ARCHITECTURES=`. + +For example `-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"` will build binaries that run on both Intel cpus and Apple silicon. + +SDL supports following Apple architectures: + +| Platform | `CMAKE_OSX_ARCHITECTURES` value | +|----------------------------|---------------------------------| +| 64-bit ARM (Apple Silicon) | `arm64` | +| x86_64 | `x86_64` | +| 32-bit ARM | `armv7s` | + +CMake documentation: [link](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) + +#### Simulators and/or non-default macOS platform SDK + +Use `-DCMAKE_OSX_SYSROOT=` to configure a different platform SDK. +The value can be either the name of the SDK, or a full path to the sdk (e.g. `/full/path/to/iPhoneOS.sdk`). + +| SDK | `CMAKE_OSX_SYSROOT` value | +|----------------------|---------------------------| +| iphone | `iphoneos` | +| iphonesimulator | `iphonesimulator` | +| appleTV | `appletvos` | +| appleTV simulator | `appletvsimulator` | +| visionOS | `xr` | +| visionOS simulator | `xrsimulator` | +| watchOS | `watchos` | +| watchOS simulator | `watchsimulator` | + +Append with a version number to target a specific SDK revision: e.g. `iphoneos12.4`, `appletvos12.4`. + +CMake documentation: [link](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) + +#### Examples + +- for macOS, building a dylib and/or static library for x86_64 and arm64: + + ```bash + cmake ~/sdl -DCMAKE_SYSTEM_NAME=Darwin -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 + +- for macOS, building an universal framework for x86_64 and arm64: + + ```bash + cmake ~/sdl -DSDL_FRAMEWORK=ON -DCMAKE_SYSTEM_NAME=Darwin -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 + +- for iOS-Simulator, using the latest, installed SDK: + + ```bash + cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for iOS-Device, using the latest, installed SDK, 64-bit only + + ```bash + cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for iOS-Device, using the latest, installed SDK, mixed 32/64 bit + + ```cmake + cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s" -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for iOS-Device, using a specific SDK revision (iOS 12.4, in this example): + + ```cmake + cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64 + ``` + +- for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles): + + ```cmake + cmake ~/sdl -DSDL_TESTS=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for tvOS-Simulator, using the latest, installed SDK: + + ```cmake + cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for tvOS-Device, using the latest, installed SDK: + + ```cmake + cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64` -DCMAKE_OSX_DEPLOYMENT_TARGET=9.0 + ``` + +- for QNX/aarch64, using the latest, installed SDK: + + ```cmake + cmake ~/sdl -DCMAKE_TOOLCHAIN_FILE=~/sdl/build-scripts/cmake-toolchain-qnx-aarch64le.cmake -DSDL_X11=0 + ``` + +## SDL-specific CMake options + +SDL can be customized through (platform-specific) CMake options. +The following table shows generic options that are available for most platforms. +At the end of SDL CMake configuration, a table shows all CMake options along with its detected value. + +| CMake option | Valid values | Description | +|-------------------------------|--------------|-----------------------------------------------------------------------------------------------------| +| `-DSDL_SHARED=` | `ON`/`OFF` | Build SDL shared library (not all platforms support this) (`libSDL3.so`/`libSDL3.dylib`/`SDL3.dll`) | +| `-DSDL_STATIC=` | `ON`/`OFF` | Build SDL static library (`libSDL3.a`/`SDL3-static.lib`) | +| `-DSDL_TEST_LIBRARY=` | `ON`/`OFF` | Build SDL test library (`libSDL3_test.a`/`SDL3_test.lib`) | +| `-DSDL_TESTS=` | `ON`/`OFF` | Build SDL test programs (**requires `-DSDL_TEST_LIBRARY=ON`**) | +| `-DSDL_DISABLE_INSTALL=` | `ON`/`OFF` | Don't create a SDL install target | +| `-DSDL_DISABLE_INSTALL_DOCS=` | `ON`/`OFF` | Don't install the SDL documentation | +| `-DSDL_INSTALL_TESTS=` | `ON`/`OFF` | Install the SDL test programs | + +### Incompatibilities + +#### `SDL_LIBC=OFF` and sanitizers + +Building with `-DSDL_LIBC=OFF` will make it impossible to use the sanitizer, such as the address sanitizer. +Configure your project with `-DSDL_LIBC=ON` to make use of sanitizers. + +## CMake FAQ + +### CMake fails to build without X11 or Wayland support + +Install the required system packages prior to running CMake. +See [README-linux](linux#build-dependencies) for the list of dependencies on Linux. +Other unix operationg systems should provide similar packages. + +If you **really** don't need to show windows, add `-DSDL_UNIX_CONSOLE_BUILD=ON` to the CMake configure command. + +### How do I copy a SDL3 dynamic library to another location? + +Use [CMake generator expressions](https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html#target-dependent-expressions). +Generator expressions support multiple configurations, and are evaluated during build system generation time. + +On Windows, the following example copies `SDL3.dll` to the directory where `mygame.exe` is built. +```cmake +if(WIN32) + add_custom_command( + TARGET mygame POST_BUILD + COMMAND "${CMAKE_COMMAND}" -E copy $ $ + VERBATIM + ) +endif() +``` +On Unix systems, `$` will refer to the dynamic library (or framework), +and you might need to use `$` instead. + +Most often, you can avoid copying libraries by configuring your project with absolute [`CMAKE_LIBRARY_OUTPUT_DIRECTORY`](https://cmake.org/cmake/help/latest/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.html) +and [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`](https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html) paths. +When using a multi-config generator (such as Visual Studio or Ninja Multi-Config), eventually add `/$` to both paths. + +### Linking against a static SDL library fails due to relocation errors + +On unix platforms, all code that ends up in shared libraries needs to be built as relocatable (=position independent) code. +However, by default CMake builds static libraries as non-relocatable. +Configuring SDL with `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` will result in a static `libSDL3.a` library +which you can link against to create a shared library. + diff --git a/src/contrib/SDL-3.2.20/docs/README-contributing.md b/src/contrib/SDL-3.2.20/docs/README-contributing.md new file mode 100644 index 0000000..02a37bf --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/README-contributing.md @@ -0,0 +1,107 @@ +# Contributing to SDL + +We appreciate your interest in contributing to SDL, this document will describe how to report bugs, contribute code or ideas or edit documentation. + +**Table Of Contents** + +- [Filing a GitHub issue](#filing-a-github-issue) + - [Reporting a bug](#reporting-a-bug) + - [Suggesting enhancements](#suggesting-enhancements) +- [Contributing code](#contributing-code) + - [Forking the project](#forking-the-project) + - [Following the style guide](#following-the-style-guide) + - [Running the tests](#running-the-tests) + - [Opening a pull request](#opening-a-pull-request) + - [Continuous integration](#continuous-integration) +- [Contributing to the documentation](#contributing-to-the-documentation) + - [Editing a function documentation](#editing-a-function-documentation) + - [Editing the wiki](#editing-the-wiki) + +## Filing a GitHub issue + +### Reporting a bug + +If you think you have found a bug and would like to report it, here are the steps you should take: + +- Before opening a new issue, ensure your bug has not already been reported on the [GitHub Issues page](https://github.com/libsdl-org/SDL/issues). +- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new). +- Include details about your environment, such as your Operating System and SDL version. +- If possible, provide a small example that reproduces your bug. + +### Suggesting enhancements + +If you want to suggest changes for the project, here are the steps you should take: + +- Check if the suggestion has already been made on: + - the [issue tracker](https://github.com/libsdl-org/SDL/issues); + - the [discourse forum](https://discourse.libsdl.org/); + - or if a [pull request](https://github.com/libsdl-org/SDL/pulls) already exists. +- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new). +- Describe what change you would like to happen. + +## Contributing code + +This section will cover how the process of forking the project, making a change and opening a pull request. + +### Forking the project + +The first step consists in making a fork of the project, this is only necessary for the first contribution. + +Head over to https://github.com/libsdl-org/SDL and click on the `Fork` button in the top right corner of your screen, you may leave the fields unchanged and click `Create Fork`. + +You will be redirected to your fork of the repository, click the green `Code` button and copy the git clone link. + +If you had already forked the repository, you may update it from the web page using the `Fetch upstream` button. + +### Following the style guide + +Code formatting is done using a custom `.clang-format` file, you can learn more about how to run it [here](https://clang.llvm.org/docs/ClangFormat.html). + +Some legacy code may not be formatted, so please avoid formatting the whole file at once and only format around your changes. + +For your commit message to be properly displayed on GitHub, it should contain: + +- A short description of the commit of 50 characters or less on the first line. +- If necessary, add a blank line followed by a long description, each line should be 72 characters or less. + +For example: + +``` +Fix crash in SDL_FooBar. + +This addresses the issue #123456 by making sure Foo was successful +before calling Bar. +``` + +### Running the tests + +Tests allow you to verify if your changes did not break any behaviour, here are the steps to follow: + +- Before pushing, run the `testautomation` suite on your machine, there should be no more failing tests after your change than before. +- After pushing to your fork, Continuous Integration (GitHub Actions) will ensure compilation and tests still pass on other systems. + +### Opening a pull request + +- Head over to your fork's GitHub page. +- Click on the `Contribute` button and `Open Pull Request`. +- Fill out the pull request template. +- If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request. + +### Continuous integration + +For each push and/or pull request, GitHub Actions will try to build SDL and the test suite on most supported platforms. + +Its behaviour can be influenced slightly by including SDL-specific tags in your commit message: +- `[sdl-ci-filter GLOB]` limits the platforms for which to run ci. +- `[sdl-ci-artifacts]` forces SDL artifacts, which can then be downloaded from the summary page. +- `[sdl-ci-trackmem-symbol-names]` makes sure the final report generated by `--trackmem` contains symbol names. + +## Contributing to the documentation + +### Editing a function documentation + +The wiki documentation for API functions is synchronised from the headers' doxygen comments. As such, all modifications to syntax; function parameters; return value; version; related functions should be done in the header directly. + +### Editing the wiki + +Other changes to the wiki should done directly from https://wiki.libsdl.org/ ... Just click the "edit" link at the bottom of any page! diff --git a/src/contrib/SDL-3.2.20/docs/README-documentation-rules.md b/src/contrib/SDL-3.2.20/docs/README-documentation-rules.md new file mode 100644 index 0000000..3151de7 --- /dev/null +++ b/src/contrib/SDL-3.2.20/docs/README-documentation-rules.md @@ -0,0 +1,410 @@ +# Rules for documentation + +These are the rules for the care and feeding of wikiheaders.pl. + + +## No style guide + +When adding or editing documentation, we don't (currently) have a style guide +for what it should read like, so try to make it consistent with the rest of +the existing text. It generally should read more like technical reference +manuals and not sound conversational in tone. + +Most of these rules are about how to make sure the documentation works on +a _technical_ level, as scripts need to parse it, and there are a few simple +rules we need to obey to cooperate with those scripts. + +## The wiki and headers share the same text. + +There is a massive Perl script (`build-scripts/wikiheaders.pl`, hereafter +referred to as "wikiheaders") that can read both the wiki and the public +headers, and move changes in one across to the other. + +If you prefer to use the wiki, go ahead and edit there. If you prefer to use +your own text editor, or command line tools to batch-process text, etc, you +can [clone the wiki as a git repo](https://github.com/libsdl-org/sdlwiki) and +work locally. + + +## Don't taunt wikiheaders. + +The script isn't magic; it's a massive pile of Regular Expressions and not +a full C or markdown parser. While it isn't _fragile_, if you try to do clever +things, you might confuse it. This is to the benefit of documentation, though, +where we would rather you not do surprising things. + + +## We _sort of_ write in Doxygen format. + +To document a symbol, we use something that looks like Doxygen (and Javadoc) +standard comment format: + +```c +/** + * This is a function that does something. + * + * It can be used for frozzling bobbles. Be aware that the Frozulator module + * _must_ be initialized before calling this. + * + * \param frozzlevel The amount of frozzling to perform. + * \param color What color bobble to frozzle. 0 is red, 1 is green. + * \returns the number of bobbles that were actually frozzled, -1 on error. + * + * \threadsafety Do not call this from two threads at once, or the bobbles + * won't all frozzle correctly! + * + * \since This function is available since SDL 7.3.1. + * + * \sa SDL_DoSomethingElse + */ +extern SDL_DECLSPEC int SDLCALL SDL_DoSomething(int frozzlevel, int color); +``` + +Note the `/**` at the start of the comment. That's a "Doxygen-style" comment, +and wikiheaders will treat this differently than a comment with one `*`, as +this signifies that this is not just a comment, but _documentation_. + +These comments _must_ start in the first column of the line, or wikiheaders +will ignore them, even with the "/**" start (we should improve the script +someday to handle this, but currently this is a requirement). + +We do _not_ parse every magic Doxygen tag, and we don't parse them in `@param` +format. The goal here was to mostly coexist with people that might want +to run Doxygen on the SDL headers, not to build Doxygen from scratch. That +being said, compatibility with Doxygen is not a hard requirement here. + +wikiheaders uses these specific tags to turn this comment into a (hopefully) +well-formatted wiki page, and also can generate manpages and books in LaTeX +format from it! + +Text markup in the headers is _always_ done in Markdown format! But less is +more: try not to markup text more than necessary. + + +## Doxygen tags we support: + +- `\brief one-line description` (Not required, and wikiheaders will remove tag). +- `\param varname description` (One for each function/macro parameter) +- `\returns description` (One for each function, don't use on `void` returns). +- `\sa` (each of these get tucked into a "See Also" section on the wiki) +- `\since This function is available since SDL 3.0.0.` (one per Doxygen comment) +- `\threadsafety description` (one per function/macro). +- `\deprecated description` (one per symbol, if symbol is deprecated!) + +Other Doxygen things might exist in the headers, but they aren't understood +by wikiheaders. + + +## Use Markdown. + +The wiki also supports MediaWiki format, but we are transitioning away from it. +The headers always use Markdown. If you're editing the wiki from a git clone, +just make .md files and the wiki will know what to do with them. + + +## Most things in the headers can be documented. + +wikiheaders understands functions, typedefs, structs/unions/enums, `#defines` +... basically most of what makes up a C header. Just slap a Doxygen-style +comment in front of most things and it'll work. + + +## Defines right below typedefs and functions bind. + +Any `#define` directly below a function or non-struct/union/enum typedef is +considered part of that declaration. This happens to work well with how our +headers work, as these defines tend to be bitflags and such that are related +to that symbol. + +wikiheaders will include those defines in the syntax section of the wiki +page, and generate stub pages for each define that simply says "please refer +to (The Actual Symbol You Care About)" with a link. It will also pull in +any blank lines and most preprocessor directives for the syntax text, too. + +Sometimes an unrelated define, by itself, just happens to be right below one +of these symbols in the header. The easiest way to deal with this is either +to document that define with a Doxygen-style comment, if it makes sense to do +so, or just add a normal C comment right above it if not, so wikiheaders +doesn't bind it to the previous symbol. + + +## Don't document the `SDL_test*.h` headers. + +These are in the public headers but they aren't really considered public APIs. +They live in a separate library that doesn't, or at least probably shouldn't, +ship to end users. As such, we don't want it documented on the wiki. + +For now, we do this by not having any Doxygen-style comments in these files. +Please keep it that way! If you want to document these headers, just don't +use the magic two-`*` comment. + + +## The first line is the summary. + +The first line of a piece of documentation is meant to be a succinct +description. This is what Doxygen would call the `\brief` tag. wikiheaders +will split this text out until the first period (end of sentence!), and when +word wrapping, shuffle the overflow into a new paragraph below it. + + +## Split paragraphs with a blank line. + +And don't indent them at all (indenting in Markdown is treated as preformatted +text). + +wikiheaders will wordwrap header comments so they fit in 80 columns, so if you +don't leave a blank line between paragraphs, they will smush into a single +block of text when wordwrapping. + + +## Don't worry about word wrapping. + +If you don't word-wrap your header edits perfectly (and you won't, I promise), +wikiheaders will send your change to the wiki, and then to make things match, +send it right back to the headers with correct word wrapping. Since this +happens right after you push your changes, you might as well just write +however you like and assume the system will clean it up for you. + + +## Things that start with `SDL_` will automatically become wiki links. + +wikiheaders knows to turn these into links to other pages, so if you reference +an SDL symbol in the header documentation, you don't need to link to it. +You can optionally wrap the symbol in backticks, and wikiheaders will know to +link the backticked thing. It will not generate links in three-backtick +code/preformatted blocks. + + +## URLs will automatically become links. + +You can use Markdown's `[link markup format](https://example.com/)`, but +sometimes it's clearer to list bare URLs; the URL will be visible on the +wiki page, but also clickable to follow the link. This is up to your judgment +on a case-by-case basis. + + +## Hide stuff from wikiheaders. + +If all else fails, you can block off pieces of the header with this +magic line (whitespace is ignored): + +```c +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +``` + +Everything between this line and the next `#endif` will just be skipped by +wikiheaders. Note that wikiheaders is not a C preprocessor! Don't try to +nest conditionals or use `!defined`. + +Just block off sections if you need to. And: you almost never need to. + + +## Hide stuff from the compiler. + +If you need to put something that's only of interest to wikiheaders, the +convention is to put it in a block like this: + +```c +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +``` + +Generally this is used when there's a collection of preprocessor conditionals +to define the same symbol differently in different circumstances. You put +that symbol in this block with some reasonable generic version _and the +Doxygen-style comment_. Because wikiheaders doesn't care about this +preprocessor magic, and the C compiler can be as fancy as it wants, this is +strictly a useful convention. + + +## Struct/union/enum typedefs must have the name on the first line. + +This is because wikiheaders is not a full C parser. Don't write this: + +```c +typedef struct +{ + int a; + int b; +} SDL_MyStruct; +``` + +...make sure the name is at the start, too: + +```c +typedef struct SDL_MyStruct +{ + int a; + int b; +} SDL_MyStruct; +``` + +wikiheaders will complain loudly if you don't do this, and exit with an +error message. + + +## Don't repeat type names in `\param` and `\returns` sections. + +Wikiheaders will explicitly mention the datatype for each parameter and the +return value, linking to the datatype's wikipage. Users reading the headers +can see the types in the function signature right below the documentation +comment. So don't mention the type a second time in the documentation if +possible. It looks cluttered and repetitive to do so. + + +## Code examples go in the wiki. + +We don't want the headers cluttered up with code examples. These live on the +wiki pages, and wikiheaders knows to not bridge them back to the headers. + +Put them in a `## Code Examples` section, and make sure to wrap them in a +three-backtick-c section for formatting purposes. Only write code in C, +please. + + +## Do you _need_ a code example? + +Most code examples aren't actually useful. If your code example is just +`SDL_CreateWindow("Hello SDL", 640, 480, 0);` then just delete it; if all +you're showing is how to call a function in C, it's not a useful code example. +Not all functions need an example. One with complex setup or usage details +might, though! + + +## Code examples are compiled by GitHub Actions. + +On each change to the wiki, there is a script that pulls out all the code +examples into discrete C files and attempts to compile them, and complains +if they don't work. + + +## Unrecognized sections are left alone in the wiki. + +A wiki section that starts with `## Section Name` (or `== Section Name ==` in +MediaWiki format) that isn't one of the recognized names will be left alone +by wikiheaders. Recognized sections might get overwritten with new content +from the headers, but the wiki file will not have other sections cleaned out +(this is how Code Examples remain wiki only, for example). You can use this +to add Wiki-specific text, or stuff that doesn't make sense in a header, or +would merely clutter it up. + +A possibly-incomplete list of sections that will be overwritten by changes +to the headers: + +- The page title line, and the "brief" one-sentence description section. +- "Deprecated" +- "Header File" +- "Syntax" +- "Function Parameters" +- "Macro Parameters" +- "Fields" +- "Values" +- "Return Value" +- "Remarks" +- "Thread Safety" +- "Version" +- "See Also" + + +## It's okay to repeat yourself. + +Each individual piece of documentation becomes a separate page on the wiki, so +small repeated details can just exist in different pieces of documentation. If +it's complicated, it's not unreasonable to say "Please refer to +SDL_SomeOtherFunction for more details" ... wiki users can click right +through, header users can search for the function name. + + +## The docs directory is bridged to the wiki, too. + +You might be reading this document on the wiki! Any `README-*.md` files in +the docs directory are bridged to the wiki, so `docs/README-linux.md` lands +at https://wiki.libsdl.org/SDL3/README/linux ...these are just copied directly +without any further processing by wikiheaders, and changes go in both +directions. + + +## The wiki can have its own pages, too. + +If a page name isn't a symbol that wikiheaders sees in the headers, or a +README in the source's `docs` directory, or a few other exceptions, it'll +assume it's an unrelated wiki page and leave it alone. So feel free to +write any wiki-only pages that make sense and not worry about it junking +up the headers! + + +## Wiki categories are (mostly) managed automatically. + +The wiki will see this pattern as the last thing on a page and treat it as a +list of categories that page belongs to: + +``` +---- +[CategoryStuff](CategoryStuff), [CategoryWhatever](CategoryWhatever) +``` + +You can use this to simply tag a page as part of a category, and the user can +click directly to see other pages in that category. The wiki will +automatically manage a `Category*` pages that list any tagged pages. + +You _should not_ add tags to the public headers. They don't mean anything +there. wikiheaders will add a few tags that make sense when generating wiki +content from the header files, and it will preserve other tags already present +on the page, so if you want to add extra categories to something, tag it on +the wiki itself. + +The wiki uses some magic HTML comment tags to decide how to list items on +Category pages and let other content live on the page as well. You can +see an example of this in action at: + +https://raw.githubusercontent.com/libsdl-org/sdlwiki/main/SDL3/CategoryEvents.md + + +## Categorizing the headers. + +To put a symbol in a specific category, we use three approaches in SDL: + +- Things in the `SDL_test*.h` headers aren't categorized at all (and you + shouldn't document them!) +- Most files are categorized by header name: we strip off the leading `SDL_` + and capitalize the first letter of what's left. So everything in SDL_audio.h + is in the "Audio" category, everything in SDL_video.h is in the "Video" + category, etc. +- If wikiheaders sees a comment like this on a line by itself... + ```c + /* WIKI CATEGORY: Blah */ + ``` + ...then all symbols below that will land in the "Blah" category. We use this + at the top of a few headers where the simple + chop-off-SDL_-and-captialize-the-first-letter trick doesn't work well, but + one could theoretically use this for headers that have some overlap in + category. + + +## Category documentation lives in headers. + +To document a category (text that lives before the item lists on a wiki +category page), you have to follow a simple rule: + +The _first_ Doxygen-style comment in a header must start with: + +``` +/** + * # CategoryABC +``` + +If these conditions aren't met, wikiheaders will assume that documentation +belongs to whatever is below it instead of the Category. + +The text of this comment will be added to the appropriate wiki Category page, +at the top, replacing everything in the file until it sees a line that starts +with an HTML comment (`