From a4371d28ac97206716f12d4911cdf5a8f547a8a6 Mon Sep 17 00:00:00 2001 From: Anonymous Maarten 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 b88601b81..2b96eb2e4 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__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, `$` will refer to the dynamic library (or framework). +```cmake +if(WIN32) + add_custom_command( + TARGET mygame POST_BUILD + COMMAND "${CMAKE_COMMAND}" -E copy $ $ + 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 ee56c09fe..736575b6e 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](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: