docs: expand CMake documentation + add minimal CMake project for reporting issues

docs/README-cmake.md

@@ -1,6 +1,6 @@
 # CMake
 
-(www.cmake.org)
+[www.cmake.org](https://www.cmake.org/)
 
 The CMake build system is supported on the following platforms:
 
@@ -11,23 +11,24 @@ The CMake build system is supported on the following platforms:
 * macOS, iOS, and tvOS, with support for XCode
 * Android
 * Emscripten
-* RiscOS
+* FreeBSD
+* Haiku
+* Nintendo 3DS
 * Playstation 2
 * Playstation Vita
-* Nintendo 3DS
 * QNX 7.x/8.x
+* RiscOS
 
 ## Building SDL
 
-Assuming the source for SDL is located at `~/sdl`.
+Assuming the source tree of SDL is located at `~/sdl`,
+this will configure and build SDL in the `~/build` directory:
 ```sh
 cmake -S ~/sdl -B ~/build
 cmake --build ~/build
 ```
 
-This will build SDL in the `~/build` directory.
 Installation can be done using:
-
 ```sh
 cmake --install ~/build --prefix /usr/local        # '--install' requires CMake 3.15, or newer
 ```
@@ -43,23 +44,26 @@ SDL can be included in your project in 2 major ways:
 The following CMake script supports both, depending on the value of `MYGAME_VENDORED`.
 
 ```cmake
-cmake_minimum_required(VERSION 3.0)
+cmake_minimum_required(VERSION 3.5)
 project(mygame)
 
-# Create an option to switch between a system sdl library and a vendored sdl library
+# 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)
-    add_subdirectory(vendored/sdl EXCLUDE_FROM_ALL)
+    # 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 component and 3. fail if none can be found
+    # 1. Look for a SDL3 package,
-    find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)
+    # 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. SDL3::SDL3 is the shared SDL library, SDL3::SDL3-static is the static SDL libarary.
+# Link to the actual SDL3 library.  
 target_link_libraries(mygame PRIVATE SDL3::SDL3)
 ```
 
@@ -80,7 +84,9 @@ The following components are available, to be used as an argument of `find_packa
 
 ### Using a vendored SDL
 
-This only requires a copy of SDL in a subdirectory.
+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
 
@@ -97,6 +103,11 @@ To build it, run:
 cmake --build . --config Release
 ```
 
+### Shared or static
+
+By default, only a shared SDL library is built and installed.
+The options `-DSDL_SHARED=` and `-DSDL_STATIC=` accept boolean values to change this.
+
 ### 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
@@ -185,3 +196,109 @@ To use, set the following CMake variables when running CMake's configuration sta
     ```cmake
     cmake ~/sdl -DCMAKE_TOOLCHAIN_FILE=~/sdl/build-scripts/cmake-toolchain-qnx-aarch64le.cmake -DSDL_X11=0
     ```
+
+## Help, it doesn't work!
+
+Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).
+When you have a problem with building or using SDL, please modify it until it reproduces your issue.
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(sdl_issue)
+
+# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+# !!!!!!                                                                            !!!!!!
+# !!!!!!     This CMake script is not using "CMake best practices".                 !!!!!!
+# !!!!!!                 Don't use it in your project.                              !!!!!!
+# !!!!!!                                                                            !!!!!!
+# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+# 1. Try system SDL3 package first
+find_package(SDL3 QUIET)
+if(SDL3_FOUND)
+    message(STATUS "Using SDL3 via find_package")
+endif()
+
+# 2. Try using a vendored SDL library
+if(NOT SDL3_FOUND AND EXISTS "${CMAKE_CURRENT_LIST_DIR}/SDL/CMakeLists.txt")
+    add_subdirectory(SDL)
+    message(STATUS "Using SDL3 via add_subdirectory")
+    set(SDL3_FOUND TRUE)
+endif()
+
+# 3. Download SDL, and use that.
+if(NOT SDL3_FOUND)
+    include(FetchContent)
+    set(SDL_SHARED TRUE CACHE BOOL "Build a SDL shared library (if available)")
+    set(SDL_STATIC TRUE CACHE BOOL "Build a SDL static library (if available)")
+    FetchContent_Declare(
+        SDL
+        GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
+        GIT_TAG main  # Replace this with a particular git tag or git hash
+        GIT_SHALLOW TRUE
+        GIT_PROGRESS TRUE
+    )
+    message(STATUS "Using SDL3 via FetchContent")
+    FetchContent_MakeAvailable(SDL)
+    set_property(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/_deps/sdl-src" PROPERTY EXCLUDE_FROM_ALL TRUE)
+endif()
+
+file(WRITE main.c [===========================================[
+/**
+ * Modify this source such that it reproduces your problem.
+ */
+
+/* START of source modifications */
+
+#include <SDL3/SDL.h>
+
+int main(int argc, char *argv[]) {
+    if (SDL_Init(SDL_INIT_EVERYTHING) < 0) {
+        SDL_Log("SDL_Init failed (%s)", SDL_GetError());
+        return 1;
+    }
+
+    SDL_Window *window = NULL;
+    SDL_Renderer *renderer = NULL;
+
+    if (SDL_CreateWindowAndRenderer(640, 480, 0, &window, &renderer) < 0) {
+        SDL_Log("SDL_CreateWindowAndRenderer failed (%s)", SDL_GetError());
+        SDL_Quit();
+        return 1;
+    }
+    SDL_SetWindowTitle(window, "SDL issue");
+
+    while (1) {
+        int finished = 0;
+        SDL_Event event;
+        while (SDL_PollEvent(&event)) {
+            if (event.type == SDL_EVENT_QUIT) {
+                finished = 1;
+                break;
+            }
+        }
+        if (finished) {
+            break;
+        }
+    
+        SDL_SetRenderDrawColor(renderer, 80, 80, 80, SDL_ALPHA_OPAQUE);
+        SDL_RenderClear(renderer);
+        SDL_RenderPresent(renderer);
+    }
+
+    SDL_DestroyRenderer(renderer);
+    SDL_DestroyWindow(window);
+
+    SDL_Quit();
+}
+
+/* END of source modifications */
+
+]===========================================])
+
+add_executable(sdl_issue main.c)
+
+target_link_libraries(sdl_issue PRIVATE SDL3::SDL3)
+# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-shared)
+# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-static)
+```