update SDL3 to latest commit

libs/SDL3/docs/README-cmake.md

@@ -44,6 +44,14 @@ cmake -S ~/sdl -B ~/build -DSDL_TEST_LIBRARY=ON -DSDL_TESTS=ON
 ```
 and then building normally. In this example, the test programs will be built and can be run from `~/build/tests/`.
 
+### Building SDL examples
+
+You can build the SDL example programs by adding `-DSDL_EXAMPLES=ON` to the first cmake command above:
+```sh
+cmake -S ~/sdl -B ~/build -DSDL_EXAMPLES=ON
+```
+and then building normally. In this example, 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:
@@ -90,6 +98,8 @@ The following components are available, to be used as an argument of `find_packa
 | 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
 
@@ -114,9 +124,13 @@ cmake --build . --config Release
 
 ### Shared or static
 
-By default, only a shared SDL library is built and installed.
+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
+
 ### Pass custom compile options to the compiler
 
 - Use [`CMAKE_<LANG>_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html) to pass extra
@@ -283,6 +297,32 @@ At the end of SDL CMake configuration, a table shows all CMake options along wit
 | `-DSDL_DISABLE_INSTALL_DOCS=` | `ON`/`OFF`   | Don't install the SDL documentation                                                                 |
 | `-DSDL_INSTALL_TESTS=`        | `ON`/`OFF`   | Install the SDL test programs                                                                       |
 
+## CMake FAQ
+
+### 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 this copies `SDL3.dll` to the directory where `mygame.exe` is built.
+On Unix systems, `$<TARGET_FILE:...>` will refer to the dynamic library (or framework).
+```cmake
+if(WIN32)
+    add_custom_command(
+        TARGET mygame POST_BUILD
+        COMMAND "${CMAKE_COMMAND}" -E copy $<TARGET_FILE:SDL3::SDL3-shared> $<TARGET_FILE_DIR:mygame>
+        VERBATIM
+    )
+endif()
+```
+
+### 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.
+
 ## Help, it doesn't work!
 
 Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).
@@ -307,7 +347,7 @@ endif()
 
 # 2. Try using a vendored SDL library
 if(NOT SDL3_FOUND AND EXISTS "${CMAKE_CURRENT_LIST_DIR}/SDL/CMakeLists.txt")
-    add_subdirectory(SDL)
+    add_subdirectory(SDL EXCLUDE_FROM_ALL)
     message(STATUS "Using SDL3 via add_subdirectory")
     set(SDL3_FOUND TRUE)
 endif()
@@ -345,7 +385,7 @@ int main(int argc, char *argv[]) {
     (void)argc;
     (void)argv;
 
-    if (SDL_Init(SDL_INIT_VIDEO) < 0) {
+    if (!SDL_Init(SDL_INIT_VIDEO)) {
         SDL_Log("SDL_Init failed (%s)", SDL_GetError());
         return 1;
     }
@@ -353,12 +393,11 @@ int main(int argc, char *argv[]) {
     SDL_Window *window = NULL;
     SDL_Renderer *renderer = NULL;
 
-    if (SDL_CreateWindowAndRenderer(640, 480, 0, &window, &renderer) < 0) {
+    if (!SDL_CreateWindowAndRenderer("SDL issue", 640, 480, 0, &window, &renderer)) {
         SDL_Log("SDL_CreateWindowAndRenderer failed (%s)", SDL_GetError());
         SDL_Quit();
         return 1;
     }
-    SDL_SetWindowTitle(window, "SDL issue");
 
     while (1) {
         int finished = 0;