Merge topic 'patch-FindSDL'

905d461431 Find_SDL*: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10657

Help/manual/cmake-modules.7.rst

@@ -225,8 +225,8 @@ They are normally called through the :command:`find_package` command.
    /module/FindRTI
    /module/FindRuby
    /module/FindSDL
-   /module/FindSDL_image
    /module/FindSDL_gfx
+   /module/FindSDL_image
    /module/FindSDL_mixer
    /module/FindSDL_net
    /module/FindSDL_sound

Modules/FindSDL.cmake

@@ -5,109 +5,171 @@
 FindSDL
 -------
 
-Locate the SDL library
+Finds the SDL (Simple DirectMedia Layer) library.  SDL is a cross-platform
+library for developing multimedia software, such as games and emulators.
 
+.. note::
+
+  This module is specifically intended for SDL version 1.  Starting with version
+  2, SDL provides a CMake package configuration file when built with CMake and
+  should be found using ``find_package(SDL2)``.  Similarly, SDL version 3 can be
+  found using ``find_package(SDL3)``.  These newer versions provide separate
+  :ref:`Imported Targets` that encapsulate usage requirements.  Refer to the
+  official SDL documentation for more information.
+
+Note that the include path for the SDL header has changed in recent SDL 1
+versions from ``SDL/SDL.h`` to simply ``SDL.h``.  This change aligns with SDL's
+convention of using ``#include "SDL.h"`` for portability, as not all systems
+install the headers in a ``SDL/`` subdirectory (e.g., FreeBSD).
+
+When targeting macOS and using the SDL framework, be sure to include both
+``SDLmain.h`` and ``SDLmain.m`` in the project.  For other platforms, the
+``SDLmain`` library is typically linked using ``-lSDLmain``, which this module
+will attempt to locate automatically.  Additionally, for macOS, this module will
+add the ``-framework Cocoa`` flag as needed.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.19
-
-This module defines the following :prop_tgt:`IMPORTED` target:
+This module provides the following :ref:`Imported Targets`:
 
 ``SDL::SDL``
-  The SDL library, if found
+  .. versionadded:: 3.19
 
-Result variables
+  Target encapsulating the SDL library usage requirements, available if SDL is
+  found.
+
+Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module will set the following variables in your project:
+This module defines the following variables:
 
-``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
+  Boolean indicating whether the (requested version of) SDL is found.
+
 ``SDL_VERSION``
-  the human-readable string containing the version of SDL if found
+  .. versionadded:: 3.19
+
+  The human-readable string containing the version of SDL found.
+
 ``SDL_VERSION_MAJOR``
-  SDL major version
+  .. versionadded:: 3.19
+
+  The major version of SDL found.
+
 ``SDL_VERSION_MINOR``
-  SDL minor version
+  .. versionadded:: 3.19
+
+  The minor version of SDL found.
+
 ``SDL_VERSION_PATCH``
-  SDL patch version
+  .. versionadded:: 3.19
+
+  The patch version of SDL found.
+
+``SDL_INCLUDE_DIRS``
+  .. versionadded:: 3.19
+
+  Include directories needed to use SDL.
+
+``SDL_LIBRARIES``
+  .. versionadded:: 3.19
 
-.. versionadded:: 3.19
-  Added the ``SDL_INCLUDE_DIRS``, ``SDL_LIBRARIES`` and ``SDL_VERSION[_<PART>]``
-  variables.
+  Libraries needed to link against to use SDL.
 
-Cache variables
+Cache Variables
 ^^^^^^^^^^^^^^^
 
-These variables may optionally be set to help this module find the correct files:
+These variables may optionally be set to help this module find the correct
+files:
 
 ``SDL_INCLUDE_DIR``
-  where to find SDL.h
+  The directory containing the ``SDL.h`` header file.
 ``SDL_LIBRARY``
-  the name of the library to link against
+  A list of libraries containing the path to the SDL library and libraries
+  needed to link against to use SDL.
 
+Hints
+^^^^^
 
-Variables for locating SDL
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This module responds to the flag:
+This module accepts the following variables:
 
 ``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
-    module will attempt to locate and set the proper link flags
-    as part of the returned SDL_LIBRARY variable.
-
+  When set to boolean true, the ``SDL_main`` library will be excluded from
+  linking, as it is not required when building the SDL library itself (only
+  applications need ``main()`` function).  If not set, this module assumes an
+  application is being built and attempts to locate and include the appropriate
+  ``SDL_main`` link flags in the returned ``SDL_LIBRARY`` variable.
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+  On macOS, setting this variable will prefer the Framework version (if found)
+  over others.  In this case, the cache value of ``SDL_LIBRARY`` would need to
+  be manually changed to override this selection or set the
+  :variable:`CMAKE_INCLUDE_PATH` variable to modify the search paths.
+
+Troubleshooting
+^^^^^^^^^^^^^^^
 
-Obsolete variables
-^^^^^^^^^^^^^^^^^^
+In case the SDL library is not found automatically, the ``SDL_LIBRARY_TEMP``
+variable may be empty, and ``SDL_LIBRARY`` will not be set.  This typically
+means that CMake could not locate the SDL library (e.g., ``SDL.dll``,
+``libSDL.so``, ``SDL.framework``, etc.).  To resolve this, manually set
+``SDL_LIBRARY_TEMP`` to the correct path and reconfigure the project.
+Similarly, if ``SDLMAIN_LIBRARY`` is unset, it may also need to be specified
+manually.  These variables are used to construct the final ``SDL_LIBRARY``
+value.  If they are not set, ``SDL_LIBRARY`` will remain undefined.
 
-.. deprecated:: 3.19
+Deprecated 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
+  .. deprecated:: 3.19
+    Superseded by the ``SDL_VERSION`` with the same value.
+
+  The human-readable string containing the version of SDL if found.
+
+Examples
+^^^^^^^^
+
+Finding SDL library and linking it to a project target:
 
+.. code-block:: cmake
 
-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
-this module will try to find on your behalf.) Also for OS X, this
-module will automatically add the -framework Cocoa on your behalf.
+  find_package(SDL)
+  target_link_libraries(project_target PRIVATE SDL::SDL)
 
+When working with SDL version 2, the upstream package provides the
+``SDL2::SDL2`` imported target directly.  It can be used in a project without
+using this module:
 
+.. code-block:: cmake
 
-Additional Note: If you see an empty SDL_LIBRARY_TEMP in your
-configuration and no SDL_LIBRARY, it means CMake did not find your SDL
-library (SDL.dll, libsdl.so, SDL.framework, etc).  Set
-SDL_LIBRARY_TEMP to point to your SDL library, and configure again.
-Similarly, if you see an empty SDLMAIN_LIBRARY, you should set this
-value as appropriate.  These values are used to generate the final
-SDL_LIBRARY variable, but when these values are unset, SDL_LIBRARY
-does not get created.
+  find_package(SDL2)
+  target_link_libraries(project_target PRIVATE SDL2::SDL2)
 
+Similarly, for SDL version 3:
 
+.. code-block:: cmake
 
-$SDLDIR is an environment variable that would correspond to the
-./configure --prefix=$SDLDIR used in building SDL.  l.e.galup 9-20-02
+  find_package(SDL3)
+  target_link_libraries(project_target PRIVATE SDL3::SDL3)
 
-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
-CMAKE_INCLUDE_PATH to modify the search paths.
+See Also
+^^^^^^^^
 
-Note that the header path has changed from SDL/SDL.h to just SDL.h
-This needed to change because "proper" SDL convention is #include
-"SDL.h", not <SDL/SDL.h>.  This is done for portability reasons
-because not all systems place things in SDL/ (see FreeBSD).
+* The :module:`FindSDL_gfx` module to find the SDL_gfx library.
+* The :module:`FindSDL_image` module to find the SDL_image library.
+* The :module:`FindSDL_mixer` module to find the SDL_mixer library.
+* The :module:`FindSDL_net` module to find the SDL_net library.
+* The :module:`FindSDL_sound` module to find the SDL_sound library.
+* The :module:`FindSDL_ttf` module to find the SDL_ttf library.
 #]=======================================================================]
 
 cmake_policy(PUSH)

Modules/FindSDL_gfx.cmake

@@ -7,21 +7,70 @@ FindSDL_gfx
 
 .. versionadded:: 3.25
 
-Locate SDL_gfx library
+Finds the SDL_gfx library that provides graphics support in SDL (Simple
+DirectMedia Layer) applications.
 
-This module defines:
+.. note::
 
-::
+  This module is for SDL_gfx version 1.  For version 2 or newer usage refer to
+  the upstream documentation.
 
-  SDL::SDL_gfx, the name of the target to use with target_*() commands
-  SDL_GFX_LIBRARIES, the name of the library to link against
-  SDL_GFX_INCLUDE_DIRS, where to find the headers
-  SDL_GFX_FOUND, if false, do not try to link against
-  SDL_GFX_VERSION_STRING - human-readable string containing the
-                             version of SDL_gfx
+Imported Targets
+^^^^^^^^^^^^^^^^
 
-``$SDLDIR`` is an environment variable that would correspond to the
-``./configure --prefix=$SDLDIR`` used in building SDL.
+This module provides the following :ref:`Imported Targets`:
+
+``SDL::SDL_gfx``
+  Target encapsulating the SDL_gfx library usage requirements, available if
+  SDL_gfx is found.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``SDL_gfx_FOUND``
+  Boolean indicating whether the (requested version of) SDL_gfx library is
+  found.  For backward compatibility, the ``SDL_GFX_FOUND`` variable is also set
+  to the same value.
+``SDL_GFX_VERSION_STRING``
+  The human-readable string containing the version of SDL_gfx found.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``SDL_GFX_INCLUDE_DIRS``
+  The directory containing the headers needed to use SDL_gfx.
+``SDL_GFX_LIBRARIES``
+  The path to the SDL_gfx library needed to link against to use SDL_gfx.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+Examples
+^^^^^^^^
+
+Finding SDL_gfx library and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL_gfx)
+  target_link_libraries(project_target PRIVATE SDL::SDL_gfx)
+
+See Also
+^^^^^^^^
+
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 cmake_policy(PUSH)

Modules/FindSDL_image.cmake

@@ -5,32 +5,107 @@
 FindSDL_image
 -------------
 
-Locate SDL_image library
+Finds the SDL_image library that loads images of various formats as SDL (Simple
+DirectMedia Layer) surfaces.
 
-This module defines:
+.. note::
 
-::
+  This module is specifically intended for SDL_image version 1.  Starting with
+  version 2.6, SDL_image provides a CMake package configuration file when built
+  with CMake and should be found using ``find_package(SDL2_image)``.  Similarly,
+  SDL_image version 3 can be found using ``find_package(SDL3_image)``.  These
+  newer versions provide :ref:`Imported Targets` that encapsulate usage
+  requirements.  Refer to the official SDL documentation for more information.
 
-  SDL_IMAGE_LIBRARIES, the name of the library to link against
-  SDL_IMAGE_INCLUDE_DIRS, where to find the headers
-  SDL_IMAGE_FOUND, if false, do not try to link against
-  SDL_IMAGE_VERSION_STRING - human-readable string containing the
-                             version of SDL_image
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
+``SDL_image_FOUND``
+  Boolean indicating whether the (requested version of) SDL_image library is
+  found.  For backward compatibility, the ``SDL_IMAGE_FOUND`` variable is also
+  set to the same value.
+
+``SDL_IMAGE_VERSION_STRING``
+  The human-readable string containing the version of SDL_image found.
+
+``SDL_IMAGE_INCLUDE_DIRS``
+  Include directories containing headers needed to use the SDL_image library.
+
+``SDL_IMAGE_LIBRARIES``
+  Libraries needed to link against to use the SDL_image library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
 
 For backward compatibility the following variables are also set:
 
-::
+``SDLIMAGE_FOUND``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_image_FOUND``, which has the same value.
+
+``SDLIMAGE_INCLUDE_DIR``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_IMAGE_INCLUDE_DIRS``, which has the same value.
+
+``SDLIMAGE_LIBRARY``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_IMAGE_LIBRARIES``, which has the same value.
+
+Examples
+^^^^^^^^
+
+Finding SDL_image library and creating an imported interface target for linking
+it to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL_image)
+
+  if(SDL_image_FOUND AND NOT TARGET SDL::SDL_image)
+    add_library(SDL::SDL_image INTERFACE IMPORTED)
+    set_target_properties(
+      SDL::SDL_image
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${SDL_IMAGE_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${SDL_IMAGE_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(project_target PRIVATE SDL::SDL_image)
+
+When working with SDL_image version 2, the upstream package provides the
+``SDL2_image::SDL2_image`` imported target directly.  It can be used in a
+project without using this module:
+
+.. code-block:: cmake
+
+  find_package(SDL2_image)
+  target_link_libraries(project_target PRIVATE SDL2_image::SDL2_image)
+
+Similarly, for SDL_image version 3:
 
-  SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
-  SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
-  SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
+.. code-block:: cmake
 
+  find_package(SDL3_image)
+  target_link_libraries(project_target PRIVATE SDL3_image::SDL3_image)
 
+See Also
+^^^^^^^^
 
-$SDLDIR is an environment variable that would correspond to the
-./configure --prefix=$SDLDIR used in building SDL.
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 cmake_policy(PUSH)
@@ -95,7 +170,7 @@ find_package_handle_standard_args(SDL_image
 # for backward compatibility
 set(SDLIMAGE_LIBRARY ${SDL_IMAGE_LIBRARIES})
 set(SDLIMAGE_INCLUDE_DIR ${SDL_IMAGE_INCLUDE_DIRS})
-set(SDLIMAGE_FOUND ${SDL_IMAGE_FOUND})
+set(SDLIMAGE_FOUND ${SDL_image_FOUND})
 
 mark_as_advanced(SDL_IMAGE_LIBRARY SDL_IMAGE_INCLUDE_DIR)
 

Modules/FindSDL_mixer.cmake

@@ -5,32 +5,99 @@
 FindSDL_mixer
 -------------
 
-Locate SDL_mixer library
+Finds the SDL_mixer library that provides an audio mixer with support for
+various file formats in SDL (Simple DirectMedia Layer) applications.
 
-This module defines:
+.. note::
 
-::
+  This module is specifically intended for SDL_mixer version 1.  Starting with
+  version 2.5, SDL_mixer provides a CMake package configuration file when built
+  with CMake and should be found using ``find_package(SDL2_mixer)``.  These
+  newer versions provide :ref:`Imported Targets` that encapsulate usage
+  requirements.  Refer to the official SDL documentation for more information.
 
-  SDL_MIXER_LIBRARIES, the name of the library to link against
-  SDL_MIXER_INCLUDE_DIRS, where to find the headers
-  SDL_MIXER_FOUND, if false, do not try to link against
-  SDL_MIXER_VERSION_STRING - human-readable string containing the
-                             version of SDL_mixer
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
+``SDL_mixer_FOUND``
+  Boolean indicating whether the (requested version of) SDL_mixer library is
+  found.  For backward compatibility, the ``SDL_MIXER_FOUND`` variable is also
+  set to the same value.
+
+``SDL_MIXER_VERSION_STRING``
+  The human-readable string containing the version of SDL_mixer found.
+
+``SDL_MIXER_INCLUDE_DIRS``
+  Include directories containing headers needed to use the SDL_mixer library.
+
+``SDL_MIXER_LIBRARIES``
+  Libraries needed to link against to use SDL_mixer.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
 
 For backward compatibility the following variables are also set:
 
-::
+``SDLMIXER_FOUND``
+  .. deprecated:: 2.8.10
+    Use ``SDL_mixer_FOUND``, which has the same value.
+
+``SDLMIXER_INCLUDE_DIR``
+  .. deprecated:: 2.8.10
+    Use ``SDL_MIXER_INCLUDE_DIRS``, which has the same value.
+
+``SDLMIXER_LIBRARY``
+  .. deprecated:: 2.8.10
+    Use ``SDL_MIXER_LIBRARIES``, which has the same value.
+
+Examples
+^^^^^^^^
+
+Finding SDL_mixer library and creating an imported interface target for linking
+it to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL_mixer)
+
+  if(SDL_mixer_FOUND AND NOT TARGET SDL::SDL_mixer)
+    add_library(SDL::SDL_mixer INTERFACE IMPORTED)
+    set_target_properties(
+      SDL::SDL_mixer
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${SDL_MIXER_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${SDL_MIXER_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(project_target PRIVATE SDL::SDL_mixer)
+
+When working with SDL_mixer version 2, the upstream package provides the
+``SDL2_mixer::SDL2_mixer`` imported target directly.  It can be used in a
+project without using this module:
 
-  SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
-  SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
-  SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
+.. code-block:: cmake
 
+  find_package(SDL2_mixer)
+  target_link_libraries(project_target PRIVATE SDL2_mixer::SDL2_mixer)
 
+See Also
+^^^^^^^^
 
-$SDLDIR is an environment variable that would correspond to the
-./configure --prefix=$SDLDIR used in building SDL.
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 cmake_policy(PUSH)
@@ -95,7 +162,7 @@ find_package_handle_standard_args(SDL_mixer
 # for backward compatibility
 set(SDLMIXER_LIBRARY ${SDL_MIXER_LIBRARIES})
 set(SDLMIXER_INCLUDE_DIR ${SDL_MIXER_INCLUDE_DIRS})
-set(SDLMIXER_FOUND ${SDL_MIXER_FOUND})
+set(SDLMIXER_FOUND ${SDL_mixer_FOUND})
 
 mark_as_advanced(SDL_MIXER_LIBRARY SDL_MIXER_INCLUDE_DIR)
 

Modules/FindSDL_net.cmake

@@ -5,31 +5,99 @@
 FindSDL_net
 -----------
 
-Locate SDL_net library
+Finds the SDL_net library, a cross-platform network library for use with the
+SDL (Simple DirectMedia Layer) applications.
 
-This module defines:
+.. note::
 
-::
+  This module is specifically intended for SDL_net version 1.  Starting with
+  version 2.1, SDL_net provides a CMake package configuration file when built
+  with CMake and should be found using ``find_package(SDL2_net)``.  These
+  newer versions provide :ref:`Imported Targets` that encapsulate usage
+  requirements.  Refer to the official SDL documentation for more information.
 
-  SDL_NET_LIBRARIES, the name of the library to link against
-  SDL_NET_INCLUDE_DIRS, where to find the headers
-  SDL_NET_FOUND, if false, do not try to link against
-  SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
+``SDL_net_FOUND``
+  Boolean indicating whether the (requested version of) SDL_net library is
+  found.  For backward compatibility, the ``SDL_NET_FOUND`` variable is also set
+  to the same value.
+
+``SDL_NET_VERSION_STRING``
+  The human-readable string containing the version of SDL_net found.
+
+``SDL_NET_INCLUDE_DIRS``
+  Include directories containing headers needed to use the SDL_net library.
+
+``SDL_NET_LIBRARIES``
+  Libraries needed to link against to use the SDL_net library.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
 
 For backward compatibility the following variables are also set:
 
-::
+``SDLNET_FOUND``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_net_FOUND``, which has the same value.
+
+``SDLNET_INCLUDE_DIR``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_NET_INCLUDE_DIRS``, which has the same value.
+
+``SDLNET_LIBRARY``
+  .. deprecated:: 2.8.10
+    Use the ``SDL_NET_LIBRARIES``, which has the same value.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+Examples
+^^^^^^^^
+
+Finding SDL_net library and creating an imported interface target for linking it
+to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL_net)
+
+  if(SDL_net_FOUND AND NOT TARGET SDL::SDL_net)
+    add_library(SDL::SDL_net INTERFACE IMPORTED)
+    set_target_properties(
+      SDL::SDL_net
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${SDL_NET_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${SDL_NET_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(project_target PRIVATE SDL::SDL_net)
+
+When working with SDL_net version 2, the upstream package provides the
+``SDL2_net::SDL2_net`` imported target directly.  It can be used in a project
+without using this module:
 
-  SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
-  SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
-  SDLNET_FOUND (same value as SDL_NET_FOUND)
+.. code-block:: cmake
 
+  find_package(SDL2_net)
+  target_link_libraries(project_target PRIVATE SDL2_net::SDL2_net)
 
+See Also
+^^^^^^^^
 
-$SDLDIR is an environment variable that would correspond to the
-./configure --prefix=$SDLDIR used in building SDL.
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 cmake_policy(PUSH)
@@ -94,7 +162,7 @@ find_package_handle_standard_args(SDL_net
 # for backward compatibility
 set(SDLNET_LIBRARY ${SDL_NET_LIBRARIES})
 set(SDLNET_INCLUDE_DIR ${SDL_NET_INCLUDE_DIRS})
-set(SDLNET_FOUND ${SDL_NET_FOUND})
+set(SDLNET_FOUND ${SDL_net_FOUND})
 
 mark_as_advanced(SDL_NET_LIBRARY SDL_NET_INCLUDE_DIR)
 

Modules/FindSDL_sound.cmake

@@ -5,63 +5,144 @@
 FindSDL_sound
 -------------
 
-Locates the SDL_sound library
+Finds the SDL_sound library, an abstract soundfile decoder for use in SDL
+(Simple DirectMedia Layer) applications.
 
+.. note::
 
+  This module is specifically intended for SDL_sound version 1.  Starting with
+  version 2.0.2, SDL_sound provides a CMake package configuration file when
+  built with CMake and should be found using ``find_package(SDL2_sound)``.
+  These newer versions provide :ref:`Imported Targets` that encapsulate usage
+  requirements.  Refer to the upstream SDL_sound documentation for more
+  information.
 
-This module depends on SDL being found and must be called AFTER
-FindSDL.cmake is called.
+.. note::
+  This module depends on SDL being found and must be called after the
+  :module:`find_package(SDL) <FindSDL>`.
 
-This module defines
+  Depending on how the SDL_sound library is built, it may require additional
+  dependent libraries to be found for this module to succeed.  These
+  dependencies may include MikMod, ModPlug, Ogg, Vorbis, SMPEG, FLAC, and Speex.
 
-::
+Result Variables
+^^^^^^^^^^^^^^^^
 
-  SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
-  SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
-  SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
-    to link against.
-  SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
-    flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
-    This is available mostly for cases this module failed to anticipate for
-    and you must add additional flags. This is marked as ADVANCED.
-  SDL_SOUND_VERSION_STRING, human-readable string containing the
-    version of SDL_sound
+This module defines the following variables:
 
+``SDL_sound_FOUND``
+  Boolean indicating whether the (requested version of) SDL_sound library is
+  found.  For backward compatibility, the ``SDL_SOUND_FOUND`` variable is also
+  set to the same value.
 
+``SDL_SOUND_VERSION_STRING``
+  The human-readable string containing the version of SDL_sound found.
 
-This module also defines (but you shouldn't need to use directly)
+``SDL_SOUND_LIBRARIES``
+  Libraries needed to link against to use the SDL_sound library.
 
-::
+Cache Variables
+^^^^^^^^^^^^^^^
 
-   SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
-   against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
+The following cache variables may also be set:
 
-And might define the following as needed
+``SDL_SOUND_INCLUDE_DIR``
+  The directory containing the ``SDL_sound.h`` and other headers needed to use
+  the SDL_sound library.
 
-::
+``SDL_SOUND_LIBRARY``
+  The name of just the SDL_sound library you would link against.  Use
+  ``SDL_SOUND_LIBRARIES`` for the link instructions and not this one.
 
-   MIKMOD_LIBRARY
-   MODPLUG_LIBRARY
-   OGG_LIBRARY
-   VORBIS_LIBRARY
-   SMPEG_LIBRARY
-   FLAC_LIBRARY
-   SPEEX_LIBRARY
+``MIKMOD_LIBRARY``
+  The path to the dependent MikMod library.
 
+``MODPLUG_LIBRARY``
+  The path to the dependent ModPlug library (libmodplug).
 
+``OGG_LIBRARY``
+  The path to the dependent Ogg library.
 
-Typically, you should not use these variables directly, and you should
-use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
-audio libraries (if needed) to successfully compile on your system.
+``VORBIS_LIBRARY``
+  The path to the dependent Vorbis library.
 
-Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
-would correspond to the ./configure --prefix=$SDLDIR used in building
-SDL.
+``SMPEG_LIBRARY``
+  The path to the dependent SMPEG library.
 
-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 selectionor set the CMake environment CMAKE_INCLUDE_PATH
-to modify the search paths.
+``FLAC_LIBRARY``
+  The path to the dependent FLAC library.
+
+``SPEEX_LIBRARY``
+  The path to the dependent Speex library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+  On macOS, setting this variable will prefer the Framework version (if found)
+  over others.  In this case, the cache value of ``SDL_LIBRARY`` would need to
+  be manually changed to override this selection or set the
+  :variable:`CMAKE_INCLUDE_PATH` variable to modify the search paths.
+
+``SDLSOUNDDIR``
+  Environment variable that works the same as ``SDLDIR``.
+
+``SDL_SOUND_EXTRAS``
+  This is an optional cache variable that can be used to add additional flags
+  that are prepended to the ``SDL_SOUND_LIBRARIES`` result variable.  This is
+  available mostly for cases this module failed to anticipate for and additional
+  flags must be added.
+
+Examples
+^^^^^^^^
+
+Finding SDL_sound library and creating an imported interface target for linking
+it to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL)
+  find_package(SDL_sound)
+
+  if(SDL_sound_FOUND AND NOT TARGET SDL::SDL_sound)
+    add_library(SDL::SDL_sound INTERFACE IMPORTED)
+    set_target_properties(
+      SDL::SDL_sound
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${SDL_SOUND_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${SDL_SOUND_LIBRARIES}"
+    )
+
+    # Append the SDL dependency as imported target to be transitively linked:
+    set_property(
+      TARGET SDL::SDL_sound
+      APPEND
+      PROPERTY INTERFACE_LINK_LIBRARIES SDL::SDL
+    )
+  endif()
+
+  target_link_libraries(project_target PRIVATE SDL::SDL_sound)
+
+When working with SDL_sound version 2, the upstream package provides the
+``SDL2_sound::SDL2_sound`` imported target directly.  It can be used in a
+project without using this module:
+
+.. code-block:: cmake
+
+  find_package(SDL2_sound)
+  target_link_libraries(project_target PRIVATE SDL2_sound::SDL2_sound)
+
+See Also
+^^^^^^^^
+
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 

Modules/FindSDL_ttf.cmake

@@ -5,31 +5,107 @@
 FindSDL_ttf
 -----------
 
-Locate SDL_ttf library
+Finds the SDL_ttf library that provides support for rendering text with TrueType
+fonts in SDL (Simple DirectMedia Layer) applications.
 
-This module defines:
+.. note::
 
-::
+  This module is specifically intended for SDL_ttf version 1.  Starting with
+  version 2.0.15, SDL_ttf provides a CMake package configuration file when built
+  with CMake and should be found using ``find_package(SDL2_ttf)``.  Similarly,
+  SDL_ttf version 3 can be found using ``find_package(SDL3_ttf)``.  These newer
+  versions provide :ref:`Imported Targets` that encapsulate usage requirements.
+  Refer to the official SDL documentation for more information.
 
-  SDL_TTF_LIBRARIES, the name of the library to link against
-  SDL_TTF_INCLUDE_DIRS, where to find the headers
-  SDL_TTF_FOUND, if false, do not try to link against
-  SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
+Result Variables
+^^^^^^^^^^^^^^^^
 
+This module defines the following variables:
 
+``SDL_ttf_FOUND``
+  Boolean indicating whether the (requested version of) SDL_ttf library is
+  found.  For backward compatibility, the ``SDL_TTF_FOUND`` variable is also set
+  to the same value.
+
+``SDL_TTF_VERSION_STRING``
+  The human-readable string containing the version of SDL_ttf found.
+
+``SDL_TTF_INCLUDE_DIRS``
+  Include directories containing headers needed to use SDL_ttf library.
+
+``SDL_TTF_LIBRARIES``
+  Libraries needed to link against to use SDL_ttf.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
 
 For backward compatibility the following variables are also set:
 
-::
+``SDLTTF_FOUND``
+  .. deprecated:: 2.8.10
+    Replaced with ``SDL_ttf_FOUND``, which has the same value.
+
+``SDLTTF_INCLUDE_DIR``
+  .. deprecated:: 2.8.10
+    Replaced with ``SDL_TTF_INCLUDE_DIRS``, which has the same value.
+
+``SDLTTF_LIBRARY``
+  .. deprecated:: 2.8.10
+    Replaced with ``SDL_TTF_LIBRARIES``, which has the same value.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``SDLDIR``
+  Environment variable that can be set to help locate an SDL library installed
+  in a custom location.  It should point to the installation destination that
+  was used when configuring, building, and installing SDL library:
+  ``./configure --prefix=$SDLDIR``.
+
+Examples
+^^^^^^^^
+
+Finding SDL_ttf library and creating an imported interface target for linking
+it to a project target:
+
+.. code-block:: cmake
+
+  find_package(SDL_ttf)
+
+  if(SDL_ttf_FOUND AND NOT TARGET SDL::SDL_ttf)
+    add_library(SDL::SDL_ttf INTERFACE IMPORTED)
+    set_target_properties(
+      SDL::SDL_ttf
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${SDL_TTF_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${SDL_TTF_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(project_target PRIVATE SDL::SDL_ttf)
+
+When working with SDL_ttf version 2, the upstream package provides the
+``SDL2_ttf::SDL2_ttf`` imported target directly.  It can be used in a project
+without using this module:
+
+.. code-block:: cmake
+
+  find_package(SDL2_ttf)
+  target_link_libraries(project_target PRIVATE SDL2_ttf::SDL2_ttf)
+
+Similarly, for SDL_ttf version 3:
 
-  SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
-  SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
-  SDLTTF_FOUND (same value as SDL_TTF_FOUND)
+.. code-block:: cmake
 
+  find_package(SDL3_ttf)
+  target_link_libraries(project_target PRIVATE SDL3_ttf::SDL3_ttf)
 
+See Also
+^^^^^^^^
 
-$SDLDIR is an environment variable that would correspond to the
-./configure --prefix=$SDLDIR used in building SDL.
+* The :module:`FindSDL` module to find the main SDL library.
 #]=======================================================================]
 
 cmake_policy(PUSH)