SDL: doc: document how to use generator expressions + explain why we no longer provide CMake variables

From a4371d28ac97206716f12d4911cdf5a8f547a8a6 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Sun, 5 May 2024 20:46:49 +0200
Subject: [PATCH] doc: document how to use generator expressions + explain why
 we no longer provide CMake variables

---
 docs/README-cmake.md     | 25 ++++++++++++++++++++++++-
 docs/README-migration.md | 10 ++++++----
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/docs/README-cmake.md b/docs/README-cmake.md
index b88601b816cd3..2b96eb2e4a658 100644
--- a/docs/README-cmake.md
+++ b/docs/README-cmake.md
@@ -114,9 +114,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 +287,25 @@ 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()
+```
+
 ## Help, it doesn't work!
 
 Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).
diff --git a/docs/README-migration.md b/docs/README-migration.md
index ee56c09fe94ce..736575b6e2efd 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -25,19 +25,19 @@ rename_macros.py source_code_path
 
 
 CMake users should use this snippet to include SDL support in their project:
-```
+```cmake
 find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)
 target_link_libraries(mygame PRIVATE SDL3::SDL3)

Autotools users should use this snippet to include SDL support in their project:
- +m4
PKG_CHECK_MODULES([SDL3], [sdl3])

-and then add $SDL3_CFLAGS to their project CFLAGS and $SDL3_LIBS to their project LDFLAGS
+and then add `$SDL3_CFLAGS` to their project `CFLAGS` and `$SDL3_LIBS` to their project `LDFLAGS`.

Makefile users can use this snippet to include SDL support in their project:
-```
+```make
CFLAGS += $(shell pkg-config sdl3 --cflags)
LDFLAGS += $(shell pkg-config sdl3 --libs)

@@ -48,6 +48,8 @@ The SDLmain library has been removed, it’s been entirely replaced by SDL_main.h.

The vi format comments have been removed from source code. Vim users can use the editorconfig plugin to automatically set tab spacing for the SDL coding style.

+Installed SDL CMake configuration files no longer define SDL3_PREFIX, SDL3_EXEC_PREFIX, SDL3_INCLUDE_DIR, SDL3_INCLUDE_DIRS, SDL3_BINDIR or SDL3_LIBDIR. Users are expected to use CMake generator expressions with SDL3::SDL3, SDL3::SDL3-shared, SDL3::SDL3-static or SDL3::Headers. By no longer defining these CMake variables, using a system SDL3 or using a vendoring SDL3 behave in the same way.
+

SDL_atomic.h

The following structures have been renamed: