FindSDL: Add SDL_INCLUDE_DIRS, SDL_LIBRARIES, and SDL::SDL

Also provide `SDL_VERSION[_{MAJOR,MINOR,PATCH}]`.

Fixes: #12911

Help/release/dev/FindSDL-update.rst

@@ -0,0 +1,11 @@
+FindSDL-update
+--------------
+
+* The :module:`FindSDL` module now provides:
+
+  * imported target ``SDL::SDL``,
+
+  * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
+
+  * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
+    ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.

Modules/FindSDL.cmake

@@ -5,24 +5,54 @@
 FindSDL
 -------
 
-Locate SDL library
+Locate the SDL library
 
-This module defines
 
-::
+Imported targets
+^^^^^^^^^^^^^^^^
 
-  SDL_LIBRARY, the name of the library to link against
-  SDL_FOUND, if false, do not try to link to SDL
-  SDL_INCLUDE_DIR, where to find SDL.h
-  SDL_VERSION_STRING, human-readable string containing the version of SDL
+This module defines the following :prop_tgt:`IMPORTED` target:
 
+``SDL::SDL``
+  The SDL library, if found
 
+Result variables
+^^^^^^^^^^^^^^^^
 
-This module responds to the flag:
+This module will set the following variables in your project:
+
+``SDL_INCLUDE_DIRS``
+  where to find SDL.h
+``SDL_LIBRARIES``
+  the name of the library to link against
+``SDL_FOUND``
+  if false, do not try to link to SDL
+``SDL_VERSION``
+  the human-readable string containing the version of SDL if found
+``SDL_VERSION_MAJOR``
+  SDL major version
+``SDL_VERSION_MINOR``
+  SDL minor version
+``SDL_VERSION_PATCH``
+  SDL patch version
+
+Cache variables
+^^^^^^^^^^^^^^^
+
+These variables may optionally be set to help this module find the correct files:
 
-::
+``SDL_INCLUDE_DIR``
+  where to find SDL.h
+``SDL_LIBRARY``
+  the name of the library to link against
+
+
+Variables for locating SDL
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This module responds to the flag:
 
-  SDL_BUILDING_LIBRARY
+``SDL_BUILDING_LIBRARY``
     If this is defined, then no SDL_main will be linked in because
     only applications need main().
     Otherwise, it is assumed you are building an application and this
@@ -30,6 +60,15 @@ This module responds to the flag:
     as part of the returned SDL_LIBRARY variable.
 
 
+Obsolete variables
+^^^^^^^^^^^^^^^^^^
+
+These variables are obsolete and provided for backwards compatibility:
+
+``SDL_VERSION_STRING``
+  the human-readable string containing the version of SDL if found.
+  Identical to SDL_VERSION
+
 
 Don't forget to include SDLmain.h and SDLmain.m your project for the
 OS X framework based version.  (Other versions link to -lSDLmain which
@@ -52,15 +91,6 @@ does not get created.
 $SDLDIR is an environment variable that would correspond to the
 ./configure --prefix=$SDLDIR used in building SDL.  l.e.galup 9-20-02
 
-Modified by Eric Wing.  Added code to assist with automated building
-by using environmental variables and providing a more
-controlled/consistent search behavior.  Added new modifications to
-recognize OS X frameworks and additional Unix paths (FreeBSD, etc).
-Also corrected the header search path to follow "proper" SDL
-guidelines.  Added a search for SDLmain which is needed by some
-platforms.  Added a search for threads which is needed by some
-platforms.  Added needed compile switches for MinGW.
-
 On OSX, this will prefer the Framework version (if found) over others.
 People will have to manually change the cache values of SDL_LIBRARY to
 override this selection or set the CMake environment
@@ -174,13 +204,11 @@ if(SDL_INCLUDE_DIR AND EXISTS "${SDL_INCLUDE_DIR}/SDL_version.h")
   string(REGEX REPLACE "^#define[ \t]+SDL_MAJOR_VERSION[ \t]+([0-9]+)$" "\\1" SDL_VERSION_MAJOR "${SDL_VERSION_MAJOR_LINE}")
   string(REGEX REPLACE "^#define[ \t]+SDL_MINOR_VERSION[ \t]+([0-9]+)$" "\\1" SDL_VERSION_MINOR "${SDL_VERSION_MINOR_LINE}")
   string(REGEX REPLACE "^#define[ \t]+SDL_PATCHLEVEL[ \t]+([0-9]+)$" "\\1" SDL_VERSION_PATCH "${SDL_VERSION_PATCH_LINE}")
-  set(SDL_VERSION_STRING ${SDL_VERSION_MAJOR}.${SDL_VERSION_MINOR}.${SDL_VERSION_PATCH})
   unset(SDL_VERSION_MAJOR_LINE)
   unset(SDL_VERSION_MINOR_LINE)
   unset(SDL_VERSION_PATCH_LINE)
-  unset(SDL_VERSION_MAJOR)
-  unset(SDL_VERSION_MINOR)
-  unset(SDL_VERSION_PATCH)
+  set(SDL_VERSION ${SDL_VERSION_MAJOR}.${SDL_VERSION_MINOR}.${SDL_VERSION_PATCH})
+  set(SDL_VERSION_STRING ${SDL_VERSION})
 endif()
 
 include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)
@@ -188,3 +216,14 @@ include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)
 FIND_PACKAGE_HANDLE_STANDARD_ARGS(SDL
                                   REQUIRED_VARS SDL_LIBRARY SDL_INCLUDE_DIR
                                   VERSION_VAR SDL_VERSION_STRING)
+
+if(SDL_FOUND)
+  set(SDL_LIBRARIES ${SDL_LIBRARY})
+  set(SDL_INCLUDE_DIRS ${SDL_INCLUDE_DIR})
+  if(NOT TARGET SDL::SDL)
+    add_library(SDL::SDL INTERFACE IMPORTED)
+    set_target_properties(SDL::SDL PROPERTIES
+      INTERFACE_INCLUDE_DIRECTORIES "${SDL_INCLUDE_DIR}"
+      INTERFACE_LINK_LIBRARIES "${SDL_LIBRARY}")
+  endif()
+endif()

Tests/CMakeLists.txt

@@ -1452,6 +1452,7 @@ ${CMake_SOURCE_DIR}/Utilities/Release/push.bash --dir dev -- '${CMake_BUILD_NIGH
             Patch
             PostgreSQL
             Protobuf
+            SDL
             SQLite3
             TIFF
             Vulkan

Tests/FindSDL/CMakeLists.txt

@@ -0,0 +1,10 @@
+add_test(NAME FindSDL.Test COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindSDL/Test"
+  "${CMake_BINARY_DIR}/Tests/FindSDL/Test"
+  ${build_generator_args}
+  --build-project TestFindSDL
+  --build-options ${build_options}
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )

Tests/FindSDL/Test/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.1)
+project(TestFindSDL C)
+include(CTest)
+
+find_package(SDL)
+
+add_definitions(
+  -DCMAKE_EXPECTED_SDL_VERSION_MAJOR=${SDL_VERSION_MAJOR}
+  -DCMAKE_EXPECTED_SDL_VERSION_MINOR=${SDL_VERSION_MINOR}
+  -DCMAKE_EXPECTED_SDL_VERSION_PATCH=${SDL_VERSION_PATCH})
+
+add_executable(test_sdl_tgt main.c)
+target_link_libraries(test_sdl_tgt SDL::SDL)
+add_test(NAME test_sdl_tgt COMMAND test_sdl_tgt)
+
+add_executable(test_sdl_var main.c)
+target_include_directories(test_sdl_var PRIVATE ${SDL_INCLUDE_DIRS})
+target_link_libraries(test_sdl_var PRIVATE ${SDL_LIBRARIES})
+add_test(NAME test_sdl_var COMMAND test_sdl_var)

Tests/FindSDL/Test/main.c

@@ -0,0 +1,18 @@
+#include <SDL.h>
+
+int main()
+{
+  // Test 1 requires headers only.
+  SDL_version compiled;
+  SDL_VERSION(&compiled);
+  if (compiled.major != CMAKE_EXPECTED_SDL_VERSION_MAJOR ||
+      compiled.minor != CMAKE_EXPECTED_SDL_VERSION_MINOR ||
+      compiled.patch != CMAKE_EXPECTED_SDL_VERSION_PATCH)
+    return 1;
+
+  // Test 2 requires to link to the library.
+  if (SDL_WasInit(SDL_INIT_VIDEO | SDL_INIT_AUDIO) != 0)
+    return 2;
+
+  return 0;
+}