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

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).

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](https://github.com/editorconfig/editorconfig-vim) 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](https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html#target-dependent-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: